npm package: @highlight-ui/dropdown-menu
Description: Dropdown Menu Component
Author: Personio GmbH & Co. KG
Latest version: 3.3.10

[![npm](https://img.shields.io/npm/v/@highlight-ui/dropdown-menu)](https://www.npmjs.com/package/@highlight-ui/dropdown-menu)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/84a8e8-dropdown-menu/b/118c63)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/feedback-circularprogress--default)

# @highlight-ui/dropdown-menu

## Installation

Using npm:

```bash
npm install @highlight-ui/dropdown-menu
```

Using yarn:

```bash
yarn add @highlight-ui/dropdown-menu
```

Using pnpm:

```bash
pnpm install @highlight-ui/dropdown-menu
```

In your (S)CSS file:

```scss
@import url('@highlight-ui/dropdown-menu');
```

Once the package is installed, you can import the library:

```ts
import {
  DropdownMenu,
  DropdownMenuItem,
  DropdownMenuList,
  DropdownMenuToggle,
} from '@highlight-ui/dropdown-menu';
```

## Usage

```tsx
import React from 'react';
import {
  DropdownMenu,
  DropdownMenuToggle,
  DropdownMenuList,
  DropdownMenuItem,
} from '@highlight-ui/dropdown-menu';
import { Button } from '@highlight-ui/button';

export default function DropdownMenuExample() {
  return (
    <DropdownMenu>
      <DropdownMenuToggle>
        <Button buttonState={disabled ? 'disabled' : undefined}>
          Toggle Me!
        </Button>
      </DropdownMenuToggle>
      <DropdownMenuList direction={direction} title={title}>
        <DropdownMenuItem
          onClick={() => {
            console.log('clicked!');
          }}
        >
          Item label (as Button)
        </DropdownMenuItem>
        <DropdownMenuItem
          href="https://personio.com"
          target="_blank"
          rel="noopener noreferrer"
        >
          Item label (as Link)
        </DropdownMenuItem>
        <DropdownMenuItem disabled>Item label (disabled)</DropdownMenuItem>
      </DropdownMenuList>
    </DropdownMenu>
  );
}
```

## Props 📜

### DropdownMenu

| Prop                   | Type         | Required | Default | Description                                                                                                                      |
| :--------------------- | :----------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------------- |
| `open`                 | `boolean`    | No       | `false` | Whether the dropdown is open or not                                                                                              |
| `defaultValue`         | `boolean`    | No       | `false` | Default open value                                                                                                               |
| `className`            | `string`     | No       |         | Allows providing a custom class name to the DIV element that surrounds the text                                                  |
| `closeOnClickAnywhere` | `boolean`    | No       | `false` | Enables closing the dropdown menu when clicking inside                                                                           |
| `disabled`             | `boolean`    | No       | `false` | Prevents the open state of the dropdown menu from changing (Only works when the `open` prop is _not_ being used)                 |
| `onChange`             | `() => void` | No       |         | Callback triggered whenever the open state of the dropdown menu is changed (Only works when the `open` prop is _not_ being used) |
| `onClose`              | `() => void` | No       |         | Callback triggered whenever the dropdown menu is closed (Only works when the `open` prop is _not_ being used)                    |
| `onOpen`               | `() => void` | No       |         | Callback triggered whenever the dropdown menu is opened (Only works when the `open` prop is _not_ being used)                    |
| `onRequestToChange`    | `() => void` | No       |         | Callback triggered when the open state of the dropdown menu is about to change (Only works when the `open` prop is in use)       |

### DropdownMenuToggle

| Prop        | Type         | Required | Default | Description                                                                |
| :---------- | :----------- | :------- | :------ | :------------------------------------------------------------------------- |
| `className` | `string`     | No       |         | Allows providing a custom class name to the toggle                         |
| `disabled`  | `boolean`    | No       | `false` | Prevents the open state of the dropdown menu from changing                 |
| `onToggle`  | `() => void` | No       |         | Callback triggered whenever the open state of the dropdown menu is changed |

### DropdownMenuList

| Prop                    | Type                                                               | Required | Default        | Description                                                                |
| :---------------------- | :----------------------------------------------------------------- | :------- | :------------- | :------------------------------------------------------------------------- |
| `open`                  | `boolean`                                                          | No       | `false`        | Whether the dropdown is open or not                                        |
| `className`             | `string`                                                           | No       |                | Allows providing a custom class name to the list                           |
| `containerWidth`        | `number`                                                           | No       | `0`            | The max width of the container                                             |
| `direction`             | `'bottom-left', 'bottom-right', 'center', 'top-left', 'top-right'` | No       | `bottom-right` | The direction that the menu should open from - relative to the trigger     |
| `onToggle`              | `() => void`                                                       | No       |                | Callback triggered whenever the open state of the dropdown menu is changed |
| `preventToCloseOnClick` | `boolean`                                                          | No       | `false`        | Prevents the close on click                                                |
| `title`                 | `string`                                                           | No       |                | Gives this dropdown a title                                                |

### DropdownMenuItem

> The DropdownMenuItem gets its props from the `a` and `button` types.

## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/84a8e8-dropdown-menu/b/118c63) for usage guidelines and visual examples.

If you're interested in contributing, please visit our [contribution page](https://www.personio.design/40d648a47/v/0/p/138faf-about-the-process).