ankit-m/react-16-dropdown

A zero-dependency, lightweight and fully customizable dropdown (not select) for React.

react-16-dropdown

A zero-dependency, lightweight and fully customizable dropdown (not select) for React. You can find examples here

Installation

npm install --save react-16-dropdown

Basic usage

import Dropdown from 'react-16-dropdown';

const options = [{
  label: 'Prestige 🎩',
  value: 'prestige',
}, {
  label: 'Inception 😴',
  value: 'inception',
}];

<Dropdown
  align='left'
  className='custom-classname'
  closeOnEscape={true}
  options={options}
  triggerLabel='Movies 🍿'
  onClick={val => console.log(val)}
/>

Supported props

You can pass the following props to the Dropdown component -

Name	Default	Allowed values	Description
align	left	left, right	Decides the alignment of the menu w.r.t trigger
autoFocus	false	Boolean	Should the trigger be focused by default
className	''	String	Adds the given class to the wrapper element
closeOnClickOutside	true	Boolean	Should the dropdown menu close on clicking outside the menu
closeOnEscape	true	Boolean	Should the dropdown menu close on pressing Escape
closeOnOptionClick	true	Boolean	Should the dropdown close when option is clicked
disabled	false	Boolean	Disable the trigger
id	undefined	String	HTML attribute id for the wrapper component
focused	undefined	String	Default focused component in controlled mode
menuComponent	Menu⁽¹⁾ ⁽²⁾	ReactElement	Component to replace the default menu
menuPortalTarget	body	String	Selector for the portal to be attached as a child to
menuRenderer	MenuRenderer⁽¹⁾	ReactElement	Component to render the menu
menuSectionRenderer	MenuRenderer⁽¹⁾	ReactElement	Component to render menu sections
onClick*	undefined	Function	Handler for option click event
onClose	undefined	Function	Function to be called when menu closes
onOpen	undefined	Function	Function to be called when menu opens
onMenuKeyDown	undefined	Function	Function to be called when keydown event is triggered on the menu or bubbled up from option
onTriggerClick	undefined	Function	Function to be called when the trigger element is clicked
onTriggerKeyDown	undefined	Function	Function to be called when a key is pressed on the trigger
open	undefined	Boolean	Prop to control open/closed state of the menu
optionComponent	Option⁽¹⁾ ⁽²⁾	ReactElement	Component to replace the default option
optionRenderer	OptionRenderer⁽¹⁾	ReactElement	Component to render option
options*	undefined	Array	An array of objects
portalClassName	''	String	Adds the given class to portal component
sections	undefined	Array	Sections array for menu with sections
triggerComponent	Trigger⁽¹⁾ ⁽²⁾	ReactElement	Component to replace the default trigger
triggerLabel	Open menu	String	Text for the default trigger button
triggerRenderer	TriggerRenderer⁽¹⁾	ReactElement	Component to render the trigger

The options prop is an array of objects. Each object can have the following keys -

Key	Value	Description
value*	String	Unique identifier for each option
label*	<String	ReactElement>
className	String	Custom class name for the option
disabled	Boolean	Is the option disabled?

In case you are using sections you need to pass the sections prop, which is an array of objects. Each object can have the following keys -

Key	Value	Description
id*	String	Unique identifier for each section
options*	Array	Array of options under this section
title	<String	ReactElement>
className	String	Custom class name for section

⁽¹⁾ Default internal component

⁽²⁾ If you replace the component (instead of using renderers), you will have to pass down all the handlers, refs and other props down to your components.

* Required props

Customization

You can customize any part of the dropdown to suit your needs. In most cases, modifying existing classes/adding your own classes should do the trick. For advanced use cases, you can use custom render components. If you want to take over individual components of the dropdown, you can replace the menu, option or trigger default components.

Using renderers -

<Dropdown
  options={colorOptions}
  triggerRenderer={() => <button className='btn btn-dark ml-2'>Option renderer</button>}
  optionRenderer={props => <div className={`option option--${props.value}`}>{props.label}</div>}
  onClick={e => console.log(e)}
/>

Using components -

function CustomButtonComponent(props) {
  return (
    <a
      className='btn btn-outline-info'
      ref={props.triggerRef}
      onClick={props.onClick}
      onKeyDown={props.onKeyDown}
    >
      Custom link component
    </a>
  );
}

<Dropdown
  options={options}
  triggerComponent={CustomButtonComponent}
  onClick={e => console.log(e)}
/>

Controlled Component

You can also use the dropdown as a controlled component if you pass the open prop.

<Dropdown
  open={true}
  options={options}
  onTriggerClick={() => { /* do something */ }}
  onClick={e => console.log(e)}
/>

Sections

Dropdown sections with titles are also supported. Although, you can only have one level of sections. Instead of the options array, you need to pass the sections, which is an array of sections containing options. You need to pass a unique id for each section.

const sections = [{
  title: 'Movies',
  id: 'movies',
  options: movieOptions,
}, {
  title: 'Fruits',
  id: 'fruits',
  options: fruitOptions,
}];

<Dropdown
  closeOnEscape
  sections={sections}
  triggerLabel='Sections'
  onClick={e => console.log(e)}
/>