An accessible two-state button that can be either off (not pressed) or on (pressed). Common use cases are toolbar buttons like Bold, Italic, and Underline. In addition to following the accessibility guidelines here, this component provides interop between real <button> elements and faux <div>, <a>, <span>, et. al. buttons.

Quick Start

Check out the example on CodeSandbox

import * as React from 'react'
import {ToggleButton, useA11yToggleButton} from '@accessible/toggle-button'

const Component = () => {
  const [muted, setMuted] = React.useState(false)
  return (
    <ToggleButton active={muted} onChange={setMuted}>
      <span>{muted ? 'Unmute' : 'Mute'}</span>
    </ToggleButton>
  )
}

const ComponentWithHook = () => {
  const ref = React.useRef(null)
  const [muted, setMuted] = React.useState(false)
  const a11yProps = useA11yToggleButton(ref, {
    active: muted,
    onChange: setMuted,
  })

  return (
    <button ref={ref} {...a11yProps}>
      <span>{muted ? 'Unmute' : 'Mute'}</span>
    </button>
  )
}

API

useA11yToggleButton(target, options?)

A React hook for creating a headless a11y toggle button to the W3C accessibility standard. In addition to providing accessibility props to your component, this hook will add events for interoperability between actual <button> elements and fake ones e.g. <a> and <div> to the target element.

Arguments

| Argument | Type | Required? | Description | | -------- | ----------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | | target | React.RefObject<T> | T | null | Yes | A React ref or HTML element | | | options | UseA11yToggleButtonOptions | Yes | The component you want to turn into a button that handles focus and space, enter keydown events. |

UseA11yToggleButtonOptions

export interface UseA11yToggleButtonOptions {
  /**
   * Creates a controlled hook where the active value always matches this one.
   */
  active?: boolean
  /**
   * Sets the default active state of the button for uncontrolled hooks.
   * @default false
   */
  defaultActive?: boolean
  /**
   * This callback is invoked any time the active state of the
   * toggle button changes
   */
  onChange?: (active: boolean) => void
  /**
   * Adds a click event to your button
   */
  onClick?: (event: MouseEvent) => any
}

Returns

interface ReturnValue {
  readonly 'aria-pressed': boolean
  readonly role: 'button'
  readonly tabIndex: 0
}

<ToggleButton>

This component clones its child component and adds accessibility roles for pressed/unpressed state buttons. It also creates context so its active state is accessible from its children.

Props

| Prop | Type | Default | Required? | Description | | ------------- | --------------------------- | ------- | --------- | -------------------------------------------------------------------------------------- | | active | string | | No | Creates a controlled component where the active value always matches this one. | | defaultActive | string | false | No | Sets the default active state of the button. | | activeClass | string | | No | Adds this class name to its child component when the button is in a active state. | | inactiveClass | string | | No | Adds this class name to its child component when the button is in an inactive state. | | activeStyle | React.CSSProperties | | No | Adds this style object to its child component when the button is in a active state. | | inactiveStyle | React.CSSProperties | | No | Adds this style object to its child component when the button is in an inactive state. | | onChange | (active: boolean) => void | | No | This callback is invoked any time the active state changes. | | children | React.ReactElement | | Yes | This is the element you want to turn into a ToggleButton. |

LICENSE

MIT