Breadcrumbs

The breadcrumbs component is a navigation list used to visualize the information architecture of a website and the users current place in the hierarchy.

ARIA pattern Theme source React source Feedback

Usage

Import the Breadcrumbs component and and render individual Breadcrumbs.Items with a Breadcrumbs.Link inside. The current breadcrumb should use the isCurrent prop which sets the appropriate aria attributes.

import { Breadcrumbs } from '@aws-amplify/ui-react';

export default function DefaultBreadcrumbsExample() {
  return (
    <Breadcrumbs
      items={[
        {
          href: '/',
          label: 'Home',
        },
        {
          href: '/react/components',
          label: 'Components',
        },
        {
          label: 'Breadcrumbs',
        },
      ]}
    />
  );
}

Custom separator

You can customize the separator between breadcrumb links with the separator prop.

import { Breadcrumbs } from '@aws-amplify/ui-react';

export default function CustomSeparatorExample() {
  return (
    <Breadcrumbs
      items={[
        {
          href: '/',
          label: 'Home',
        },
        {
          href: '/react/components',
          label: 'Components',
        },
        {
          label: 'Breadcrumbs',
          isCurrent: true,
        },
      ]}
      separator={<Breadcrumbs.Separator>|</Breadcrumbs.Separator>}
    />
  );
}

Custom separator with icon

import { Breadcrumbs } from '@aws-amplify/ui-react';
import { MdChevronRight } from 'react-icons/md';

export default function CustomSeparatorIconExample() {
  return (
    <Breadcrumbs
      items={[
        {
          href: '/',
          label: 'Home',
        },
        {
          href: '/react/components',
          label: 'Components',
        },
        {
          label: 'Breadcrumbs',
        },
      ]}
      separator={<MdChevronRight />}
    />
  );
}

No separator

import { Breadcrumbs } from '@aws-amplify/ui-react';

export default function NoSeparatorExample() {
  return (
    <Breadcrumbs
      items={[
        {
          href: '/',
          label: 'Home',
        },
        {
          href: '/react/components',
          label: 'Components',
        },
        {
          label: 'Breadcrumbs',
        },
      ]}
      separator={null}
    />
  );
}

Composable

The sub-components of the Breadcrumbs component are exposed so you can compose the Breadcrumbs however you want. With the composable API you can full control over what is rendered and unlock more advanced use-cases.

<Breadcrumbs.Container>
<Breadcrumbs.Item>
<Breadcrumbs.Link>
<Breadcrumbs.Separator>

Beginning and ending separator

import { Breadcrumbs } from '@aws-amplify/ui-react';

export default function ComposableBreadcrumbsExample() {
  return (
    <Breadcrumbs.Container>
      <Breadcrumbs.Item>
        <Breadcrumbs.Separator />
        <Breadcrumbs.Link href="/">Home</Breadcrumbs.Link>
        <Breadcrumbs.Separator />
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="/react/components">Components</Breadcrumbs.Link>
        <Breadcrumbs.Separator />
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="/react/components/breadcrumbs" isCurrent>
          Breadcrumbs
        </Breadcrumbs.Link>
        <Breadcrumbs.Separator />
      </Breadcrumbs.Item>
    </Breadcrumbs.Container>
  );
}

NextJS

You can use Breacrumbs with NextJS's Link component and useRouter to automatically generate the breadcrumbs based on the current path.

import NextLink from 'next/link';
import { Breadcrumbs } from '@aws-amplify/ui-react';
import { useRouter } from 'next/router';

export default function NextBreadcrumbsExample() {
  const { asPath } = useRouter();

  const nestedRoutes = asPath
    .split('#')[0]
    .split('?')[0]
    .split('/')
    .filter((subpath) => subpath.length > 0);

  const breadcrumbs = [
    { href: '/', text: 'Home' },
    ...nestedRoutes.map((subpath, i) => {
      const href = '/' + nestedRoutes.slice(0, i + 1).join('/');

      const text = subpath;
      return { href, text };
    }),
  ];

  return (
    <Breadcrumbs.Container>
      {breadcrumbs.map(({ href, text }, i) => {
        const isCurrent = i === breadcrumbs.length - 1;
        return (
          <Breadcrumbs.Item key={href}>
            <NextLink href={href} passHref legacyBehavior>
              <Breadcrumbs.Link isCurrent={isCurrent}>{text}</Breadcrumbs.Link>
            </NextLink>
            {isCurrent ? null : <Breadcrumbs.Separator />}
          </Breadcrumbs.Item>
        );
      })}
    </Breadcrumbs.Container>
  );
}

import { Breadcrumbs, SelectField } from '@aws-amplify/ui-react';

export default function BreadcrumbsWithDropdownExample() {
  return (
    <Breadcrumbs.Container>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="/">Home</Breadcrumbs.Link>
        <Breadcrumbs.Separator />
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <Breadcrumbs.Link href="/react/components">Components</Breadcrumbs.Link>
        <Breadcrumbs.Separator />
      </Breadcrumbs.Item>
      <Breadcrumbs.Item>
        <SelectField
          label="branch"
          labelHidden
          variation="quiet"
          size="small"
          options={['Breadcrumbs', 'Breadcrumbs.Item', 'Breadcrumbs.Link']}
        />
      </Breadcrumbs.Item>
    </Breadcrumbs.Container>
  );
}

Styling

Theme

You can customize the appearance of all Breadcrumbs components in your application with a Theme.

Breadcrumbs Theme Source

import { Breadcrumbs, ThemeProvider, createTheme } from '@aws-amplify/ui-react';

const theme = createTheme({
  name: 'breadcrumbs-theme',
  tokens: {
    components: {
      breadcrumbs: {
        separator: {
          color: '{colors.secondary.20}',
          fontSize: '{fontSizes.xl}',
          paddingInline: '{space.medium}',
        },
        link: {
          current: {
            color: '{colors.secondary.80}',
          },
        },
      },
    },
  },
});

export default function BreadcrumbsThemeExample() {
  return (
    <ThemeProvider theme={theme}>
      <Breadcrumbs
        items={[
          {
            href: '/',
            label: 'Home',
          },
          {
            href: '/react/components',
            label: 'Components',
          },
          {
            label: 'Breadcrumbs',
          },
        ]}
      />
    </ThemeProvider>
  );
}

Target classes

Class	Description
`amplify-breadcrumbs`	Top level element that wraps the Breadcrumbs component
`amplify-breadcrumbs__item`	Each breadcrumb
`amplify-breadcrumbs__link`	Links used within breadcrumbs
`amplify-breadcrumbs__list`	List element within nav
`amplify-breadcrumbs__separator`	Separator between each breadcrumb

--amplify-components-breadcrumbs-color
--amplify-components-breadcrumbs-flex-direction
--amplify-components-breadcrumbs-flex-wrap
--amplify-components-breadcrumbs-gap
--amplify-components-breadcrumbs-item-align-items
--amplify-components-breadcrumbs-item-color
--amplify-components-breadcrumbs-item-flex-direction
--amplify-components-breadcrumbs-item-font-size
--amplify-components-breadcrumbs-item-line-height
--amplify-components-breadcrumbs-link-color
--amplify-components-breadcrumbs-link-current-color
--amplify-components-breadcrumbs-link-current-font-size
--amplify-components-breadcrumbs-link-current-font-weight
--amplify-components-breadcrumbs-link-current-text-decoration
--amplify-components-breadcrumbs-link-font-size
--amplify-components-breadcrumbs-link-font-weight
--amplify-components-breadcrumbs-link-padding-block
--amplify-components-breadcrumbs-link-padding-inline
--amplify-components-breadcrumbs-link-text-decoration
--amplify-components-breadcrumbs-separator-color
--amplify-components-breadcrumbs-separator-font-size
--amplify-components-breadcrumbs-separator-padding-inline

Global styling

To override styling on all Breadcrumbs components, you can set Amplify CSS variables or use the target classes like .amplify-breadcrumbs class.

/* styles.css */
.amplify-breadcrumbs {
  background-color: pink;
}

Local styling

To override styling on a specific Breadcrumbs component or sub-component, you can use (in order of increasing specificity): a class selector and style props.

Using a class selector:

<Breadcrumbs className="my-breadcrumbs">
</Breadcrumbs>

/* styles.css */
.my-breadcrumbs {
   background-color: pink;
}

Using style props:

import { Breadcrumbs } from '@aws-amplify/ui-react';

const breadcrumbs = [
  {
    href: '/',
    text: 'Home',
  },
  {
    href: '/react/components',
    text: 'Components',
  },
  {
    text: 'Breadcrumbs',
    isCurrent: true,
  },
];

export default function BreadcrumbsStyleExample() {
  return (
    <Breadcrumbs.Container
      backgroundColor="background.tertiary"
      borderRadius="medium"
      padding="medium"
    >
      {breadcrumbs.map(({ href, text, isCurrent }, idx) => (
        <Breadcrumbs.Item key={`${href}${idx}`}>
          <Breadcrumbs.Link
            fontWeight="bold"
            textDecoration="underline"
            href={href}
            isCurrent={isCurrent}
          >
            {text}
          </Breadcrumbs.Link>
        </Breadcrumbs.Item>
      ))}
    </Breadcrumbs.Container>
  );
}

Accessibility

https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/

The Breadcrumbs component is a nav element to let browsers know it is for navigation, with aria-label="Breadcrumbs" to identify it as breadcrumbs
The list of links is rendered in an ordered list, ol
Separators have aria-hidden="true" so they are not announced by screen readers
Use the isCurrent prop for the current element in the navigation which sets aria-current="page" and aria-disabled="true" on the link.