# SvToggleButton
A button with a sticky pressed on/off state, exposed to assistive tech via
`aria-pressed`.
`SvToggleButton` looks like a button but remembers whether it is on. Use it for
binary controls where the label stays constant - bold/italic in a formatting
toolbar, a pin, a mute, a "live" toggle. It is controlled: drive `pressed` from
your state and flip it in `onChange`. It carries the shared editor contract
(label, hint, validation, `dir`/RTL) through [SvField](https://svgrid.com/docs/help/ui-components/inputs/).
Related: [SvSwitchButton](https://svgrid.com/docs/help/ui-components/sv-switch-button/) · [SvButtonGroup](https://svgrid.com/docs/help/ui-components/sv-button-group/) · [Buttons & toggles overview](https://svgrid.com/docs/help/ui-components/buttons/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvToggleButton` starter into your app:
Prefer to see it first? `npx @svgrid/ui try toggle-button` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvToggleButton` ships free in
`@svgrid/grid` and is **part of the grid's editor kit** - the same control SvGrid mounts when you edit a matching cell:
The examples on this page run against these rows:
```svelte
```
```ts
import { SvToggleButton } from '@svgrid/grid'
```
## Example
> Live demo: Toggle button - https://svgrid.com/demos/307-toggle-button/
```svelte
(bold = v)}>Bold
```
## Props
| Prop | Type | Default | Description |
| ----------- | --------------------------- | ------- | ---------------------------------------------------------------- |
| `pressed` | `boolean` | `false` | Current on/off state (controlled). |
| `onChange` | `(pressed: boolean) => void`| - | Fires with the next state when toggled. |
| `disabled` | `boolean` | `false` | Blocks toggling and dims the control. |
| `size` | `sm` \| `md` \| `lg` | `md` | Padding and font size, shared with the rest of the kit. |
| `label` | `string` | - | Visible field label, rendered above the button. |
| `hint` | `string` | - | Helper text under the button. |
| `error` | `string` | - | Error message announced via `aria-describedby`. |
| `required` | `boolean` | `false` | Adds `aria-required`. |
| `invalid` | `boolean` | `false` | Marks the control invalid (danger border). |
| `dir` | `ltr` \| `rtl` \| `auto` | `auto` | Text direction. |
| `ariaLabel` | `string` | - | Accessible name for an icon-only toggle. |
| `id` | `string` | auto | Root id; label/hint/error ids derive from it. |
| `children` | `Snippet` | - | The button label. |
## Examples
### Formatting toolbar
A row of toggles, each bound to its own state, reads as an inline formatting bar:
```svelte
(bold = v)}>B (italic = v)}>I
```
### Icon toggle with a label
Give an icon-only toggle an `ariaLabel` so the on/off state is announced with a
name:
```svelte
(pinned = v)}>📌
```
### Reflecting external state
Because it is controlled, the pressed look always mirrors your state - toggle it
from anywhere and the button follows:
```svelte
setLive(v)}>Live
```
### Toolbar filter toggle
A toggle whose pressed state drives a `$derived` list makes a compact "show
only" filter - the button stays lit while the filter is active:
```svelte
(favoritesOnly = v)}>
★ Favorites only
```
## Accessibility
- Renders a native `