Button Toggle

For development, import ButtonToggle from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Button Toggle consists of three primary elements that work together to let users alternate between two states with a single click.

Container
Text label
Icon

Options

The Button Toggle supports multiple size configurations to accommodate various toggle scenarios.

Sizes

Size	Height
Large	48px
Medium	40px
Small	32px

Behavior

The Button Toggle responds to user interaction with distinct visual states and flexible layout behaviors.

Visual States

Default

Checked

Text wrap

Button Toggles fill all available space, wrapping only when no space remains. Text is center-aligned when wrapping.

Widths

In general, Button Toggles should match the width of their text. Container width works well when aligning with specific layout elements. Button Toggle Icon width always equals its height.

Usage Guidelines

Standard	Requirement
DoControl binary state	Button Toggles control the binary state of a Button. They can contain text, text with an icon, or just an icon.
DoSelect multiple options from a set	Button Toggles work well when selecting multiple options from a set of available options; see How to Use.

How to Use

Button Toggles work well when selecting multiple options from a set of available options.

Content

Content within the Button Toggle should clearly communicate the toggle state through labels and optional icons.

Keyboard Interaction

Users can navigate the Button Toggle using standard keyboard controls.

Key	Interaction
Space or Enter	Toggles checked state

Button Toggles using an href will also use this keyboard combination.

Accessibility

Anvil provides most of the accessibility needs for Button Toggle out of the box, and only need some additional considerations for library users.

Provide labels for Icon Buttons

Regardless of whether or not a label is visible on the page, a label should be provided to describe the action for both screen readers and for users who focus on the element. For more guidance on button labels and accessibility, see button accessibility best practices.

Code

Implementation
ButtonToggle Props

Common Examples

import { ButtonToggle } from "@servicetitan/anvil2";

function ExampleComponent() {
  return <ButtonToggle>Click to toggle</ButtonToggle>;
}

Button toggle sizes

Use the size prop to adjust the text size and padding of the button.

Controlling button toggles

Uncontrolled button toggles

By default, button toggles are uncontrolled. The checked state changes when the button is clicked. To make the button toggle checked by default, use the defaultChecked prop.

Controlled button toggles

To programmatically set the checked state of a button toggle, use the checked prop.

Handling state changes

The onChange prop accepts a function that passes the change event and current state object. This can be used to trigger other actions depending on the changed state.

() => {
  doSomething(state: ButtonToggleState) {
    console.log(`${state.value} is pressed: ${state.pressed}`)
  }
  return (
    <ButtonToggle onChange={(e, state) => doSomething(state)}>
      Toggle
    </ButtonToggle>
  )
}

React Accessibility

Icon-only button toggles

<ButtonToggle icon={Star} aria-label="Favorite" />

Use aria-label or aria-labelledby for a button without any text.

<ButtonToggle icon={Star} />

Don’t

Provide only an icon for screen readers to read.For more guidance on button labels and accessibility, see button accessibility best practices.

<ButtonToggle
  checked={true}
  defaultChecked={false}
  disabled={false}
  icon={StarIcon}
  size="medium"
  value="toggle-1"
  onChange={(e, state) => console.log(state)}
>
  Click to toggle
</ButtonToggle>

`ButtonToggle` Props

boolean

ReactNode

boolean

default:"false"

boolean

default:"false"

Svg { before: Svg, after: Svg }

The SVGR library imports *.svg files as React components, so icon can accept either a React component, or an object with before and/or after keys to specify the placement of the icon.

(event, { pressed, value }) => void

"small" | "medium" | "large"

default:"medium"

string

Concepts & Guidelines

Anvil2

Resources

Button Toggle - Web

Anatomy

Options

Sizes

Behavior

Visual States

Default

Checked

Text wrap

Widths

Usage Guidelines

How to Use

Content

Keyboard Interaction

Accessibility

Provide labels for Icon Buttons

Code

Common Examples

Button toggle sizes

Controlling button toggles

Uncontrolled button toggles

Controlled button toggles

Handling state changes

React Accessibility

Icon-only button toggles

`ButtonToggle` Props

​Anatomy

​Options

​Sizes

​Behavior

​Visual States

​Default

​Checked

​Text wrap

​Widths

​Usage Guidelines

​How to Use

​Content

​Keyboard Interaction

​Accessibility

​Provide labels for Icon Buttons

​Code

​Common Examples

​Button toggle sizes

​Controlling button toggles

​Uncontrolled button toggles

​Controlled button toggles

​Handling state changes

​React Accessibility

​Icon-only button toggles

​ButtonToggle Props

Anatomy

Options

Sizes

Behavior

Visual States

Default

Checked

Text wrap

Widths

Usage Guidelines

How to Use

Content

Keyboard Interaction

Accessibility

Provide labels for Icon Buttons

Code

Common Examples

Button toggle sizes

Controlling button toggles

Uncontrolled button toggles

Controlled button toggles

Handling state changes

React Accessibility

Icon-only button toggles

`ButtonToggle` Props