README.md

slidev-component-poll

Poll and quiz component for Slidev.

See below for more examples.

Installation

npm i slidev-component-poll

Slidev Configuration

Define this package into your slidev addons.

In your slides metadata (using Front Matter):

---
addons:
  - slidev-component-poll
---

Or in your package.json:

{
  "slidev": {
    "addons": ["slidev-component-poll"]
  }
}

Using serverRef

slidev-component-poll can use built-in slidev capabilities to allow communication with multiple clients.

By using serverRef, the communication with multiple clients is only possible in dev mode!

This won't work if you build and deploy to a static host.

To use serverRef you will need to define the default value in your own project.

For that you need to create a vite.config.ts file with (see here for more information):

import { defineConfig } from "vite";

export default defineConfig({
  slidev: {
    serverRef: {
      state: {
        poll: {},
        pollUsers: {},
      },
    },
  },
});

Using a server

You can use a both:

• slidev-addon-sync
• and slidev-sync-server

to allow communication with multiple clients that will works for static builds.

This addon use 2 channels for the state:

• poll: state containing the poll results
• pollUsers: state containing the poll user names

So you will need to configure slidev-addon-sync in your markdown file Front Matter with the following syncStates configuration:

---
syncStates:
  poll:
    presenter: false
    init: false
  pollUsers:
    presenter: false
  # Add the following lines if you want to also sync slidev channels
  shared: ["page", "clicks", "cursor", "lastUpdate"]
  drawings: true
---

Anonymous

If you prefer that users answer polls anonymously, or prefer to skip the step of defining a name when answering polls, add in the Front Matter:

---
pollSettings:
  anonymous: true
---

Components

You can create a poll by using the Poll component.

Poll

All in one component for poll:

<Poll
  question="What is your favorite color ?"
  :answers="['Red', 'Green', 'Blue']"
/>

Or with markdown answers:

<Poll question="What is your favorite color ?">

**Red**

**Green**

**Blue**

</Poll>

More advanced example:

<Poll question="What is your favorite color ?">

```js
() => 'Red';
```

```js
() => 'Green';
```

```js
() => 'Blue';
```

</Poll>

Parameters:

• answers (string[]): The available answers to the question (can also be provided using the default slot).
• clearable (boolean, default: false): Can the poll be cleared after being closed ? (results will be cleared and poll can be reopened again). For controlled polls only.
• controlled (boolean, default: false): If true the poll will not be opened at the start, use controls to open and close the poll (see below for more information).
• correctAnswer (number | number[]): Highlight the corresponding answer(s) in the results (index starts at 0).
• displayResults ('poll' | 'quiz' | 'publicQuiz', default 'quiz'): Display results as poll or quiz (see below for more information).
• editable (boolean, default: false): Can someone's answer be edited by this same person ?
• id ('string'): Unique identifier for poll (if not provided, the system will generate an id based on the page number).
• multiple (boolean, default: false): Can someone select multiple answers (displays checkbox instead of radio buttons).
• question (string, required): The question displayed as title.
• reOpenable (boolean, default: false): Can the poll be reopened after being closed ? (old results are kept).
• showResults ('free' | 'auto' | 'none', default 'auto'):
  • 'free': User can see results before submitting
  • 'auto': Results are only shown after user submission
  • 'none': Results are only accessible for user that have access to controls

Poll and quiz

You can use this addon to either create polls or quizzes mostly base on the displayResults props.

Here is an example when displayResults="poll" (left side show slideshow view and right side show presenter view).

• Poll not answered:
• Poll results (when answered):

Code example:

<Poll question="What is your favorite color ?" :answers="['Red', 'Green', 'Blue']" displayResults="poll" />

Here is an other example when displayResults="quiz" or displayResults="publicQuiz".

• Quiz not answered:
• Quiz results (when answered):

Code example:

<Poll question="What is your favorite color ?" :answers="['Red', 'Green', 'Blue']" correctAnswer="0" />

People names will be shown in front of the results for the presenter or if displayResults="publicQuiz".

Controlled forms

When using controlled=true the poll can be controlled meaning that its state can be changed.

The poll can have three state:

• CLEARED: Starting state, no results recorded and no result can be recorded, waiting to be opened.
• OPEN: Poll is open, and results can be received.
• CLOSED: Poll is closed, and results can not be received anymore.

Here is an example when controlled=true and clearable=true (left side show slideshow view and right side show presenter view).

• Poll is not yet open:
• Poll is open:
• Answer has been submitted:
• Poll is closed:

If you run the slidev server with remote access (and you should if you don't use a server but want other people to answer your polls), then you can control the state of the poll from the presenter view.

When remote control is enabled, the presenter button is not shown, so people does not have direct access to the presenter view.

But anyone who tap the presenter view URL in its browser can access the presenter view, and then control the state of your poll.

If you want to prevent that, you can start the server with --remote=[your_password] and in that case the presenter view is a little more secured.

When using a password, the controls will also be displayed on the slideshow but only if the password query parameter in the URL is correct.

We can sum up the following cases:

• slideshow view without password (or wrong password): controls are not shown
• slideshow view with correct password (if any is set): controls are shown
• presenter view: controls are shown