@accessible/toggle-button

---

<ToggleButton>

npm i @accessible/toggle-button

---

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