npm package: @highlight-ui/accordion
Description: Accordion and Expandable components for Highlight UI
Author: Personio GmbH & Co. KG
Latest version: 5.1.15

[![npm](https://img.shields.io/npm/v/@highlight-ui/accordion)](https://www.npmjs.com/package/@highlight-ui/accordion)
[![personio.design](https://img.shields.io/static/v1?label=Personio&message=zeroheight&color=yellow)](https://www.personio.design/40d648a47/v/0/p/525fe1-accordion)
[![storybook.personio.design](https://img.shields.io/static/v1?label=Personio&message=storybook&color=red)](https://storybook.personio.design/?path=/story/content-structure-accordion--basic-story)

# @highlight-ui/accordion

## Installation

Using npm:

```bash
npm install @highlight-ui/accordion
```

Using yarn:

```bash
yarn add @highlight-ui/accordion
```

Using pnpm:

```bash
pnpm install @highlight-ui/accordion
```

In your (S)CSS file:

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

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

```ts
import {
  Accordion,
  AccordionProps,
  AccordionSection,
  Expandable,
  ExpandableProps,
} from '@highlight-ui/accordion';
```

### Performance Tips

Once the package is installed, you can import the library. The Accordion component depends on [React DND](https://react-dnd.github.io/react-dnd/about), which is a relatively heavy dependency. This component's package is tree shakeable, if you do not need the drag-and-drop functionalities you can import the `StaticAccordion` component instead of the `Accordion` component.

```ts
import { StaticAccordion } from '@highlight-ui/accordion';
```

If you only need the drag-and-drop functionalities of the component, you can import
the `DraggableAccordion` component:

```ts
import { DraggableAccordion } from '@highlight-ui/accordion';
```

## Usage

### Standard Accordion

```tsx
import React, { useState } from 'react';
import { Accordion } from '@highlight-ui/accordion';

export default function AccordionExample() {
  return (
    <Accordion
      sections={
        ({
          key: '1',
          title: 'Title 1',
          content: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
        },
        {
          key: '2',
          title: 'Title 2',
          disabled: true,
          content: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
        },
        {
          key: '3',
          title: 'Title 3',
          content: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit.',
        })
      }
    />
  );
}
```

### Accordion with actions

```tsx
import React, { useState } from 'react';
import { Accordion } from '@highlight-ui/accordion';
import { Button } from '@highlight-ui/button';
import { Input } from '@highlight-ui/input';

export default function AccordionExample() {
  return (
    <Accordion
      sections={[
        {
          key: '1',
          title: 'Title 1',
          actions: (
            <Button variant="emphasized" onClick={() => alert('Hello')}>
              Click me
            </Button>
          ),
          content: (
            <div>
              <Button>A focusable button</Button>
              <Input placeholder="A focusable input" />
              <p>Lorem ipsum dolor sit amet consectetur adipisicing elit.</p>
            </div>
          ),
        },
        {
          key: '2',
          title: 'Title 2',
          actions: (
            <Button variant="emphasized" onClick={() => alert('Hello')}>
              Click me
            </Button>
          ),
          content: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
        },
      ]}
    />
  );
}
```

## Props 📜

### Accordion

| Prop                       | Type                                                                       | Required | Default | Description                                                                                                                |
| :------------------------- | :------------------------------------------------------------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------------------------- |
| `sections`                 | `AccordionSection`                                                         | Yes      |         | An array of `AccordionSection` data structure                                                                              |
| `selectable`               | `boolean`                                                                  | No       | `false` | Should segments be selectable using a checkbox                                                                             |
| `selectableSections`       | `AccordionSection`                                                         | No       |         | Indicates the selected checkboxes in sections                                                                              |
| `mutltiple`                | `boolean`                                                                  | No       | `false` | Should multiple sections remain open                                                                                       |
| `initiallyOpen`            | `AccordionSection`                                                         | No       |         | The sections which are open by default. In case `multiple` is set to `false`, only the first array element will be opened. |
| `onExpansionChange`        | `(section: AccordionSection, isExpanded: boolean, index: number ) => void` | No       |         | Callback fired whenever the section opens or closes.                                                                       |
| `onSelectedSectionsChange` | `(sections: AccordionSection[]) => void`                                   | No       |         | Will be called with each selection change when the `selectable` prop is `true`.                                            |
| `dragProps`                | `DragProps<AccordionSection, D>`                                           | No       |         | Configuration for drag-and-drop capabilities.                                                                              |

### Custom types 🔠

| Type               | Values                                                                                                                                                        | Description                        |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------- |
| `AccordionSection` | `{key: string, title: React.ReactNode, content: React.ReactNode, actions?: React.ReactNode, disabled? boolean}`                                               | Used for a number of section props |
| `DragProps`        | Provided by the `drag-and-drop` utility [package](https://gitlab.personio-internal.de/personio/platform/highlight-ui/-/tree/master/packages/ui/drag-and-drop) |                                    |

## Contributing 🖌️

Please visit [personio.design](https://www.personio.design/40d648a47/v/0/p/0289d5-accordion/b/26fe12) 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).