Segmented, one file.

API reference

Constructor & usage

new Segmented(target, options?) — target is a CSS selector string or an element. Creating a second instance on the same element destroys the first. Without a DOM (SSR), the constructor returns an inert no-op instance instead of throwing.

Build into a container — pass options and the control is rendered from scratch:

<div id="view"></div>
<script>
  var seg = new Segmented('#view', {
    options: ['List', 'Board', 'Calendar'],   // shorthand: value = label
    onChange: function (value, seg) { console.log(value) }
  })
</script>

Enhance existing buttons — omit options and each direct <button> child becomes a segment: label from its text, value from data-value (falling back to the text), and disabled respected. destroy() restores the original children and attributes exactly as they were.

<div id="env">
  <button data-value="dev">Dev</button>
  <button data-value="staging">Staging</button>
  <button disabled>Timeline</button>
</div>
<script>new Segmented('#env')</script>

Zero JS — add data-vsg to the container and it is initialized automatically (see Declarative init). Static helpers: Segmented.create(el, opts) is the same as new Segmented(...), and Segmented.get(el) returns the live instance for an element (or null).

Entries in the options array are either primitives (shorthand — the value doubles as the label) or objects:

Options

All constructor options with their defaults (Segmented.defaults, mutable to change them globally):

There are no per-call-only constructor options beyond these. The one method-level option is setValue(value, { silent: true }), covered below.

Instance methods

All methods except getValue() return the instance, so calls chain. Useful instance properties: el (the container), options (normalized option objects), index (selected index, -1 if none), segs (segment buttons), and input (the hidden input, or null).

Statics & helpers

Events & callbacks

Two ways to hear about selection changes; both fire only when the selection actually changes, and neither fires for the initial selection, setValue(v, { silent: true }), or update().

document.addEventListener('segmented:change', function (e) {
  console.log(e.detail.value, e.detail.segmented)
})

No native change/input events are dispatched on the hidden form input; its value is simply kept in sync.

Declarative init

Any element with data-vsg is auto-initialized on DOMContentLoaded (or immediately, if the script loads after parsing). Call Segmented.autoInit(root?) yourself for content added later. Options come from data attributes on the container; segments come from its <button> children (value from data-value on each button, label from its text, disabled respected):

<div data-vsg data-name="view" data-size="sm" data-full-width="true">
  <button data-value="list">List</button>
  <button data-value="board">Board</button>
</div>

Theming

With theme: 'auto' (the default) the control resolves its theme in the family's order: <html data-theme> / data-bs-theme → a .dark/.light class on <html> → prefers-color-scheme — re-resolved live when any of those change (via MutationObserver and a media-query listener, or the shared VC theme engine when the core is loaded). Pin per instance with theme: 'light' or 'dark'. The resolved theme is stamped on the container as data-theme.

All colors are CSS custom properties, defined on .vsg (light) and .vsg[data-theme=dark] (dark):

.vsg { --vsg-accent: #b45309; --vsg-radius: 8px; }

With the VC core loaded, VC.config({ accent: '#b45309' }) themes this and every other family component in one call.

CSS isolation: the control renders as class="vsg vc1" and all structural rules ship salted (.vsg.vc1 .vsg-seg { … }) so host-page design systems can't override it — while the --vsg-* variable definitions are deliberately unsalted, so overrides like the one above keep working. The injected stylesheet is inserted before the page's own CSS so your overrides win the cascade. Custom token: Segmented.salt = 'acme' before the first instance; disable salting with Segmented.salt = false.

Headless: Segmented.defaults.styles = false (or per instance { styles: false }) injects no CSS while keeping the full behavior — thumb measurement, roving tabindex, ARIA, hidden input. Use Segmented.css (string) or dist/segmented.css (file) as a starting point, and style this markup contract:

.vsg[.vsg-sm][.vsg-full][.vsg-disabled][data-theme=dark]   role=radiogroup
  .vsg-thumb[.vsg-thumb-on]        ← JS sets transform/width/height
  .vsg-seg[aria-checked]           ← role=radio button, data-value
    .vsg-icon                      ← only when `icon` given
    .vsg-label                     ← omitted when icon-only
  input[type=hidden]               ← only when `name` given

Accessibility

The control is a role="radiogroup" whose segments are role="radio" buttons with aria-checked, using a roving tabindex — the whole control is one Tab stop, and the checked segment is the one that receives focus. The group gets an accessible name from the label option; an author-provided aria-label / aria-labelledby is never clobbered. Icon-only segments carry an aria-label from their label/value, and icon spans plus the thumb are aria-hidden="true". disable() sets aria-disabled="true" on the group. The thumb re-measures on window resize and animates only after the first placement; prefers-reduced-motion disables the animation entirely.

Key presses with Alt, Ctrl, or Cmd held are left to the browser.