# Poll Card

> A social poll in a card. Pick one option or several (with a cap), vote, and the results slide in as bars with percentages, a check on your choice and the leader picked out. Shows total votes and time left, lets voters change or remove their vote, can show results before voting, and settles into final results with a winner once it closes.

- Slug: `poll-card`
- Category: [Cards](https://www.assembli.design/category/cards.md)
- Type: component
- Tags: poll, vote, survey, social, community, results, card, radio
- npm dependencies: lucide-react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/poll-card
- Page: https://www.assembli.design/components/poll-card

![Poll Card preview](https://www.assembli.design/thumbnails/poll-card-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `question` (required) | `string` |  |  |
| `options` (required) | `PollOption[]` |  |  |
| `multiple` | `boolean` | `false` | Checkboxes instead of radios. |
| `maxChoices` | `number` |  | With `multiple`, the most options a voter can pick. |
| `author` | `PollAuthor` |  |  |
| `postedAt` | `string` |  | A short label for when it was posted, e.g. "2h". |
| `endsAt` | `string \| Date` |  | When voting closes. Past this the poll shows final results. |
| `now` | `string \| Date` |  | The current time. Pass it on the server so the prerendered "time left" matches; otherwise the client's clock is used. |
| `closed` | `boolean` | `false` | Force the poll closed, regardless of `endsAt`. |
| `defaultValue` | `string[]` | `[]` | The viewer's vote, uncontrolled. An empty array means they haven't voted. |
| `value` | `string[]` |  | The viewer's vote, controlled. |
| `onVote` | `(ids: string[]) => void \| Promise<void>` |  | Called with the chosen option ids when the viewer votes, or with [] when they take it back. Return a promise to show a busy state. |
| `showResultsBeforeVoting` | `boolean` | `false` | Lets voters peek at the results before choosing. |
| `allowChange` | `boolean` | `true` | Lets voters change their mind while the poll is open. |
| `voters` | `number` |  | With `multiple`, how many people have voted (not counting the viewer). Shown instead of the vote total. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/poll-card/poll-card.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/poll-card
```

Registry item JSON: https://www.assembli.design/r/poll-card.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.