# Switch
> Form-associated switch whose track fills with a dithered energy field when on; the thumb springs across with a few sparks.
- Element: `<hf-switch>`
- React: `import { HfSwitch } from "@/components/lumesec/hf-switch"`
- Collection: Pixel HD (https://elements.lumesec.ai/components/pixel-hd)
- Registry item: https://elements.lumesec.ai/r/hf-switch.json
- Page: https://elements.lumesec.ai/components/pixel-hd/switch



Live preview: https://elements.lumesec.ai/view/hf-switch

```html
<hf-switch name="ultra" checked>Ultracode<span slot="hint">Plan multi-agent workflows</span></hf-switch><hf-switch name="search" style="margin-top:16px">Web search<span slot="hint">Look things up while answering</span></hf-switch>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/hf-switch
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/hf-switch.json
```

## Usage

React:

```tsx
import { HfSwitch } from "@/components/lumesec/hf-switch";

export function Example() {
  return (
    <>
      <HfSwitch name="ultra" checked>
        Ultracode
        <span slot="hint">Plan multi-agent workflows</span>
      </HfSwitch>
      <HfSwitch name="search" style={{ marginTop: 16 }}>
        Web search
        <span slot="hint">Look things up while answering</span>
      </HfSwitch>
    </>
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/hf-switch.js"></script>

<hf-switch name="ultra" checked>Ultracode<span slot="hint">Plan multi-agent workflows</span></hf-switch><hf-switch name="search" style="margin-top:16px">Web search<span slot="hint">Look things up while answering</span></hf-switch>
```

## Behaviour

The track charges up with a dithered energy field when it turns on and the thumb springs across with a few sparks. Form-associated, like every control here.

## API reference

### Attributes

| Attribute | React prop | Type      | Default | Description                                                                                                |
| --------- | ---------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `checked` | `checked`  | `boolean` | `false` | Presence attribute. Observed: adding or removing it updates the switch, `aria-checked` and the form value. |
| `value`   | `value`    | `string`  | `on`    | Value submitted with the form while checked.                                                               |
| `name`    | `name`     | `string`  | —       | Form field name.                                                                                           |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event    | React prop | Detail                 | Description                                                                        |
| -------- | ---------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `change` | `onChange` | `{ checked: boolean }` | Fires when the user toggles the switch. Not fired when `checked` is set from code. |

### Properties

| Property  | Type      | Description                       |
| --------- | --------- | --------------------------------- |
| `checked` | `boolean` | Reflects the `checked` attribute. |

### Slots

| Slot        | Description                            |
| ----------- | -------------------------------------- |
| `(default)` | Label text. Falls back to `Ultracode`. |
| `hint`      | Secondary text under the label.        |

## Accessibility

* The control is a native `<button>` with `role="switch"` and `aria-checked`, so Enter and Space toggle it.
* `aria-label` is the text in the default slot (`Ultracode` when the slot is empty) and follows changes to that content. The `hint` slot is linked with `aria-describedby`.
* Clicking anywhere on the row, including the label text, toggles the switch.
* Submits `name=value` (default `on`) while checked and nothing while unchecked. No validation; form reset does not change the state.
* Reduced motion: the thumb moves without the spring, the fill appears without its sweep or flowing pattern, and no sparks are drawn.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec`, `--muted` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg`, `--ui-muted` and `--ui-track`.