@neo4j-ndl/react/skills/ndl-react/components/breadcrumbs.md

React implementation of Neo4j Design System

# Breadcrumbs

Import: `import { Breadcrumbs } from '@neo4j-ndl/react'`

## Props

### Breadcrumbs

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` |  |  | Content to be rendered. Should only be `Breadcrumbs.Item`. |
| `ref` | `Ref<HTMLElement>` |  |  | A ref to apply to the root element. |
| `shouldWrap` | `boolean` |  | `true` | Additional classnames. |

### Breadcrumbs.Button

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("a" & ElementType<any, keyof IntrinsicElements>) \| ... 177 more ... \| (FunctionComponent<...> & ElementType<...>)` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. What HTML element to render the root element as. |
| `children` | `ReactNode` |  |  | Content to be rendered. |
| `href` | `string` | ✅ |  | The href of the link. Only applicable if `as` is `'a'`. |
| `leadingElement` | `ReactNode` |  |  | Leading element to be rendered. |
| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Only applicable if `as` is `'button'`. |
| `ref` | `any` |  |  | A ref to apply to the root element. |
| `target` | `HTMLAttributeAnchorTarget` |  |  | The target of the link. Only applicable if `as` is `'a'`. |
| `trailingElement` | `ReactNode` |  |  | Trailing element to be rendered. |

### Breadcrumbs.Item

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` |  |  | Content to be rendered. Should be either `Breadcrumbs.Link`, `Breadcrumbs.Button` or `Breadcrumbs.SelectButton`. |
| `ref` | `Ref<HTMLLIElement>` |  |  | A ref to apply to the root element. |

### Breadcrumbs.Link

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaCurrent` | `boolean \| "time" \| "false" \| "true" \| "page" \| "step" \| "location" \| "date"` |  | `false` | Whether the link is the current item. Use `'page'` if it indicates the current page and `'step'` for steps (in a multi-step wizard for example). @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current |
| `as` | `("button" & ElementType<any, keyof IntrinsicElements>) \| ("a" & ElementType<any, keyof IntrinsicElements>) \| ... 177 more ... \| (FunctionComponent<...> & ElementType<...>)` |  |  | An override of the default HTML tag of the root of the component. Can also be another React component. What HTML element to render the root element as. |
| `children` | `ReactNode` |  |  | Content to be rendered. |
| `href` | `string` | ✅ |  | The href of the link. Only applicable if `as` is `'a'`. |
| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Only applicable if `as` is `'button'`. |
| `ref` | `any` |  |  | A ref to apply to the root element. |
| `target` | `HTMLAttributeAnchorTarget` |  |  | The target of the link. Only applicable if `as` is `'a'`. |

### Breadcrumbs.SelectButton

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `ariaLabel` | `string` | ✅ |  | Aria label needed for accessibility. |
| `children` | `ReactNode` |  |  | Content to be rendered. |
| `isActive` | `boolean` |  |  | Active - used when a connected menu is open |
| `onClick` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` |  |  | Event handler for when the button is clicked. Should be used to open a `Menu`. |
| `ref` | `Ref<HTMLButtonElement>` |  |  | A ref to apply to the root element. |

## Accessibility

## Implementation guidelines

- The `Link` has a `ariaCurrent` prop that should be set on the breadcrumb that is representing the current step or page, to the corresponding value.

- The `Button` can be used with both icon + text, text only or icon only. If you only provide an icon, to create a custom home breadcrumb e.g., make sure to set the `aria-label` in the `htmlAttributes` prop.

- The `SelectButton` is essentially an icon button, and therefore has a prop `ariaLabel` that is required for accessibility.

## Examples

### Ellipses

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Breadcrumbs, Menu } from '@neo4j-ndl/react';
import { useRef, useState } from 'react';

const Component = () => {
  const menuRef = useRef<HTMLButtonElement>(null);
  const [isMenuOpen, setIsMenuOpen] = useState(false);

  return (
    <Breadcrumbs>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="#">Home</Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link
          ref={menuRef}
          as="button"
          onClick={() => setIsMenuOpen(!isMenuOpen)}
          htmlAttributes={{
            'aria-label': 'Open ellipsis menu',
          }}
        >
          ...
          <Menu
            anchorRef={menuRef}
            isOpen={isMenuOpen}
            onClose={() => setIsMenuOpen(false)}
          >
            <Menu.Item title="Page 1" />
            <Menu.Item title="Page 2" />
            <Menu.Item title="Page 3" />
          </Menu>
        </Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link as="span" ariaCurrent="page">
          Current page
        </Breadcrumbs.Link>
      </Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

export default Component;
```

### Header

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Breadcrumbs, Menu } from '@neo4j-ndl/react';
import {
  BuildingOffice2IconOutline,
  FolderIconOutline,
  Neo4JIconColorIcon,
} from '@neo4j-ndl/react/icons';
import { useRef, useState } from 'react';

const Component = () => {
  const [isOrganizationMenuOpen, setIsOrganizationMenuOpen] = useState(false);
  const organizationMenuRef = useRef<HTMLButtonElement>(null);

  return (
    <Breadcrumbs shouldWrap={false}>
      <Breadcrumbs.Item className="n-mr-token-8">
        <button
          type="button"
          aria-label="Home"
          className="n-rounded-sm focus-visible:n-outline-2 focus-visible:n-outline-offset-[3px] focus-visible:n-outline-primary-focus n-shrink-0"
        >
          <Neo4JIconColorIcon className="n-h-6 n-w-[26px]" />
        </button>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Button leadingElement={<BuildingOffice2IconOutline />}>
          Organization 1
        </Breadcrumbs.Button>
        <Breadcrumbs.SelectButton
          ref={organizationMenuRef}
          ariaLabel="Open organization menu"
          onClick={() => {
            setIsOrganizationMenuOpen((prev) => !prev);
          }}
          isActive={isOrganizationMenuOpen}
        >
          <Menu
            anchorRef={organizationMenuRef}
            isOpen={isOrganizationMenuOpen}
            onClose={() => setIsOrganizationMenuOpen(false)}
          >
            <Menu.Group>
              <Menu.RadioItem title="Organization 1" isChecked={true} />
              <Menu.RadioItem title="Organization 2" isChecked={false} />
            </Menu.Group>
            <Menu.Divider />
            <Menu.Group>
              <Menu.Item title="All Organizations" />
            </Menu.Group>
          </Menu>
        </Breadcrumbs.SelectButton>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Button leadingElement={<FolderIconOutline />}>
          Project 1
        </Breadcrumbs.Button>
        <Breadcrumbs.SelectButton ariaLabel="Open project menu"></Breadcrumbs.SelectButton>
      </Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

export default Component;
```

### Pages

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Breadcrumbs } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <Breadcrumbs>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="">Home</Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="">Page</Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="">Subpage</Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="" ariaCurrent="page">
          Current page
        </Breadcrumbs.Link>
      </Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

export default Component;
```

### Steps

```tsx
import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';

import { Breadcrumbs } from '@neo4j-ndl/react';

const Component = () => {
  return (
    <Breadcrumbs>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="">Previous step</Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="" ariaCurrent="step">
          Current step
        </Breadcrumbs.Link>
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="">Next step</Breadcrumbs.Link>
      </Breadcrumbs.Item>
    </Breadcrumbs>
  );
};

export default Component;
```