https://github.com/accessible-ui/toggle-button
🅰 An accessible two-state button that can be either off (not pressed) or on (pressed)
https://github.com/accessible-ui/toggle-button
a11y a11y-button a11y-toggle accessibility accessible accessible-react accessible-toggle aria aria-button aria-toggle react
Last synced: 2 months ago
JSON representation
🅰 An accessible two-state button that can be either off (not pressed) or on (pressed)
- Host: GitHub
- URL: https://github.com/accessible-ui/toggle-button
- Owner: accessible-ui
- License: mit
- Created: 2019-12-28T19:08:46.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:23:10.000Z (over 2 years ago)
- Last Synced: 2025-02-28T18:07:00.112Z (3 months ago)
- Topics: a11y, a11y-button, a11y-toggle, accessibility, accessible, accessible-react, accessible-toggle, aria, aria-button, aria-toggle, react
- Language: TypeScript
- Homepage: https://codesandbox.io/s/accessibletoggle-button-example-s1cuy
- Size: 2.72 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
<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](https://www.w3.org/TR/wai-aria-practices/#button), this component
provides interop between real `` elements and faux `
`, ``, ``, et. al. buttons.
## Quick Start
[Check out the example on **CodeSandbox**](https://codesandbox.io/s/accessibletoggle-button-example-s1cuy)
```jsx harmony
import * as React from 'react'
import {ToggleButton, useA11yToggleButton} from '@accessible/toggle-button'
const Component = () => {
const [muted, setMuted] = React.useState(false)
return (
{muted ? 'Unmute' : 'Mute'}
)
}
const ComponentWithHook = () => {
const ref = React.useRef(null)
const [muted, setMuted] = React.useState(false)
const a11yProps = useA11yToggleButton(ref, {
active: muted,
onChange: setMuted,
})
return (
{muted ? 'Unmute' : 'Mute'}
)
}
```
## API
### useA11yToggleButton(target, options?)
A React hook for creating a headless a11y toggle button to the
[W3C accessibility standard](https://www.w3.org/TR/wai-aria-practices/#button). In addition
to providing accessibility props to your component, this hook will add events for interoperability
between actual `` elements and fake ones e.g. `` and `` to the `target` element.
#### Arguments
| Argument | Type | Required? | Description |
| -------- | ----------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| target | React.RefObject<T> | T | null | Yes | A React ref or HTML element | |
| options | [`UseA11yToggleButtonOptions`](#usea11ytogglebuttonoptions) | Yes | The component you want to turn into a button that handles focus and `space`, `enter` keydown events. |
#### UseA11yToggleButtonOptions
```ts
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
```ts
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