> ## 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 – Code

> The ButtonToggle provides a persistent on and off action.

<Tabs>
  <Tab title="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."
  </Tab>

  <Tab title="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.

    <ParamField path="label" type="string" required>
      Visible label, or the accessible name for an icon-only toggle.
    </ParamField>

    <ParamField path="analyticsId" type="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`.
    </ParamField>

    <ParamField path="defaultSelected" type="boolean" default="false">
      Initial selection for uncontrolled use. Ignored when `isSelected` is set.
    </ParamField>

    <ParamField path="icon" type={`IconElement | { icon: IconElement; position: "left" | "right" }`}>
      Bare icon for an icon-only toggle, or `{ icon, position }` for an icon
      paired with the visible label.
    </ParamField>

    <ParamField path="isDisabled" type="boolean" default="false">
      Disables the toggle.
    </ParamField>

    <ParamField path="isSelected" type="boolean">
      Controlled selected state.
    </ParamField>

    <ParamField path="onChange" type="(isSelected: boolean) => void">
      Fired when selection changes.
    </ParamField>

    <ParamField path="size" type={`"medium" | "small" | "xsmall"`} default="medium">
      Target size.
    </ParamField>

    <ParamField path="testID" type="string">
      Test hook forwarded to the underlying `Pressable`.
    </ParamField>
  </Tab>
</Tabs>