react-a11y-dropdown

An fully accessible and unopinionated dropdown component for React with full keyboard support.

The goal with React A11y Dropdown is to help build accessible dropdown menus by providing the required functionality, keyboard interactions and ARIA attributes to meet accessibilility best practices as determined by w3.org Menu Button spec.

→ View Examples

Features

• Button: Creates a button to toggle the state (open/closed) of the dropdown menu.
• Aria Attributes: Adds required aria attributes to the button and dropdown components.
• Keyboard Controls: Enables keyboard controls to tab and arrow key seemlessly through focusable elements within the dropdown component.
• Letter Navigation: Character search by first letter when focus is on an expanded dropdown menu.

Note: This component does not style the contents of the dropdown. Its simply a wrapper for your existing components and will inherit application styling as required.

Accessibility

Meeting W3.org accessiblitiy guidelines on interactive components requires a lot of thought, planning and custom JavaScript. The idea with react-a11y-dropdowns is to keep all that complex functionality inside a single component so you don't have to worry about it.

This component follows the best practices that have been set out by the W3.org with regards to dropdowns and menu button controls by enabling keyboard controls (up, down, home, end, esc), adding the proper aria attributes and providing a first letter search when interacting with a dropdown menu.

Install

# With npm
npm i react-a11y-dropdown

# With Yarn
yarn add react-a11y-dropdown

Usage

import DropDown from 'react-a11y-dropdown'

export default function App() {
   return (
      <DropDown label="Development Resources">
         <ul>
            <li>
               <a href="https://github.com/">Github</a>
            </li>
            <li>
               <a href="https://www.npmjs.com/">NPM</a>
            </li>
            <li>
               <a href="https://www.reactjs.org">React</a>
            </li>
         </ul>
      </DropDown>
   )
}

Props

The DropDown component accepts the following props.

| Prop | Description | Type | Default | Required | | ------------------------- | --------------------------------------------------------------------------------------- | ------- | ------- | -------- | | id | The component ID - if not specified an ID will be generated randomly. | string | null | Yes | | label | The text for the generated button toggle - HTML is accepted. | string | null | Yes | | className | Classnames for the dropdown container. | string | null | No | | activeClassName | Classnames for the dropdown container while in an expanded state. | string | null | No | | buttonClassName | Classnames for the button element. | string | null | No | | activeButtonClassName | Classnames for the button element while in an expanded state. | string | null | No | | dropdownClassName | Classnames for the dropdown element. | string | null | No | | activeDropdownClassName | Classnames for the dropdown element while in an expanded state. | string | null | No | | useStyles | Use built-in CSS styles from component. | boolean | true | No | | isMenu | Is this a menu button group? If true, the appropriate aria attributes will be added. | boolean | true | No | | search | Enbale searching dropdown menu contents by first letter when dropdown is in open state. | boolean | false | No | | href | Add a link/href to the button element and make it a clickable link. | string | null | No | | onHover | Allow mouse hover to open dropmenu. | boolean | false | No | | config | Modify the component CSS styles via config prop. | object | null | No |

return (
   <DropDown
      label="Button Label"
      id="dropdown"
      className="my-dropdown"
      buttonClassName="text-md text-blue-600 bg-blue-50",
      config={{
         button: {
            background: '#fff',
            borderColor: '#cccccc',
            color: '#111111',
            hover: {
               background: '#111111',
               borderColor: '#111111',
               color: '#fff'
            }
         }
      }}
   >
      <YourComponent>{children}</YourComponent>
   </DropDown>
)

Config

The DropDown component can be fully styled passing in updated options via the config prop.

return (
   <DropDown
      label="Show Menu"
      config={{
         button: {
            background: '#fff',
            border: null,
            color: '#ff0000',
            hover: {
               background: '#121212',
               color: '#fff',
            }
         }
      }}
   >
      <YourComponent>{children}</YourComponent>
   </DropDown>
)

Config Defaults

The following default CSS properties are passed into the DropDown component and can be modified using the config prop.

{
   button: { 
      display: 'block',
      background: '#eef1f4',
      border: '1px solid #d6d9dc',
      borderRadius: '3px',
      color: '#494a4c',
      fontSize: '14px',
      fontWeight: '500',
      margin: '0',
      padding: '8px 12px',
      transition: null,
      width: null,
      hover: {
         background: '#eaedef',
         borderColor: '#c1c3c6',
         borderRadius: null,
         color: '#242526'
      },
      active: {
         background: null,
         borderColor: null,
         borderRadius: null,
         color: null
      }
   },
   dropdown: {
      background: '#fff',
      border: '1px solid #d6d9dc',
      borderRadius: '3px',
      bottom: null,
      boxShadow: '0 8px 16px rgba(88, 92, 95, 0.1)',
      display: 'block',
      left: '0',
      margin: '5px 0 0',
      padding: '10px',
      position: 'absolute',
      right: null,
      transform: null,
      transition: 'all 0.15s ease',
      top: '100%',
      width: '250px',
      zIndex: 99999,
      active: {
         bottom: null,
         display: null,
         left: null,
         right: null,
         top: null,
         transform: null
      }
   },
   container: {
      width: 'auto'
   }
}

Notes

• The active object properties are applied when the DropDown component is in an expanded state.
• Setting a property to null will prevent the CSS property from being attached to the component.

CSS Styling

Some basic styles are provided via Styled Components for the <button/> trigger and dropdown elements (see markup below). The contents of the dropdown are not styled in any way and it will inherit your current application styles.

I've done my best to only provide styling for things that were absolutely necessary to acheive a modern look and feel for the default component.

Rendered Markup

<!-- Closed -->
<div class="react-a11y-dropdown">
   <button class="react-a11y-dropdown--button">Open Menu</button>
   <div class="react-a11y-dropdown--menu">
      <!-- Your Component Here -->
   </div>
</div>

<!-- Opened -->
<div class="react-a11y-dropdown expanded">
   <button class="react-a11y-dropdown--button active">Open Menu</button>
   <div class="react-a11y-dropdown--menu active">
      <!-- Your Component Here -->
   </div>
</div>

Custom Styles

Instead of providing a CSS file to be imported directly into your application, I've created a config prop that is passed into the <DropDown/> component that can modify existing styles on the fly.

return (
   <DropDown
      label="Button Label"
      config={{
         button: {
            background: '#f7f7f7',
            color: '#999',
            hover: {
               background: '#111111',
               color: '#fff'
            }
         }
      }}
   >
      <YourComponent>{children}</YourComponent>
   </DropDown>
)

Remove Styles

You can always roll your own styles and remove default component styling by setting the useStyles prop.

<DropDown label="Button Label" useStyles={false}>
   <YourComponent>{children}</YourComponent>
</DropDown>

Note: With useStyles set to false all styling will be removed with the exception of the visibility and opacity styles that are used to show/hide the dropdown component.

Development Features/Notes

Ideas and features to add in future development.

• The ability to add theming and allow for switching preset styles via component prop.
• Full text search along with letter navigation to enhance the letter searching.