Upvotekit website widget

At a glance

• One tag: <script src="https://upvotekit.com/widget.js" data-project="your-project" async></script>. Replace your-project with your project's slug: the snippet in Settings → Embed already contains it, and it's the <slug> in your public board's address upvotekit.com/p/<slug>.
• Three display modes: panel (default), popover and inline. Pick one with data-display.
• Options are data-* attributes on the script tag. Everything has a sensible default; only data-project is required.
• A JavaScript API: window.Upvotekit(command, …) opens, closes and identifies, and lets you listen for events.
• Signed-in users: your server creates a short-lived embed token, your page passes it with Upvotekit('identify', token). Votes and posts are then linked to that user, and private boards become visible to them.
• Small and isolated: about 5 KB gzipped, no dependencies, no global variables besides Upvotekit, styles in a shadow root. Nothing else loads until the board is needed.
• No tracking: the widget sends no analytics.
• Everything the board shows comes from your project: colors, fonts, style, boards and moderation are set in Upvotekit, not in the tag.

Quick start

1. Copy the snippet. In Upvotekit, open Settings → Embed (or Developers → Embed). Pick a display mode and copy the tag. It looks like this:

   <script src="https://upvotekit.com/widget.js" data-project="your-project" async></script>
   

2. Paste it into your site. For panel and popover, paste it just before </body> on every page that should show the Feedback button (or in your site's global footer or layout). For inline, paste it where the board should appear.

3. Check your allowed origins. If Settings → Embed → Allowed embed origins lists any sites, add your website's origin there (for example https://www.example.com). If the list is empty, any site may show the board.

That's it. Reload your site and you'll see a Feedback button in the bottom-right corner.

Choose how it shows

Set data-display to one of three modes.

Panel

<script src="https://upvotekit.com/widget.js" data-project="your-project" async></script>

The panel closes with the close button, the Escape key, or a click on the dimmed page.

Popover

<script src="https://upvotekit.com/widget.js" data-project="your-project" data-display="popover" async></script>

The popover closes with the close button, the Escape key, or a click anywhere else on your page.

Inline

Paste the tag where the board should appear:

<h1>Feedback</h1>
<script src="https://upvotekit.com/widget.js" data-project="your-project" data-display="inline" async></script>

Or point it at an element with data-target (useful when your site only lets you add scripts in one place, such as the <head> or a tag manager):

<div id="feedback"></div>
<script src="https://upvotekit.com/widget.js" data-project="your-project" data-display="inline" data-target="#feedback" async></script>

An inline board:

• grows and shrinks with its content, so your page scrolls, not the board;
• loads when it scrolls into view (or right away with data-load="page");
• has no button and no open/close state. Upvotekit('open', { page: 'roadmap' }) switches its page and scrolls it into view; close and toggle do nothing.

Pick the starting page

data-page sets the page the board opens on:

Visitors can still move between pages with the board's own tabs.

Style the button

These apply to panel and popover:

The board itself takes its look (style preset, colors, fonts, corners, light or dark) from your project's Settings → Appearance.

Open it from your own buttons

Add data-upvotekit-trigger to any element on your page. Clicking it opens the board:

<button data-upvotekit-trigger>Send feedback</button>
<a href="#" data-upvotekit-trigger="roadmap">See our roadmap</a>

• A value names the page to open (feedback, submit, roadmap or changelog).
• It works for elements added later too, such as menus rendered by your framework.
• Combine with data-launcher="none" to show only your own buttons.
• For an inline board, a trigger scrolls to the board and switches its page.

Control when the board loads

The script itself is small. The board (an iframe with your project's pages) loads only when it's needed. data-load decides when:

Use open to keep pages as light as possible, and page when the board should appear instantly.

Identify signed-in users

By default, visitors are anonymous. They can still vote, and the board asks for an email address when it needs one (for example to post). If your site has its own sign-in, identify your users so their votes and posts are linked to them, they never type their email, and you see who they are in Upvotekit.

It takes two steps: your server creates an embed token, your page passes it to the widget.

1. Create a token on your server

Call POST /api/v1/embed-tokens with an API key that has the end_users:write scope. Create the key in Developers → API keys. Never put the API key in your web page: the token is the only thing the browser should see.

curl -X POST https://upvotekit.com/api/v1/embed-tokens \
  -H "Authorization: Bearer $UPVOTEKIT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "email": "[email protected]",
    "display_name": "Ada Lovelace",
    "company_external_id": "acme-inc",
    "company_name": "Acme Inc.",
    "mrr": 49.99
  }'

The response:

{ "data": { "token": "eyJhbGciOi…", "expires_at": "2026-10-01T13:00:00.000Z" } }

The same call in Node.js, for example in a route your page calls:

// GET /upvotekit-token on your server, for the signed-in user
const response = await fetch('https://upvotekit.com/api/v1/embed-tokens', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.UPVOTEKIT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ external_user_id: user.id, email: user.email, display_name: user.name }),
})
const { data } = await response.json()
return { token: data.token }

Body fields:

2. Pass the token to the widget

<script>
  window.Upvotekit=window.Upvotekit||function(){(Upvotekit.q=Upvotekit.q||[]).push(arguments)}
</script>
<script src="https://upvotekit.com/widget.js" data-project="your-project" async></script>
<script>
  fetch('/upvotekit-token')
    .then((r) => r.json())
    .then(({ token }) => Upvotekit('identify', token))
</script>

The first line is optional. It lets you call Upvotekit(…) before /widget.js has finished loading; the calls run as soon as it does.

If you render pages on the server, you can also put the token on the tag: data-token="eyJhbGciOi…".

Keep the user signed in

Tokens expire (after an hour by default). When the board notices, the widget fires auth-expired. Fetch a new token and identify again:

Upvotekit('on', 'auth-expired', async () => {
  const { token } = await fetch('/upvotekit-token').then((r) => r.json())
  Upvotekit('identify', token)
})

A new token reaches an open board without reloading it.

Sign out

Upvotekit('identify', null)

The board reloads as an anonymous visitor.

Private boards

A board set to Private (Settings → Boards) is shown only to identified users: it needs an embed token.

• Signed-out visitors don't see private boards at all. Public boards of the same project stay visible to them.
• Identified users see private boards, limited to board_ids if the token names any.
• This is enforced by Upvotekit's server, not by the widget, so a visitor can't get around it.

If all of your project's boards are private, a signed-out visitor would open an empty board. Add data-require-identify="true" and the widget shows nothing (no button, no inline board, nothing loaded) until you call Upvotekit('identify', token). Upvotekit('identify', null) hides it again.

<script src="https://upvotekit.com/widget.js" data-project="your-project" data-require-identify="true" async></script>

Control it from JavaScript

Every call goes through one function, Upvotekit(command, …arguments):

Wrong calls never break your page: they print a warning starting with [Upvotekit] in the browser console and do nothing.

Listen for events

Use Upvotekit('on', name, handler), or listen on window for a CustomEvent named upvotekit:<name> (the payload is in event.detail):

Upvotekit('on', 'feedback-created', ({ feedbackId, title }) => {
  showToast(`Thanks! We got "${title}".`)
})

window.addEventListener('upvotekit:vote-changed', (event) => {
  analytics.track('Voted', event.detail)
})

When the board is unavailable, the floating button hides itself. An inline board shows the board's "under maintenance" message.

Security and privacy

• Allowed embed origins. Settings → Embed lists the sites that may show your board. If the list is empty, any site may. If it isn't, browsers block the board on other sites, and the widget prints a console warning naming the origin to add. Enter origins as scheme, host and optional port: https://www.example.com, http://localhost:3000.
• Content Security Policy. If your site sends a CSP header, allow Upvotekit in script-src (for /widget.js) and frame-src (for the board): for example script-src 'self' https://upvotekit.com; frame-src https://upvotekit.com.
• Tokens. Create them only on your server, keep them short-lived, and never expose your API key in the browser. A token is scoped to one project and one user and grants no admin rights.
• Spam protection. Anonymous posts can be checked by Cloudflare Turnstile if the project has it turned on. Requests from identified users (with a token) skip it.
• Isolation. The board runs in an iframe on Upvotekit's domain, so it can't read your page, and your page can't read it. The widget only accepts messages from that iframe.
• No analytics. The widget doesn't track visitors or send anything to analytics services.

Recipes

Plain HTML, or any site builder

Paste the tag into your site's "custom code", "footer code" or "before </body>" field (WordPress, Webflow, Framer, Squarespace, Shopify themes all have one). For an inline board, use an "embed" or "HTML" block where the board should appear.

React

import { useEffect, useRef } from 'react'

const WIDGET = 'https://upvotekit.com/widget.js'

// <FeedbackWidget project="your-project" display="popover" token={token} />
export function FeedbackWidget({ project, display = 'panel', token }) {
  const slot = useRef(null)

  useEffect(() => {
    window.Upvotekit = window.Upvotekit || function () { (window.Upvotekit.q = window.Upvotekit.q || []).push(arguments) }
    const script = document.createElement('script')
    script.src = WIDGET
    script.async = true
    script.dataset.project = project
    script.dataset.display = display
    // An inline board appears right after its script tag, so put the tag in this component.
    ;(display === 'inline' ? slot.current : document.body).appendChild(script)
    return () => {
      window.Upvotekit?.('destroy')
      script.remove()
    }
  }, [project, display])

  useEffect(() => {
    if (token) window.Upvotekit?.('identify', token)
  }, [token])

  return <div ref={slot} />
}

Next.js

Use the React component above in a client component ('use client') that you render in your root layout for panel/popover, or on a page for inline. Fetch the token from a route handler that calls POST /api/v1/embed-tokens with the API key from your server environment.

Vue and Nuxt

<script setup>
const props = defineProps({ project: String, display: { type: String, default: 'panel' }, token: String })
const slot = ref(null)
let script

onMounted(() => {
  window.Upvotekit = window.Upvotekit || function () { (window.Upvotekit.q = window.Upvotekit.q || []).push(arguments) }
  script = document.createElement('script')
  script.src = 'https://upvotekit.com/widget.js'
  script.async = true
  script.dataset.project = props.project
  script.dataset.display = props.display
  ;(props.display === 'inline' ? slot.value : document.body).appendChild(script)
})
watch(() => props.token, (token) => token && window.Upvotekit?.('identify', token), { immediate: true })
onBeforeUnmount(() => {
  window.Upvotekit?.('destroy')
  script?.remove()
})
</script>

<template><div ref="slot" /></template>

Single-page apps

The widget lives on <body> and survives your app's route changes, so add it once in your app shell. If you add it from a component, call Upvotekit('destroy') when that component unmounts, as in the recipes above.

Google Tag Manager

Add a Custom HTML tag with the script tag and fire it on all pages. For an inline board, add data-target pointing at an element on the page, since the tag manager inserts the script elsewhere.

A feedback page with the roadmap one click away

<nav>
  <a href="#" data-upvotekit-trigger="feedback">Requests</a>
  <a href="#" data-upvotekit-trigger="roadmap">Roadmap</a>
  <a href="#" data-upvotekit-trigger="changelog">What's new</a>
</nav>
<div id="board"></div>
<script src="https://upvotekit.com/widget.js" data-project="your-project" data-display="inline" data-target="#board" async></script>

Mobile and accessibility

• On screens narrower than 640 pixels, the panel and the popover fill the screen, and your page doesn't scroll behind them.
• The button is a real <button> with aria-expanded. The panel and popover are dialogs with a label. When they open, focus moves to their close button; when they close, focus returns to where it was.
• Escape closes them.
• With "reduce motion" turned on in the operating system, nothing slides or fades.
• The widget's own styles live in a shadow root: your CSS can't break it, and it can't change your page.

Troubleshooting

Reference

Attributes

Commands

open, close, toggle, identify, on, off, destroy. See "Control it from JavaScript".

Events

ready, open, close, navigate, resize, feedback-created, vote-changed, auth-expired, unavailable, open-external. See "Listen for events".

Limits

• One widget per page, showing one project.
• The script and the board always load from upvotekit.com, even when your public board has a custom domain.
• There is no npm package yet; load the script tag as shown.

The plain iframe

If you'd rather size and place the board yourself, embed it directly:

<iframe src="https://upvotekit.com/embed/your-project/feedback" title="Feedback" style="width:100%;min-height:640px;border:0"></iframe>

Replace feedback with submit, roadmap or changelog for another page. Add ?token= with an embed token to identify the user. The iframe doesn't resize itself; the widget's inline mode does the same with automatic height and is the recommended way.