> ## 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 - React Native

> The ButtonToggle provides a persistent on and off action.

> [!NOTE]
>
> For development, import `ButtonToggle` from
> `@servicetitan/anvil2-rn`. For design, find it in the
> [Mobile Agentic Component Library file](https://www.figma.com/design/gjGWnAOnI1kukfzjsUQ6dP/Mobile-Agentic-Component-Library).

**Implementation**

```tsx theme={null}
import { useState } from "react";
import { IconPencil } from "@servicetitan/anvil2-icons/react-native";
import { ButtonToggle } from "@servicetitan/anvil2-rn";

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

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

## Common Examples

To use the `ButtonToggle`, pass a required `label` and control selection with `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. Use `{ icon, position }` to show the label beside the icon.

```tsx theme={null}
<ButtonToggle
  label="Edit mode"
  icon={{ icon: <IconPencil />, position: "left" }}
  isSelected={selected}
  onChange={setSelected}
/>
```

`size` is `"medium"`, `"small"`, or `"xsmall"`.

## Accessibility

* The control uses `accessibilityRole="togglebutton"` and `accessibilityState.checked` for the selected state.
* `label` is always required, including for icon-only toggles, and is set as `accessibilityLabel`.
* Use a short imperative label such as "Bold" or "List view."

**ButtonToggle Props**

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

## `ButtonToggle` Props

The `ButtonToggle` accepts the following props. It does not forward remaining React Native `Pressable` props.

**label** `string` *required*

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

**analyticsId** `string`

Opt-in telemetry id. When set under `Anvil2RNTelemetryProvider`, a press
emits a `press` event with `meta.selected` (the state the press produced)
before `onChange`.

**defaultSelected** `boolean` (default: false)

Initial selection for uncontrolled use. Ignored when `isSelected` is set.

**icon** `IconElement | \{ icon: IconElement; position: "left" | "right" \}`

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

**isDisabled** `boolean` (default: false)

Disables the toggle.

**isSelected** `boolean`

Controlled selected state.

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

Fired when selection changes.

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

Target size.

**testID** `string`

Test hook forwarded to the underlying `Pressable`.


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