---
name: Dropdown
menu: Components
route: /components/dropdown
---

import { Playground, PropsTable } from 'docz'
import { Button, Icon, Text } from '@personio/ui-components'
import { Dropdown } from '@personio/ui-components'
import { State, Toggle } from 'react-powerplug'
import styles from './dropdown.scss'

# Dropdown
Toggle contextual overlays for displaying lists of links and more with the Personio dropdown component.

## Overview
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. They’re toggled by clicking, not by hovering.

You can control the state using a prop (controlled approach) or make the component work alone, with a internal state (not controlled approach).

<PropsTable of={Dropdown} />

## Example (not controlled)
The example bellow shows the easiest way to use the Dropdown, using an uncontrolled approach.

<Playground>
  <div className="dropdown-container">
    <Dropdown>
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List>
        <Dropdown.Item href="https://www.personio.de/" target="_blank" rel="nooponer noreferrer">
          Your account
        </Dropdown.Item>
        <Dropdown.Item href="https://www.personio.de/" target="_blank" rel="nooponer noreferrer">
          Your settings
        </Dropdown.Item>
        <Dropdown.Item onClick={() => {
          alert('Logout')
        }}>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>


## Example starting opened (not controlled)
The example bellow shows the easiest way to use the Dropdown, using an uncontrolled approach.

<Playground>
  <div className="dropdown-container">
    <Dropdown defaultValue={true}>
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List>
        <Dropdown.Item href="https://www.personio.de/" target="_blank" rel="nooponer noreferrer">
          Your account
        </Dropdown.Item>
        <Dropdown.Item href="https://www.personio.de/" target="_blank" rel="nooponer noreferrer">
          Your settings
        </Dropdown.Item>
        <Dropdown.Item onClick={() => {
          alert('Logout')
        }}>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>

## Callbacks (not controlled)

<Playground>
  <div className="dropdown-container">
    <Dropdown
      onChange={() => console.log('onChange')}
      beforeOpen={() => console.log('beforeOpen')}
      onOpen={() => console.log('onOpen')}
      beforeClose={() => console.log('beforeClose')}
      onClose={() => console.log('onClose')}
    >
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List>
        <Dropdown.Item
          onClick={(e) => {
            console.log(e)
          }}
        >Your account</Dropdown.Item>
        <Dropdown.Item>Your settings</Dropdown.Item>
        <Dropdown.Item>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>

## Preventing to close

<Playground>
  <div className="dropdown-container">
    <Dropdown>
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List preventToCloseOnClick>
        <Dropdown.Item hovered>Your account</Dropdown.Item>
        <Dropdown.Item>Your settings</Dropdown.Item>
        <Dropdown.Item>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>

## Example (controlled)

<Playground>
  <div className="dropdown-container">
    <State initial={{ open: false }}>
      {({ state, setState }) => (
        <Dropdown open={state.open} onRequestToChange={() => {
          setState({ open: !state.open })
        }}>
          <Dropdown.Toggle>
            <Button>
              Hanno Renner
            </Button>
          </Dropdown.Toggle>
          <Dropdown.List>
            <Dropdown.Item>Your account</Dropdown.Item>
            <Dropdown.Item>Your settings</Dropdown.Item>
            <Dropdown.Item>
              Logout
            </Dropdown.Item>
          </Dropdown.List>
        </Dropdown>
      )}
    </State>
  </div>
</Playground>


## Callbacks (controlled)

<Playground>
  <div className="dropdown-container">
    <State initial={{ open: false }}>
      {({ state, setState }) => (
        <Dropdown open={state.open} onRequestToChange={() => {
          setState({ open: !state.open })
        }}>
          <Dropdown.Toggle>
            <Button>
              Hanno Renner
            </Button>
          </Dropdown.Toggle>
          <Dropdown.List>
            <Dropdown.Item>Your account</Dropdown.Item>
            <Dropdown.Item>Your settings</Dropdown.Item>
            <Dropdown.Item>
              Logout
            </Dropdown.Item>
          </Dropdown.List>
        </Dropdown>
      )}
    </State>
  </div>
</Playground>

## Disabled item

<Playground>
  <div className="dropdown-container">
    <Dropdown>
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List>
        <Dropdown.Item>Your account</Dropdown.Item>
        <Dropdown.Item disabled>Your settings</Dropdown.Item>
        <Dropdown.Item>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>

## Hovered item

<Playground>
  <div className="dropdown-container">
    <Dropdown>
      <Dropdown.Toggle>
        <Button>
          Hanno Renner
        </Button>
      </Dropdown.Toggle>
      <Dropdown.List>
        <Dropdown.Item hover>Your account</Dropdown.Item>
        <Dropdown.Item>Your settings</Dropdown.Item>
        <Dropdown.Item>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>

## Position

<Playground>
  <div className="dropdown-container-center">
    <Dropdown>
      <Dropdown.Toggle>
        <Button name="ellipsis-h" />
      </Dropdown.Toggle>
      <Dropdown.List direction="bottom-right">
        <Dropdown.Item hover>Your account</Dropdown.Item>
        <Dropdown.Item>Your settings</Dropdown.Item>
        <Dropdown.Item>
          Logout
        </Dropdown.Item>
      </Dropdown.List>
    </Dropdown>
  </div>
</Playground>
