Survey File

This page details the contents of the survey.qmd file, where you define the main survey content of your survey.

Note

You do NOT need to render the survey.qmd file, and in fact we do not recommend doing so as the rendered output will not necessarily look like your final survey. Instead, to preview your survey you should locally run your app.

YAML header

The YAML header is at the top of the survey.qmd file. It contains some basic settings, like this:

---
format: html
echo: false
warning: false
---

The only required setting is format: html, as the document should render as an HTML document. The other settings are optional, though we recommend you keep them to ensure a good experience for your respondents. Typically you wouldn’t want warnings or the code defining the survey questions to be displayed in your survey - that’s what the echo: false and warning: false settings are for.

Changing the look and feel

Because the survey.qmd is a Quarto document, you can use any of the Quarto formatting options to change the look and feel of your survey.

For example, you can change the overall survey theme using the theme key:

---
theme: united # Any bootswatch theme 
---

There are 25 bootswatch themes to choose from. You can also provide a custom.scss file to further modify the theme, or even combine the two, e.g.:

---
theme: [united, custom.scss]
---

Progress bar

You can modify the survey progress bar with the barcolor and barposition keys, e.g.:

---
barcolor: "#768692"
barposition: top 
---

The barcolor key defines the color of the progress bar. It defaults to the primary theme color, but you can change it to any hex code you wish here to overwrite the theme color.

The barposition key defines the position of the progress bar. It defaults to top, but can also be changed to bottom or none (to remove the bar). The progress bar updates on every question the user clicks on, not pages.

The rest of the content in the survey.qmd file is the content you want in your survey, including pages, navigation buttons, and questions.

Adding pages

In surveydown, pages are defined using fences (:::), like this:

::: {#welcome .sd-page}

Page 1 content here

:::

::: {#page2 .sd-page}

Page 2 content here

:::

As you can see, we use three colon symbols :::, called a “fence”, to mark the start and end of pages. This notation is commonly used in Quarto for a variety of use cases, like defining subfigures in images.

In the starting fence, you need to define a page name (e.g. welcome and page2 in the example above) and you need to define the class as .sd-page. Then anything you put between the page fences will appear on that page.

Adding navigation buttons

To navigate to the next page, you need to insert a sd_next() function call inside a code chunk, like this:

```{r}
sd_next()
```

The above code chunk will create a “Next” button that goes on to the immediate next page. The button will look like this:

You can also send the user to other pages by just changing the value assigned to the next_page argument. For example, to send the user to a page with the id page3, you can use:

```{r}
sd_next(next_page = 'page3')
```

Finally, you can also change the label of the button by changing the label argument, like this:

```{r}
sd_next(label = 'Next page')
```

While the sd_next() function controls basic, static page navigation, you can conditionally override these controls using the sd_skip_forward() function in your server function. See the Conditional Survey Flow page for more details.

Adding questions

Every survey question is created using the sd_question() function inside a code chunk. The question type is defined by the type argument. For example, to add a multiple choice question, you could insert the following code chunk:

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

The above code chunk will create a multiple choice question that looks like this:

*

The sd_question() function can be used to create a variety of question types, like text input, select drop down choices, and more by changing the type argument (see the Questions Types page).

The function has many other arguments for customizing the look and feel of the question, such as the height and width (see the Question Formatting page).

By default all questions are optional, but you can make questions required in the server options (see the Server Options page for details).

Ending the survey

The simplest way to end a survey is to create a page with no sd_next() button on it. This will effectively serve as a ending page, because the respondent will not be able to navigate anywhere else once reaching a page with no next button.

For example, you may want to have a screen-out page that respondents are sent to if they answer a certain way on a question (e.g., see conditional survey flow. You can do this by creating a page with no sd_next() button on it, like this:

::: {#screenout .sd-page}

Sorry, you are not eligible for this survey.

You can close this window now.

:::

When a respondent reaches this page, they will not be able to navigate anywhere else, so the survey is over.

You can also add a button to end the survey programmatically using the sd_close() function inside a code chunk, like this:

```{r}
sd_close(label = 'Close window')
```

This will create a button with the label “Close window” that the respondent can click on to close the survey window. This button can be added anywhere in the survey, not necessarily on the last page - all it does is close the browser window.

Finally, you can also add a button to end the survey and redirect the respondent to another page. You can do this using the sd_redirect() function, like this:

sd_redirect(
  id     = "redirect",
  url    = "https://www.google.com",
  label  = "Redirect to Google",
  button = TRUE,
  newtab = TRUE
)

This will create a button with the label “Redirect to Google” that the respondent can click on to be redirected to Google. You can also customize the url to include url parameters. See the External Redirects page for more details.

Back to top