Polls

A lightweight, client-side voting widget: define a poll, render it into a container, and let visitors click to vote. Results are stored per-browser.

💡 Site-only module. onigiri-polls.js ships with this documentation site (in static/js/), not the core framework repository.

Client-side only. Votes are stored in Onigiri.storage (falling back to nothing if unavailable) - they live in the visitor's own browser, not on a server. Two different visitors voting on the "same" poll do not see each other's votes, and votes are not tamper-proof against someone editing their own browser storage. For a real, shared voting feature, use this as the front-end and wire vote()/getResults() up to your own backend.

Quick Start

1. Include the Module

<script src="/static/js/onigiri-storage.js"></script>
<script src="/static/js/onigiri-polls.js"></script>

onigiri-storage.js is optional but recommended - without it, votes reset on every page load.

2. Add a Container

<div data-poll="favorite-feature"></div>

3. Create and Mount the Poll

Onigiri.polls.init();

Onigiri.polls.create('favorite-feature', {
    question: 'Which feature should we build next?',
    options: [
        { id: 'directives', label: 'Declarative directives' },
        { id: 'state', label: 'Shared state management' },
        { id: 'resource', label: 'REST resource models' }
    ]
});

Onigiri.polls.mount('favorite-feature');

✅ That's it! Clicking an option casts a vote and re-renders the poll with live percentages.

API Reference

Configuration Options

Option	Type	Default	Description
`storageKey`	String	'onigiri_poll_votes'	Storage key used to persist votes
`animationDuration`	Number	300	Reserved for future use
`allowMultipleVotes`	Boolean	false	Allow the same browser to vote more than once
`showResults`	Boolean	true	Reserved for future use - results currently always show once a vote is cast

Methods

Onigiri.polls.init(options)

Merges config, loads any previously stored votes, and binds a delegated click handler for .poll-vote-btn elements.

Onigiri.polls.create(id, options)

Registers a poll definition. options.options is an array of { id, label } objects.

Onigiri.polls.mount(id)

Renders the poll into the matching [data-poll="id"] container.

Onigiri.polls.vote(pollId, optionId)

Casts a vote. Returns false without recording anything if the poll doesn't exist or the visitor has already voted and allowMultipleVotes is off. Normally you won't call this directly - clicking a rendered option button does it for you.

Onigiri.polls.getResults(pollId)

Returns { total, options: [{ id, label, votes, percentage }] }, sorted by vote count descending.

Events

Event	Fired when
`onigiri:poll:voted`	A vote is cast (`detail: { pollId, optionId }`)

Security Notes

Poll questions and option labels are HTML-escaped before rendering (via Onigiri.security.sanitizeHTML when loaded). If you build poll definitions from a CMS field or translation file, this keeps an edited string from injecting markup.
Because voting is entirely client-side, treat results as informal/anecdotal rather than authoritative - see the note above.