# Discourse Surveys

**URL:** https://meta.discourse.org/t/discourse-surveys/308679
**Category:** Plugin
**Tags:** official, experimental, surveys
**Created:** [May 20, 2024, 9:46am UTC](https://meta.discourse.org/t/discourse-surveys/308679 "2024-05-20T09:46:58Z")
**Posts on this page:** 1
**Showing post:** 1

<div class="post-metadata">

### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [May 20, 2024, 9:46am UTC](https://meta.discourse.org/t/discourse-surveys/308679/1 "2024-05-20T09:46:58Z")

</div>

| | | |
| --- | --- | --- |
| :discourse2: | **Summary** | **Discourse Surveys** plugin allows you to create surveys directly within your Discourse forum posts using simple Markdown syntax. |
| 🛠 | **Repository Link** | [https://github.com/discourse/discourse-surveys](https://github.com/discourse/discourse-surveys) |
| 📖 | **Install Guide** | [How to install plugins in Discourse](https://meta.discourse.org/t/install-plugins-in-discourse/19157) |

The Discourse Surveys Plugin allows you to create surveys directly within your Discourse forum posts using simple Markdown syntax. The plugin currently supports a variety of question types such as radio buttons, checkboxes, dropdowns, number inputs, text areas, star ratings, and thumbs up/down ratings.

## Features

- **7 Different Field Types** : Radio buttons, checkboxes, dropdowns, text areas, number selection, star ratings, and thumbs up/down

- **Required/Optional Fields** : Mark fields as required to ensure completion

- **Emoji Support** : Use emojis in your survey options

- **Markdown Support** : Rich text formatting in questions and options

- **User Authentication** : Automatic login prompts for anonymous users

- **Response Tracking** : Prevents duplicate submissions from the same user

- **Permission Aware** : Respects topic and category permissions

- **Mobile Responsive** : Works seamlessly on all devices

## Usage

### Basic Survey Structure

All surveys must be wrapped in `[survey]` tags:

```markdown

[survey name="my-survey" title="Customer Feedback Survey"]

<!-- Survey fields go here -->

[/survey]

```

### Survey Attributes

- `name`: Unique identifier for the survey (defaults to “survey”)

- `title`: Optional title displayed at the top of the survey

- `public`: Set visibility (future feature)

- `status`: Survey status (future feature)

### Field Types

#### 1. Radio Buttons (Single Choice)

```markdown

[radio question="What is your favorite color?"]

- Red

- Blue

- Green

- Yellow

[/radio]

```

#### 2. Checkboxes (Multiple Choice)

```markdown

[checkbox question="Which features do you use? (Select all that apply)"]

- Email notifications

- Mobile app

- Desktop notifications

- API access

[/checkbox]

```

#### 3. Dropdown Selection

```markdown

[dropdown question="What is your age group?"]

- Under 18

- 18-24

- 25-34

- 35-44

- 45-54

- 55+

[/dropdown]

```

#### 4. Text Area (Long Form Text)

```markdown

[textarea question="Please provide detailed feedback:" required="false"]

[/textarea]

```

#### 5. Number Selection

```markdown

[number question="Rate this feature from 1-10:" min="1" max="10"]

[/number]

```

#### 6. Star Rating

```markdown

[star question="How would you rate your overall experience?"]

[/star]

```

#### 7. Thumbs Up/Down

```markdown

[thumbs question="Would you recommend this to others?"]

[/thumbs]

```

### Field Attributes

All field types support these attributes:

- `question`: The question text (required)

- `required`: Whether the field must be filled (`true`/`false`, defaults to `true`)

- `min`: Minimum value for number fields

- `max`: Maximum value for number fields

### Complete Example

### Basic Survey Markdown

Here is a basic example of survey Markdown including all available fields:

```plaintext
[survey name="awesome-survey-thumbs" title="Awesome Survey"]

[radio question="Choose any one option:"]
- cat
- dog
[/radio]

[checkbox question="Choose multiple options:"]
- red
- blue
- green
[/checkbox]

[dropdown question="Gender:"]
- Male
- Female
[/dropdown]

[number question="Rate this survey from 1 to 10:"]
[/number]

[textarea question="What is your feedback about xyz?" required="false"]
[/textarea]

[star question="How would you rate overall experience?"]
[/star]

[thumbs question="Were you satisfied with our services?"]
[/thumbs]

[/survey]

```

### Survey Rendering

Below is an example of how the above Markdown renders in Discourse:

 ![awesome-survey](https://global.discourse-cdn.com/meta/original/4X/8/4/3/8435f2d7f81e20727b205b4f5b5bc72a4724c553.png)

## Advanced Usage

### Using Emojis in Options

```markdown

[radio question="Choose your favorite animal:"]

- 🐈 Cat

- 🐶 Dog

- 🐦 Bird

- 🐠 Fish

[/radio]

```

### Markdown Formatting in Questions

```markdown

[radio question="Which **programming language** do you prefer?"]
- JavaScript
- Python
- Ruby
- Go
[/radio]

[checkbox question="Select your *favorite* features:"]
- Speed
- Security
- Ease of use
[/checkbox]

[textarea question="Please read our [guidelines](https://example.com) and provide feedback:"]
[/textarea]

```

Supported formatting:

- **Bold** : ` **text** `
- _Italic_: `*text*`
- ~~Strikethrough~~ : ` ~~text~~ `
- `Inline code`: ``code``
- [Links](https://example.com): `[text](url)`

### 

### Mixed Required and Optional Fields

```markdown

[survey name="mixed-survey"]

[radio question="What is your role?" required="true"]

- Developer

- Designer

- Manager

- Other

[/radio]

[textarea question="Any additional thoughts?" required="false"]

[/textarea]

[/survey]

```

## Survey Results

Currently, this plugin does not have any backend UX to view the survey results directly. Instead, you can rely on [Data Explorer](https://meta.discourse.org/t/32566?silent=true) queries to fetch and analyze survey responses. Here is an example query:

```sql
-- [params]
-- text :survey_name = survey

SELECT
  s.id,
  s.name,
  s.post_id,
  sf.question,
  COALESCE(sr.value, sfo.html) AS value,
  sr.user_id,
  sr.created_at AS responded_at
FROM
  surveys s
  JOIN survey_fields sf ON sf.survey_id = s.id
  JOIN survey_responses sr ON sr.survey_field_id = sf.id
  LEFT JOIN survey_field_options sfo ON sfo.id = sr.survey_field_option_id
WHERE
  s.name = :survey_name
ORDER BY
  s.id DESC

```

## Permissions and Security

- **Login Required** : Anonymous users must log in before submitting responses

- **One Response Per User** : Each user can only submit one response per survey

- **Topic Permissions** : Users must have read access to the topic to view surveys

- **Posting Permissions** : Users must have posting permissions in the topic to submit responses

- **Archived Topics** : Surveys in archived topics cannot accept new responses

- **Deleted Posts** : Surveys in deleted posts are no longer accessible

## Limitations

- Only one survey is allowed per post

- Survey structure cannot be modified after receiving responses

- All survey field questions must be unique within a single survey

- Survey field questions cannot be blank

## Technical Details

### Database Schema

The plugin creates four main database tables:

- `surveys`: Main survey records

- `survey_fields`: Individual fields within surveys

- `survey_field_options`: Options for choice-based fields

- `survey_responses`: User responses to survey fields

### Styling

The plugin includes responsive CSS that adapts to your theme. Custom styling can be added by targeting these CSS classes:

- `.survey` - Main survey container

- `.survey-field` - Individual field wrapper

- `.field-[type]` - Specific field type containers

- `.submit-response` - Submit button

> Last edited by @techAPJ 2026-02-04T12:32:36Z
> 
> > **Check document**
> >
> > Perform check on document:

---

_[View the full topic](https://meta.discourse.org/t/discourse-surveys/308679)._