Toggle

Playground

An on/off switch with chunky pixel corners and stepped motion. It exposes a checked property and fires change, so Datastar can bind to it like a native checkbox.

Examples

Basic

<sb-toggle label="Warp drive"></sb-toggle>
<sb-toggle label="Shields" checked></sb-toggle>
<sb-toggle label="Self-destruct" disabled></sb-toggle>

Sizes

<sb-toggle size="sm" checked aria-label="Small"></sb-toggle>
<sb-toggle size="md" checked aria-label="Medium"></sb-toggle>
<sb-toggle size="lg" checked aria-label="Large"></sb-toggle>

Two-way binding

Bind the checked property with data-bind and the __prop and __event modifiers.

<div data-signals:_thrusters="false">
  <sb-toggle label="Thrusters" data-bind:_thrusters__prop.checked__event.change></sb-toggle>
  <p data-text="$_thrusters ? 'Thrusters engaged' : 'Thrusters idle'"></p>
</div>

With commands

Give it a name, and it emits sb-change with { name, value } when a value is committed: ready to post as a command. With confirm, it sets :state(pending) until the server's re-rendered attribute matches, and revert() goes back to the server's value when a command is rejected. See Commands and components and the Showcase.

The server's checked wins when it sends a new one, even onto a toggle rendered without it; the same markup again leaves the user's switch alone. A removed attribute changes nothing, so send checked="false" to switch it off. Write it as checked, checked="true" or checked="false": checked="checked" (like disabled="disabled") reads as false.

Forms

Inside a <form>, sb-toggle submits like a checkbox: name=on when it is on, nothing when it is off or disabled, and nothing without a name. new FormData(form) and Datastar's contentType: 'form' include it, and a form reset brings back the server's checked without firing change or sb-change. It is not a form-associated element yet (Rocket can't declare one), so required and validity, <fieldset disabled>, <label for> and the form attribute don't reach it. With commands, sb-change carries { name, value } (see With commands).

Styling

Style it from your page's CSS, without changing the component or importing anything into it. Custom properties, inherited properties and ::part() all reach into its shadow root.

• Size: size (sm, md, lg) sets the switch.
• Fonts: the label uses your page's font, size and colour.
• Colours: the track is --sb-border-strong when off and --sb-brand when on; the knob is --sb-toggle-knob (default --sb-text-1, and --sb-text-on-brand on the brand track), the focus ring --sb-brand-light. --sb-notch: 0 rounds the switch instead of notching it, and its knob and colour move smoothly instead of in steps.
• Parts: switch (the track) and label. The knob has no part: colour it with --sb-toggle-knob. Your page's ::part() rules win over the component's own, without !important.

<style>
  .my-toggle { --sb-brand: #16A34A; --sb-notch: 0; --sb-toggle-knob: #FFFFFF; }
  .my-toggle::part(label) { color: var(--sb-text-2); font-size: 0.875rem; }
</style>
<sb-toggle class="my-toggle" label="Autopilot" checked size="lg"></sb-toggle>

Accessibility

The switch is a <button role="switch"> with aria-checked, so it is focusable and toggles with Space and Enter. Give it a label, or an aria-label on <sb-toggle> when the name shouldn't show: the switch takes it over (aria-labelledby doesn't reach inside). Without either it is announced as "Toggle". In forced colours (Windows High Contrast) the track is outlined and the on state uses the system highlight colours.

Installation

<script type="importmap">
  { "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>

<sb-toggle label="Notifications"></sb-toggle>

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js": "sha384-mvTnynHaljKNMleD0bj6/rWROnluHlNmbc5rOQTd+fQH3YBDYhlvHdNquEX99by5"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/toggle@46880f06cfc3/toggle.bundle.min.js" integrity="sha384-jq5uNQA0WHDb6bMACFqSurqw9TZWSmWHbbTP7FgK9kGKcKY+cepdrhB/M9dxP0HY"></script>

<sb-toggle label="Notifications"></sb-toggle>

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js": "sha384-mvTnynHaljKNMleD0bj6/rWROnluHlNmbc5rOQTd+fQH3YBDYhlvHdNquEX99by5",
      "https://starbase.zweiundeins.gmbh/c/toggle@46880f06cfc3/toggle.min.js": "sha384-4Ef5TBvxfIWFtftzSu4YZcZXCDC5f/SMFD7EMubp6LjOlS+XyjC7KvOaNt19Y4hj"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/toggle@46880f06cfc3/toggle.min.js" integrity="sha384-4Ef5TBvxfIWFtftzSu4YZcZXCDC5f/SMFD7EMubp6LjOlS+XyjC7KvOaNt19Y4hj"></script>

<sb-toggle label="Notifications"></sb-toggle>

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@f602fbe19d74/datastar-rocket.js": "sha384-mvTnynHaljKNMleD0bj6/rWROnluHlNmbc5rOQTd+fQH3YBDYhlvHdNquEX99by5",
      "https://starbase.zweiundeins.gmbh/c/toggle@46880f06cfc3/toggle.bundle.min.js": "sha384-jq5uNQA0WHDb6bMACFqSurqw9TZWSmWHbbTP7FgK9kGKcKY+cepdrhB/M9dxP0HY"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@339249aca48f/autoloader.js" integrity="sha384-ZNpMayI1XShztIEX0iDHyCDDbhT8H+t+zEESUq4BCrN4b+7m931LQEl5x0vbY+Vo"></script>

<sb-toggle label="Notifications"></sb-toggle>

<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/toggle/toggle.bundle.min.js"></script>

<sb-toggle label="Notifications"></sb-toggle>

<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/toggle/toggle.min.js"></script>

<sb-toggle label="Notifications"></sb-toggle>

Size

A page loads this component as one file, its bundle, compressed the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.

API reference

Props

Events