Skip to content

🅰 An accessible two-state button that can be either off (not pressed) or on (pressed)

License

Notifications You must be signed in to change notification settings

accessible-ui/toggle-button

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

17 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


<ToggleButton>

Bundlephobia Types Code coverage Build status NPM Version MIT License

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