> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Button Toggle - Web (AI Kit)

> The ButtonToggle provides a persistent on and off action with React Aria selection semantics.

> [!NOTE]
>
> For development, import `ButtonToggle` from
> `@servicetitan/anvil2-ai-kit`. For design, find it in the
> [AI Kit Web Component Library file](https://www.figma.com/design/QEIsArLktLeJAaFvcpw3PO/AI-Kit-Web-Component-Library).

**Implementation**

ai-kit-button-toggle

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-button-toggle?file=src/App.tsx)

```tsx lines expandable theme={null}
import { useState } from "react";
import { IconPencil } from "@servicetitan/anvil2-icons";
import { ButtonToggle } from "@servicetitan/anvil2-ai-kit";

function App() {
  const [selected, setSelected] = useState(false);

  return (
    <ButtonToggle
      label="Edit mode"
      icon={<IconPencil />}
      isSelected={selected}
      onChange={setSelected}
    />
  );
}

export default App;
```

## Common Examples

To use the `ButtonToggle`, pass a required `label` and control selection with
React Aria's `isSelected` and `onChange`. Use `defaultSelected` instead for
uncontrolled selection. The kit forbids `children`.

```tsx theme={null}
<ButtonToggle
  label="Bold"
  isSelected={bold}
  onChange={setBold}
  icon={<IconBold />}
/>
```

A bare icon creates an icon-only toggle. `label` becomes its accessible name
and tooltip. Use `{ icon, position }` to show the label beside the icon.

ai-kit-button-toggle-label

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/ai-kit-button-toggle-label?file=src/App.tsx)

```tsx lines expandable theme={null}
import { useState } from "react";
import { IconPencil } from "@servicetitan/anvil2-icons";
import { ButtonToggle } from "@servicetitan/anvil2-ai-kit";

function App() {
  const [selected, setSelected] = useState(false);

  return (
    <ButtonToggle
      label="Edit mode"
      icon={{ icon: <IconPencil />, position: "left" }}
      isSelected={selected}
      onChange={setSelected}
    />
  );
}

export default App;
```

`size` is `"medium"`, `"small"`, or `"xsmall"`. On coarse pointers,
`xsmall` promotes to a 40×40 minimum touch target.

## React Accessibility

* React Aria provides keyboard, pointer, focus-visible, and selection behavior.
* `label` is always required, including for icon-only toggles.
* Use a short imperative label such as "Bold" or "List view."

**ButtonToggle Props**

## `ButtonToggle` Props

The `ButtonToggle` accepts the following props. It also forwards remaining React Aria `ToggleButton` props except `children`, render-prop `className`, and `style`.

**label** `string` *required*

Visible label, or the accessible name and tooltip for an icon-only toggle.

**className** `string`

Class merged onto the button.

**defaultSelected** `boolean`

Initial selection for uncontrolled use.

**icon** `ButtonIcon`

Bare icon for an icon-only toggle, or `{ icon, position }` for an icon
paired with the visible label.

**isDisabled** `boolean`

Disables the toggle.

**isSelected** `boolean`

Controlled selected state.

**onChange** `(isSelected: boolean) =\> void`

Fired when selection changes.

**size** `"medium" | "small" | "xsmall"` (default: medium)

Target size.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.