npm i @accessible/drawer

An accessible and versatile drawer component for React

Features

• Style-agnostic You can use this component with the styling library of your choice. It works with CSS-in-JS, SASS, plain CSS, plain style objects, anything!
• Portal-friendly The drawer target will render into React portals of your choice when configured to do so.
• a11y/aria-compliant This component works with screen readers out of the box and manages focus for you.

Quick Start

Check out the example on CodeSandbox

import * as React from 'react'
import * as Drawer from '@accessible/drawer'

const Component = () => (
  <Drawer.Drawer>
    <Drawer.Trigger>
      <button>Open me</button>
    </Drawer.Trigger>

    <Drawer.Target>
      <div className='my-drawer'>
        <Drawer.CloseButton>
          <button>Close me</button>
        </Drawer.CloseButton>

        <div>I've been revealed!</div>
      </div>
    </Drawer.Target>
  </Drawer.Drawer>
)

API

Components

Hooks

<Drawer>

This component creates the context for your drawer target and trigger and contains some configuration options.

Props

useA11yTarget(target, options?)

A React hook for creating a headless drawer target to WAI-ARIA authoring practices.

Arguments

UseA11yTargetOptions

export interface UseA11yTargetOptions {
  /**
   * Sets the placement of the drawer menu
   * @default "left"
   */
  placement?: 'top' | 'right' | 'bottom' | 'left'
  /**
   * Adds this class name to props when the drawer is open
   */
  openClass?: string
  /**
   * Adds this class name to props when the drawer is closed
   */
  closedClass?: string
  /**
   * Adds this style to props when the drawer is open
   */
  openStyle?: React.CSSProperties
  /**
   * Adds this style to props when the drawer is closed
   */
  closedStyle?: React.CSSProperties
  /**
   * Prevents the `window` from scrolling when the target is
   * focused after opening.
   */
  preventScroll?: boolean
  /**
   * When `true`, this closes the target element when the `Escape`
   * key is pressed.
   * @default true
   */
  closeOnEscape?: boolean
}

Returns

type A11yProps = {
  readonly 'aria-hidden': boolean
  readonly id: string | undefined
  readonly className: string | undefined
  readonly style: {
    readonly visibility: 'hidden' | 'visible'
  } & React.CSSProperties
} & {
  readonly style:
    | ({
        readonly visibility: 'hidden' | 'visible'
      } & React.CSSProperties & {
          readonly position: 'fixed'
          readonly top: 0
          readonly right: 0
          readonly bottom: 'auto'
          readonly left: 0
          readonly transform: 'translate3d(0, -100%, 0)'
        })
    | ({
        readonly visibility: 'hidden' | 'visible'
      } & React.CSSProperties & {
          readonly position: 'fixed'
          readonly top: 0
          readonly right: 0
          readonly bottom: 0
          readonly left: 'auto'
          readonly transform: 'translate3d(100%, 0, 0)'
        })
    | ({
        readonly visibility: 'hidden' | 'visible'
      } & React.CSSProperties & {
          readonly position: 'fixed'
          readonly top: 'auto'
          readonly right: 0
          readonly bottom: 0
          readonly left: 0
          readonly transform: 'translate3d(0, 100%, 0)'
        })
    | ({
        readonly visibility: 'hidden' | 'visible'
      } & React.CSSProperties & {
          readonly position: 'fixed'
          readonly top: 0
          readonly right: 'auto'
          readonly bottom: 0
          readonly left: 0
          readonly transform: 'translate3d(-100%, 0, 0)'
        })
}

Example

import * as React from 'react'
import {useA11yTarget} from '@accessible/drawer'

const MyTarget = () => {
  const ref = React.useRef(null)
  const a11yProps = useA11yTarget(ref, {preventScroll: true})

  return (
    <div ref={ref} {...a11yProps}>
      I am the drawer content
    </div>
  )
}

<Target>

This component wraps any React element and turns it into a drawer target.

Props

Example

<Target>
  <div className='alert'>Alert</div>
</Target>

// <div
//   class="alert"
//   aria-hidden="true"
//   id="🅰12"
//   style="visibility: hidden;"
// >
//   Alert
// </div>

useA11yTrigger(target, options?)

A React hook for creating a headless drawer trigger to WAI-ARIA authoring practices. 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

Arguments

UseA11yTriggerOptions

export interface UseA11yTriggerOptions {
  /**
   * Adds this class name to props when the drawer is open
   */
  openClass?: string
  /**
   * Adds this class name to props when the drawer is closed
   */
  closedClass?: string
  /**
   * Adds this style to props when the drawer is open
   */
  openStyle?: React.CSSProperties
  /**
   * Adds this style to props when the drawer is closed
   */
  closedStyle?: React.CSSProperties
  /**
   * Adds an onClick handler in addition to the default one that
   * toggles the drawer's open state.
   */
  onClick?: (e: MouseEvent) => any
}

Returns

interface A11yProps<E extends React.MouseEvent<any, MouseEvent>> {
  readonly 'aria-controls': string | undefined
  readonly 'aria-expanded': boolean
  readonly role: 'button'
  readonly tabIndex: 0
  readonly className: string | undefined
  readonly style: React.CSSProperties | undefined
}

Example

import * as React from 'react'
import {useA11yTrigger} from '@accessible/drawer'

const MyTrigger = () => {
  const ref = React.useRef(null)
  const a11yProps = useA11yTrigger(ref, {
    openClass: 'open',
    closedClass: 'closed',
  })

  return (
    <button ref={ref} {...a11yProps}>
      Clicking me toggles the drawer content
    </button>
  )
}

<Trigger>

This component wraps any React element and adds an onClick handler which toggles the open state of the drawer target.

Props

<Trigger on='click'>
  <button className='my-button'>Open me!</button>
</Trigger>

// <button
//   class="my-button"
//   aria-controls="🅰12"
//   aria-expanded="false"
// >
//   Open me!
// </button>

useA11yCloseButton(target, options?)

A React hook for creating a headless close button to WAI-ARIA authoring practices. 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

Arguments

UseA11yCloseButtonOptions

export interface UseA11yCloseButtonOptions {
  /**
   * Adds an onClick handler in addition to the default one that
   * closes the drawer.
   */
  onClick?: (e: MouseEvent) => any
}

Returns

interface A11yProps<E extends React.MouseEvent<any, MouseEvent>> {
  readonly 'aria-controls': string | undefined
  readonly 'aria-expanded': boolean
  readonly 'aria-label': 'Close'
  readonly role: 'button'
  readonly tabIndex: 0
}

Example

import * as React from 'react'
import {useA11yCloseButton} from '@accessible/drawer'

const MyTrigger = () => {
  const ref = React.useRef(null)
  const a11yProps = useA11yCloseButton(ref, {
    onClick: () => console.log('Closing!'),
  })

  return (
    <button ref={ref} {...a11yProps}>
      Clicking me closes the drawer content
    </button>
  )
}

<CloseButton>

This is a convenience component that wraps any React element and adds an onClick handler which closes the drawer.

Props

<CloseButton>
  <button className='my-button'>Close me</button>
</CloseButton>

// <button
//   class="my-button"
//   aria-controls="drawer--12"
//   aria-expanded="false"
// >
//   Close me
// </button>

useDrawer()

This hook provides the value of the drawer's DrawerContextValue object

DrawerContextValue

export interface DrawerContextValue {
  /**
   * The open state of the drawer
   */
  isOpen: boolean
  /**
   * Opens the drawer
   */
  open: () => void
  /**
   * Closes the drawer
   */
  close: () => void
  /**
   * Toggles the open state of the drawer
   */
  toggle: () => void
  /**
   * A unique ID for the drawer target
   */
  id?: string
}

Example

const Component = () => {
  const {open, close, toggle, isOpen} = useDrawer()
  return <button onClick={toggle}>Toggle the drawer</button>
}

LICENSE

MIT