Getting Started

This page covers everything you need to get started making a survey with surveydown.

Overview

Every surveydown survey is composed of a survey and an app, defined in two separate files:

  • survey.qmd: A Quarto document that contains the survey content (pages, questions, etc), which renders to an HTML file.
  • app.R: An R script defining a Shiny app that contains the global settings (libraries, database configuration, etc.) and server configuration options (e.g., conditional page skipping / question display, etc.).

These files must be named survey.qmd and app.R.

The surveydown R package provides a set of functions for defining the survey content and configuration options. Each function starts with sd_ to make them easy to identify.

The platform is based on some basic principles:

  • Add content to your survey.qmd file using markdown text (or in RStudio use the visual editor).
  • Define survey questions in R code chunks with the sd_question() function.
  • Define pages using fences (:::), with navigation buttons handled using the sd_next() function.
  • Add rich functionality to your survey using a variety of Server Options in the server() function in the app.R file.
  • Apply Conditional Logic to question display with sd_show_if() or page navigation with sd_skip_forward().
  • Store your respondent data in a database (see Storing Data).

This approach ensures a flexible survey platform that is fully reproducible and easy to customize.

The remaining steps on this page will guide you through the process of creating a surveydown survey.

1. Install

Install R & Quarto

You need both:

We also recommend working with an IDE that has good support for R, Quarto, and Shiny.

RStudio is great, and we also like VSCode and Positron.

Install the {surveydown} R package

You can install {surveydown} from CRAN in your R console:

install.packages("surveydown")

or you can install the development version from GitHub:

# install.packages("pak")
pak::pak("surveydown-dev/surveydown")

Load the package with:

You can also check which version you have installed:

surveydown::sd_version()

2. Start with a template

Note

Every survey created with surveydown should be in its own separate project folder.

We recommend starting with a template to build your first surveydown survey. In the R console, run the following to to setup a generic template survey:

surveydown::sd_create_survey()

You can also specify where you want the template survey to be created using the path argument, and you can also specify which template to use with the template argument, like this:

surveydown::sd_create_survey(
  path     = "path/to/folder",
  template = "question_types"
)

The default is template = "default", but you can specify other templates. See the Templates page for an overview of all currently available templates.

3. Add survey content

Survey content is edited in the survey.qmd file. See the Basic Components page for more details on how to add more content to a surveydown survey. At a minimum, you can add pages and questions like this:

  • Add pages with fences, like this:

    ::: {.sd_page id=page1}

Page 1 content here

:::

  • Add questions with the sd_question() function in code chunks (see the Question Types page for more on the types of questions supported). For example, here’s a multiple choice question:

    ```{r}
sd_question(
  type  = 'mc',
  id    = 'penguins',
  label = "Which is your favorite type of penguin?",
  option = c(
    'Adélie'    = 'adelie',
    'Chinstrap' = 'chinstrap',
    'Gentoo'    = 'gentoo'
  )
)
```
    *

4. Add control options

In the server() function in the app.R file, add rich functionality to your survey using a variety of Server Options or Conditional Logic.

5. Setup your database connection

Setup your database connection using the sd_db_config() function. Once your configuration credentials are created (they get saved in a .env file), make a connection to your database using the sd_db_connect() function in the global settings at the top of the app.R file. You can also use sd_db_connect(ignore = TRUE) to run the survey without storing data. See the Storing Data page for more details.

6. Locally preview

Preview your survey by clicking the “Run App” button in RStudio or in your R console running the runApp() command.

7. Deploy

Deploy your survey by hosting it on your favorite server, like shinyapps.io, HuggingFace, Posit Connect Cloud, Heroku, etc. See the Deployment page for more details.

Back to top