---
title: "Ui: behaviour"
description: "smabar plugin reference: Ui: behaviour"
canonical: "https://smabar.com/docs/plugin-ref-ui-behaviour/"
lang: en
---

# Ui: behaviour

> smabar plugin reference: Ui: behaviour

Canonical HTML version: https://smabar.com/docs/plugin-ref-ui-behaviour/ · Language: en · Publisher: smabar (https://smabar.com)

---

[Build my plugin](https://smabar.com/build-my-plugin.md) · [All references](https://smabar.com/docs/plugin-ref-index.md) · [Install the ZIP](https://smabar.com/docs/install-plugin-zip.md)

Source: smabar 1.5.0, revision `a019f2563965edc37a5e8d84742ea1ff2fa6f824`. [Export metadata and checksums](https://smabar.com/plugin-reference/export.json).

This is an offline reference. MCP calls quoted below describe the connected workflow; use the linked documents and create local files instead. Live state, installed plugins, available providers and the user's active theme are unknown. Never claim a live check.

Read with [styling](https://smabar.com/docs/plugin-ref-styling.md) and [examples](https://smabar.com/docs/plugin-ref-examples.md).

## what

```json
"Markup hooks the SHELL implements for you. A plugin never ships JavaScript — its HTML is rendered inside the bar's own privileged origin, so a <script> is refused. These attributes are how you get behaviour anyway: write the markup, the shell runs the code. Everything below works in a flyout, a popup and a tile."
```

## stateNote

```json
"The hooks are stateless: the state lives in the DOM. A re-render replaces your markup, so a sort order or an open menu is lost when the HTML you render CHANGES. Render identical HTML and it is kept; input, select and textarea controls with data-field keep their user-edited value and focus, and derived behavior such as filtering is re-applied."
```

## hooks

```json
[
  {
    "hook": "data-sb-temporal",
    "what": "Opt-in themed date/time field on an input of type date, time, or datetime-local. Keeps its native ISO value, data-field, required/min/max/step validation and label. Date selection closes the calendar immediately; combined fields keep their time. The separate 24-hour time editor commits with Apply time or Enter. Escape or clicking outside cancels the time draft; Clear removes the value. Empty combined fields use today/current local time for the other part when first selected. Inline panels expand inside the flyout (no OS popup or JavaScript). Minute precision; use native time/datetime-local for sub-minute input. Use a visible label, an optional/required cue and a timezone hint for local datetimes. All internal buttons are type=button, so choosing a date/time never submits the plugin form.",
    "example": "<div class=\"sb-field-stack\"><label class=\"sb-label\" for=\"appointment\">Appointment <span class=\"sb-muted\">optional</span></label><input class=\"sb-input\" id=\"appointment\" data-field=\"appointment\" data-sb-temporal type=\"datetime-local\" aria-describedby=\"appointment-hint\"><p class=\"sb-field__hint\" id=\"appointment-hint\">Your local date and time. Clear to leave unset.</p></div>"
  },
  {
    "hook": "data-sb-copy",
    "what": "Button copies the text of the element its CSS selector names (scoped to your own tile). data-sb-copy-text copies the literal attribute value instead. Adds .is-copied for 1.5s and announces the result.",
    "example": "<button class=\"sb-btn sb-btn--sm\" data-sb-copy=\"#addr\">Copy</button>"
  },
  {
    "hook": "data-sb-number",
    "what": "Wrapper around an <input type=\"number\"> plus [data-sb-number-down] / [data-sb-number-up] buttons; they step the value, respect min/max/step and disable themselves at the bounds.",
    "example": "<div class=\"sb-number\" data-sb-number><button class=\"sb-number__btn\" data-sb-number-down>−</button><input class=\"sb-input\" type=\"number\" value=\"1\" min=\"0\" max=\"9\" data-field=\"n\"><button class=\"sb-number__btn\" data-sb-number-up>+</button></div>"
  },
  {
    "hook": "data-sb-password-toggle",
    "what": "Button inside .sb-password flips its input between password and text and mirrors the state into aria-pressed.",
    "example": "<div class=\"sb-password\"><input class=\"sb-input\" type=\"password\" data-field=\"pw\"><button class=\"sb-password__toggle\" data-sb-password-toggle aria-pressed=\"false\" aria-label=\"Show\"></button></div>"
  },
  {
    "hook": "data-sb-range",
    "what": "Wrapper around an <input type=\"range\">: paints the accent fill up to the thumb and writes the value into .sb-range-wrap__bubble. data-sb-range-unit appends a unit.",
    "example": "<div class=\"sb-range-wrap\" data-sb-range data-sb-range-unit=\"%\"><input class=\"sb-range\" type=\"range\" value=\"40\" data-field=\"level\"><output class=\"sb-range-wrap__bubble\"></output></div>"
  },
  {
    "hook": "data-sb-dualrange",
    "what": "Wrapper around TWO range inputs (from, to): cross-clamps so from ≤ to, paints the band between them and mirrors both into .sb-dualrange__value. data-sb-dualrange-unit appends a unit.",
    "example": "<div class=\"sb-dualrange\" data-sb-dualrange><input type=\"range\" value=\"20\" data-field=\"from\"><input type=\"range\" value=\"80\" data-field=\"to\"><span class=\"sb-dualrange__value\"></span><span class=\"sb-dualrange__value\"></span></div>"
  },
  {
    "hook": "data-sb-compare",
    "what": "Before/after image slider: the range input inside drives the clip position.",
    "example": "<div class=\"sb-compare\" data-sb-compare><img class=\"sb-compare__img sb-compare__img--before\" src=\"sb-asset:a.png\" alt=\"before\"><img class=\"sb-compare__img\" src=\"sb-asset:b.png\" alt=\"after\"><input type=\"range\" value=\"50\" aria-label=\"Compare\"></div>"
  },
  {
    "hook": "data-sb-sort",
    "what": "On a <th>: makes the column sortable. Put a real <button> inside for keyboard support. data-sb-sort=\"number\" compares numerically (currency and separators are stripped). Sorting reorders the first <tbody> and keeps aria-sort on exactly one column.",
    "example": "<div class=\"sb-table-wrap\"><table class=\"sb-table\" id=\"rows\"><thead><tr><th data-sb-sort><button type=\"button\" class=\"sb-table__sort\">Name</button></th><th data-sb-sort=\"number\"><button type=\"button\" class=\"sb-table__sort\">Amount</button></th></tr></thead><tbody><tr><td>Acme</td><td>$1,250.00</td></tr></tbody></table></div>"
  },
  {
    "hook": "data-sb-filter",
    "what": "On a search input: hides the rows of the table its selector names that do not contain the query. Give the input a data-field so the query survives your re-render — the filter is then re-applied automatically. An optional [data-sb-filter-count] with the SAME selector receives \"3 of 12 rows\"; a .sb-table-filter__empty inside the table's wrapper is unhidden when nothing matches.",
    "example": "<input class=\"sb-input\" type=\"search\" data-field=\"q\" data-sb-filter=\"#rows\" placeholder=\"Filter…\"><p class=\"sb-table-filter__count\" data-sb-filter-count=\"#rows\" role=\"status\"></p>"
  },
  {
    "hook": "data-sb-dropdown",
    "what": "Wrapper holding a [data-sb-dropdown-toggle] button and a .sb-dropdown__menu: the toggle opens it, any other click or Escape closes it, aria-expanded follows.",
    "example": "<div class=\"sb-dropdown\" data-sb-dropdown><button class=\"sb-btn\" data-sb-dropdown-toggle aria-expanded=\"false\">Actions</button><div class=\"sb-dropdown__menu\"><button class=\"sb-dropdown__item\" role=\"menuitem\" data-action=\"a\">Refresh</button></div></div>"
  },
  {
    "hook": "data-sb-menubar",
    "what": "Around several [data-sb-dropdown] entries: hovering another trigger moves an open menu there, Arrow keys walk triggers and items (APG menubar).",
    "example": "<div class=\"sb-menubar\" data-sb-menubar><div data-sb-dropdown><button class=\"sb-menubar__trigger\" data-sb-dropdown-toggle>File</button><div class=\"sb-dropdown__menu\"><button role=\"menuitem\" data-action=\"new\">New</button></div></div></div>"
  },
  {
    "hook": "data-sb-context",
    "what": "Wrapper whose right-click opens the .sb-context-menu inside it at the cursor, clamped to the window. Arrows/Home/End walk the items, Escape closes and restores focus.",
    "example": "<div data-sb-context><p>Right-click me</p><div class=\"sb-context-menu sb-dropdown__menu\" role=\"menu\"><button class=\"sb-dropdown__item\" role=\"menuitem\" data-action=\"copy\">Copy</button></div></div>"
  },
  {
    "hook": "data-sb-command",
    "what": "On a <dialog>: turns it into a filtering command palette. .sb-command__input filters .sb-command__item entries, arrows move the active one, Enter activates it and closes. Open it with commandfor/command — there is no global shortcut.",
    "example": "<button class=\"sb-btn\" commandfor=\"pal\" command=\"show-modal\">Search</button><dialog id=\"pal\" class=\"sb-modal sb-command\" data-sb-command><input class=\"sb-command__input\" autofocus placeholder=\"Type…\"><div class=\"sb-command__list\"><button class=\"sb-command__item\" data-action=\"open\" data-value=\"1\">Open report</button></div><p class=\"sb-command__empty\" hidden>No matches</p></dialog>"
  },
  {
    "hook": "data-sb-lightbox",
    "what": "Around a gallery: every <a href> wrapping an <img> opens the full image in a dialog with prev/next, a counter and arrow-key navigation.",
    "example": "<div class=\"sb-lightbox-grid\" data-sb-lightbox><a class=\"sb-lightbox-grid__item\" href=\"sb-asset:full.png\"><img src=\"sb-asset:thumb.png\" alt=\"Chart\"></a></div>"
  },
  {
    "hook": "data-sb-multiselect",
    "what": "Field wrapping a .sb-multiselect__toggle and a .sb-multiselect__panel of native checkboxes: checked boxes become removable pills, the toggle opens the panel and keeps an accessible name. The checkboxes stay the state — read them like any other field.",
    "example": "<div class=\"sb-multiselect\" data-sb-multiselect><span class=\"sb-multiselect__placeholder\">Tags</span><button class=\"sb-multiselect__toggle\" aria-expanded=\"false\"></button><div class=\"sb-multiselect__panel\"><label class=\"sb-check\"><input type=\"checkbox\" data-field=\"tag_a\" checked> Alpha</label></div></div>"
  },
  {
    "hook": "data-sb-taginput",
    "what": "Chips plus an inline text input. Enter or a comma adds a chip (duplicates ignored), Backspace on an empty input removes the last. The attribute value names a hidden field that carries the comma-separated list — read it under that data-field name.",
    "example": "<div class=\"sb-taginput\" data-sb-taginput=\"tags\"><input class=\"sb-taginput__input\" placeholder=\"Add tag…\"></div>"
  },
  {
    "hook": "data-sb-otp",
    "what": "Around several single-character inputs: typing advances, Backspace walks back, a paste fills the whole group.",
    "example": "<div class=\"sb-otp\" data-sb-otp><input class=\"sb-otp__slot\" maxlength=\"1\" inputmode=\"numeric\" data-field=\"c1\"><input class=\"sb-otp__slot\" maxlength=\"1\" inputmode=\"numeric\" data-field=\"c2\"></div>"
  },
  {
    "hook": "data-sb-combobox",
    "what": "Field holding an <input list> and its <datalist>: replaces the OS datalist popup with a themed, filtering listbox. Free text stays allowed.",
    "example": "<div class=\"sb-combobox-field\" data-sb-combobox><input class=\"sb-input\" list=\"cities\" data-field=\"city\"><datalist id=\"cities\"><option value=\"Berlin\"></option><option value=\"Bern\"></option></datalist></div>"
  },
  {
    "hook": "data-sb-native",
    "what": "Explicit opt-out for a <select>. Every select uses the shell's themed top-layer listbox by default while the original select remains the form, validation and data-field state source; keyboard focus stays on the combobox trigger and aria-activedescendant tracks the active option. Multiple selects retain open toggling and aria-multiselectable, optgroups become labelled groups, and hidden options stay omitted without changing source indexes. Add data-sb-native only when you deliberately want the operating system's native picker.",
    "example": "<select class=\"sb-select\" data-field=\"city\" data-sb-native><option value=\"berlin\">Berlin</option><option value=\"oslo\">Oslo</option></select>"
  },
  {
    "hook": "data-sb-datepicker",
    "what": "Field around an <input>: opens a themed calendar and writes YYYY-MM-DD. An optional [data-sb-datepicker-toggle] button opens it too. <input type=\"date\"> also works and needs none of this — use the picker when you want the bar's own look.",
    "example": "<div class=\"sb-datepicker-field\" data-sb-datepicker><input class=\"sb-input\" data-field=\"day\" placeholder=\"YYYY-MM-DD\"></div>"
  },
  {
    "hook": "data-sb-daterange",
    "what": "Field around TWO inputs: two picks fill start and end (ordered automatically) and the calendar marks the whole span.",
    "example": "<div class=\"sb-daterange\" data-sb-daterange><input class=\"sb-input\" data-field=\"from\"><span class=\"sb-daterange__sep\">–</span><input class=\"sb-input\" data-field=\"to\"></div>"
  },
  {
    "hook": "data-sb-countdown",
    "what": "Counts down to the ISO date-time in the attribute, once per second, without a re-render from you. [data-sb-countdown-part=\"days|hours|minutes|seconds\"] slots receive the zero-padded numbers; an optional [data-sb-countdown-done] element (authored hidden) is revealed at zero and the root gets .is-done.",
    "example": "<div class=\"sb-countdown\" data-sb-countdown=\"2027-01-01T00:00\"><span class=\"sb-countdown__segment\"><span class=\"sb-countdown__value\" data-sb-countdown-part=\"hours\"></span></span><p data-sb-countdown-done hidden>Done</p></div>"
  },
  {
    "hook": "data-sb-tween",
    "what": "Counts a changed number instead of jumping: the shell remembers the last shown value per tile surface and animates the FIRST plain number in the element's text to the new one over --sb-dur-slow (prefix, suffix and decimal format preserved; honors prefers-reduced-motion; first render shows the value directly). Keep thousands grouping out of a tweened value.",
    "example": "<span class=\"sb-mono\" data-sb-tween>48 min</span>"
  },
  {
    "hook": "data-sb-key",
    "what": "Stable identity for remembered values when one surface has multiple donuts, progress fills or data-sb-tween numbers. Give each logical value its own key and keep it unchanged across reorders; a single remembered value needs no key.",
    "example": "<span class=\"sb-mono\" data-sb-tween data-sb-key=\"cpu\">48%</span>"
  }
]
```