@accessible/toggle-button
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.2 • Public • Published

    <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

    Install

    npm i @accessible/toggle-button

    DownloadsWeekly Downloads

    22

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    94.6 kB

    Total Files

    17

    Last publish

    Collaborators

    • jaredlunde