Docs · Widget

Configuration

The widget is configured entirely through data-* attributes on the <script> tag. No JavaScript API. No runtime config object. Set it once and forget it.

Required attributes

Attribute	Value	Notes
`data-workspace`	Your workspace slug	Public, read-scoped. Safe in client HTML.

Optional attributes

Attribute	Default	Values	Notes
`data-theme`	`auto`	`auto` · `light` · `dark`	`auto` follows the customer's `prefers-color-scheme`.
`data-position`	`bottom-right`	`bottom-right` · `bottom-left` · `top-right` · `top-left`	Where the bell button anchors.
`data-accent`	workspace setting	Any CSS color (hex, oklch, rgb)	Overrides the workspace accent for this embed only.
`data-radius`	`md`	`sm` · `md` · `lg`	Corner rounding for the popover.
`data-hide-bell`	—	presence-only	Hides the floating bell. Use with a custom trigger — see below.
`data-lang`	auto-detected	`en` · `pt-BR` · `es` · `fr` · `de`	UI strings for the bell, popover, and wall. See Localization for the fallback chain.

Full example

<script
  src="https://showkit.dev/api/widget/v1.js"
  data-workspace="acme"
  data-theme="dark"
  data-position="bottom-left"
  data-accent="#7c3aed"
  data-lang="pt-BR"
  defer
></script>

Custom trigger button

Want the bell to live inside your own header instead of floating? Add data-hide-bell to suppress the default button, then call window.ShowKit.open() from your own click handler.

<button onclick="window.ShowKit.open()">
  What's new
</button>

Localization

The widget ships five locales: en, pt-BR, es, fr, de. All five dictionaries are inline in the bundle, so locale switching is synchronous — no extra request, no flash of English content.

The active locale is resolved in this order, first match wins:

data-lang on the script tag (e.g. data-lang="pt-BR") — explicit override per install.
The lang attribute on your page's <html> element — most apps that ship multilingual UIs already set this, and the widget picks it up automatically.
en as the final fallback.

Unsupported tags fall back by language prefix: pt-PT → pt-BR, en-GB → en, fr-CA → fr. A locale we don't ship yet (e.g. ja) falls all the way through to en.

What's translated: the bell aria-label, popover header, subscribe form, empty / loading / error states, "Powered by ShowKit" footer, the testimonial wall's empty-state copy. Customer-authored content (changelog entries, testimonial bodies, tags) is never auto-translated — you write it in whatever language your audience reads.

Versioning

The widget is versioned at the URL. /api/widget/v1.js is the stable v1 contract — breaking changes ship as /v2/. Pin to a major version; we'll never silently change semantics under you.