Breadcrumbs

기본 사용법

Breadcrumbs는 데이터 기반으로 동작하며, 트리 구조의 메뉴 데이터를 받아 선택된 경로를 표시합니다.

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';

const menuData = [
  {
    id: 1,
    label: 'Home',
    href: '/',
    children: [{ id: 2, label: 'Docs', href: '/docs', children: [] }],
  },
];

<Breadcrumbs
  data={menuData}
  keyField="id"
  childrenField="children"
  labelField="label"
  hrefField="href"
  selectedId={2}
/>;

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';

export default function Preview() {
  const menuData = [
    {
      id: 1,
      label: 'Home',
      href: '/',
      children: [{ id: 2, label: 'Docs', href: '/docs', children: [] }],
    },
  ];

  return (
    <div className="max-w-md h-[120px]">
      <Breadcrumbs
        data={menuData}
        keyField="id"
        childrenField="children"
        labelField="label"
        hrefField="href"
        selectedId={2}
      />
    </div>
  );
}

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';export default function Preview() {  const menuData = [    {      id: 1,      label: 'Home',      href: '/',      children: [{ id: 2, label: 'Docs', href: '/docs', children: [] }],    },  ];  return (    <div className="max-w-md h-[120px]">      <Breadcrumbs        data={menuData}        keyField="id"        childrenField="children"        labelField="label"        hrefField="href"        selectedId={2}      />    </div>  );}

Compound 패턴

headless 컴포넌트를 직접 조합하여 커스텀 Breadcrumbs를 구성할 수 있습니다.

import {
  BreadcrumbsRoot,
  BreadcrumbsList,
  BreadcrumbsItem,
  BreadcrumbsTrigger,
  BreadcrumbsContent,
  BreadcrumbsLink,
  BreadcrumbDropdownItem,
  BreadcrumbsSeparator,
} from '@aift/ui/Breadcrumbs';

<BreadcrumbsRoot>
  <BreadcrumbsList>
    <BreadcrumbsItem>
      <BreadcrumbsLink isHome href="/" />
    </BreadcrumbsItem>
    <BreadcrumbsSeparator />
    <BreadcrumbsItem>
      <BreadcrumbsTrigger isCurrent={false}>문서</BreadcrumbsTrigger>
      <BreadcrumbsContent>
        <BreadcrumbDropdownItem href="/docs">문서</BreadcrumbDropdownItem>
        <BreadcrumbDropdownItem href="/guides">가이드</BreadcrumbDropdownItem>
      </BreadcrumbsContent>
    </BreadcrumbsItem>
    <BreadcrumbsSeparator />
    <BreadcrumbsItem>
      <BreadcrumbsTrigger isCurrent>컴포넌트</BreadcrumbsTrigger>
      <BreadcrumbsContent>
        <BreadcrumbDropdownItem href="/docs/components/select">
          Select
        </BreadcrumbDropdownItem>
        <BreadcrumbDropdownItem href="/docs/components/breadcrumbs" isSelected>
          Breadcrumbs
        </BreadcrumbDropdownItem>
      </BreadcrumbsContent>
    </BreadcrumbsItem>
  </BreadcrumbsList>
</BreadcrumbsRoot>;

import {
  BreadcrumbsRoot,
  BreadcrumbsList,
  BreadcrumbsItem,
  BreadcrumbsTrigger,
  BreadcrumbsContent,
  BreadcrumbsLink,
  BreadcrumbDropdownItem,
  BreadcrumbsSeparator,
} from '@aift/ui/Breadcrumbs';

export default function Compound() {
  return (
    <div className="max-w-md h-[150px]">
      <BreadcrumbsRoot>
        <BreadcrumbsList>
          <BreadcrumbsItem>
            <BreadcrumbsLink isHome href="/" />
          </BreadcrumbsItem>
          <BreadcrumbsSeparator />
          <BreadcrumbsItem>
            <BreadcrumbsTrigger isCurrent={false}>문서</BreadcrumbsTrigger>
            <BreadcrumbsContent>
              <BreadcrumbDropdownItem href="/docs">문서</BreadcrumbDropdownItem>
              <BreadcrumbDropdownItem href="/guides">
                가이드
              </BreadcrumbDropdownItem>
            </BreadcrumbsContent>
          </BreadcrumbsItem>
          <BreadcrumbsSeparator />
          <BreadcrumbsItem>
            <BreadcrumbsTrigger isCurrent>컴포넌트</BreadcrumbsTrigger>
            <BreadcrumbsContent>
              <BreadcrumbDropdownItem href="/docs/components/select">
                Select
              </BreadcrumbDropdownItem>
              <BreadcrumbDropdownItem
                href="/docs/components/breadcrumbs"
                isSelected
              >
                Breadcrumbs
              </BreadcrumbDropdownItem>
            </BreadcrumbsContent>
          </BreadcrumbsItem>
        </BreadcrumbsList>
      </BreadcrumbsRoot>
    </div>
  );
}

import {  BreadcrumbsRoot,  BreadcrumbsList,  BreadcrumbsItem,  BreadcrumbsTrigger,  BreadcrumbsContent,  BreadcrumbsLink,  BreadcrumbDropdownItem,  BreadcrumbsSeparator,} from '@aift/ui/Breadcrumbs';export default function Compound() {  return (    <div className="max-w-md h-[150px]">      <BreadcrumbsRoot>        <BreadcrumbsList>          <BreadcrumbsItem>            <BreadcrumbsLink isHome href="/" />          </BreadcrumbsItem>          <BreadcrumbsSeparator />          <BreadcrumbsItem>            <BreadcrumbsTrigger isCurrent={false}>문서</BreadcrumbsTrigger>            <BreadcrumbsContent>              <BreadcrumbDropdownItem href="/docs">문서</BreadcrumbDropdownItem>              <BreadcrumbDropdownItem href="/guides">                가이드              </BreadcrumbDropdownItem>            </BreadcrumbsContent>          </BreadcrumbsItem>          <BreadcrumbsSeparator />          <BreadcrumbsItem>            <BreadcrumbsTrigger isCurrent>컴포넌트</BreadcrumbsTrigger>            <BreadcrumbsContent>              <BreadcrumbDropdownItem href="/docs/components/select">                Select              </BreadcrumbDropdownItem>              <BreadcrumbDropdownItem                href="/docs/components/breadcrumbs"                isSelected              >                Breadcrumbs              </BreadcrumbDropdownItem>            </BreadcrumbsContent>          </BreadcrumbsItem>        </BreadcrumbsList>      </BreadcrumbsRoot>    </div>  );}

커스텀 아이콘

customIcons와 programIdField를 사용하여 메뉴 항목별 아이콘을 지정할 수 있습니다.

import React from 'react';
import { Breadcrumbs, type SimpleBreadcrumbsProps } from '@aift/ui/Breadcrumbs';
import FileOutline20 from '@aift/ui/Icons/FileOutline20';
import FileDocumentSurface20 from '@aift/ui/Icons/FileDocumentSurface20';

export default function CustomIcons() {
  const menuData = [
    {
      programId: 1,
      menuName: '프로젝트',
      programUrl: '/projects',
      children: [
        {
          programId: 2,
          menuName: '문서',
          programUrl: '/projects/docs',
          children: [
            {
              programId: 3,
              menuName: 'API 레퍼런스',
              programUrl: '/projects/docs/api',
              children: [],
            },
          ],
        },
      ],
    },
  ];

  const customIcons: NonNullable<
    SimpleBreadcrumbsProps<Record<string, unknown>, number>['customIcons']
  > = {
    1: FileDocumentSurface20,
    2: FileOutline20,
    3: FileOutline20,
  };

  return (
    <div className="max-w-md h-[120px]">
      <Breadcrumbs
        data={menuData}
        keyField="programId"
        childrenField="children"
        labelField="menuName"
        hrefField="programUrl"
        programIdField="programId"
        selectedId={3}
        customIcons={customIcons}
      />
    </div>
  );
}

import React from 'react';import { Breadcrumbs, type SimpleBreadcrumbsProps } from '@aift/ui/Breadcrumbs';import FileOutline20 from '@aift/ui/Icons/FileOutline20';import FileDocumentSurface20 from '@aift/ui/Icons/FileDocumentSurface20';export default function CustomIcons() {  const menuData = [    {      programId: 1,      menuName: '프로젝트',      programUrl: '/projects',      children: [        {          programId: 2,          menuName: '문서',          programUrl: '/projects/docs',          children: [            {              programId: 3,              menuName: 'API 레퍼런스',              programUrl: '/projects/docs/api',              children: [],            },          ],        },      ],    },  ];  const customIcons: NonNullable<    SimpleBreadcrumbsProps<Record<string, unknown>, number>['customIcons']  > = {    1: FileDocumentSurface20,    2: FileOutline20,    3: FileOutline20,  };  return (    <div className="max-w-md h-[120px]">      <Breadcrumbs        data={menuData}        keyField="programId"        childrenField="children"        labelField="menuName"        hrefField="programUrl"        programIdField="programId"        selectedId={3}        customIcons={customIcons}      />    </div>  );}

심층 경로

다단계 트리 구조의 메뉴 데이터도 지원합니다.

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';

export default function DeepPath() {
  const menuData = [
    {
      id: 1,
      label: '대시보드',
      href: '/dashboard',
      children: [
        {
          id: 2,
          label: '설정',
          href: '/dashboard/settings',
          children: [
            {
              id: 3,
              label: '알림',
              href: '/dashboard/settings/notifications',
              children: [
                {
                  id: 4,
                  label: '이메일 알림',
                  href: '/dashboard/settings/notifications/email',
                  children: [],
                },
              ],
            },
          ],
        },
      ],
    },
  ];

  return (
    <div className="max-w-2xl h-[150px]">
      <Breadcrumbs
        data={menuData}
        keyField="id"
        childrenField="children"
        labelField="label"
        hrefField="href"
        selectedId={4}
      />
    </div>
  );
}

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';export default function DeepPath() {  const menuData = [    {      id: 1,      label: '대시보드',      href: '/dashboard',      children: [        {          id: 2,          label: '설정',          href: '/dashboard/settings',          children: [            {              id: 3,              label: '알림',              href: '/dashboard/settings/notifications',              children: [                {                  id: 4,                  label: '이메일 알림',                  href: '/dashboard/settings/notifications/email',                  children: [],                },              ],            },          ],        },      ],    },  ];  return (    <div className="max-w-2xl h-[150px]">      <Breadcrumbs        data={menuData}        keyField="id"        childrenField="children"        labelField="label"        hrefField="href"        selectedId={4}      />    </div>  );}

onItemClick

드롭다운 메뉴 아이템 클릭 시 onItemClick 콜백을 사용할 수 있습니다.

'use client';

import { Breadcrumbs } from '@aift/ui/Breadcrumbs';
import { useState } from 'react';

export default function OnItemClick() {
  const [lastClicked, setLastClicked] = useState<string | null>(null);

  const menuData = [
    {
      id: 1,
      label: '홈',
      href: '/',
      children: [
        {
          id: 2,
          label: '제품',
          href: '/products',
          children: [
            { id: 3, label: '카테고리 A', href: '/products/a', children: [] },
            { id: 4, label: '카테고리 B', href: '/products/b', children: [] },
          ],
        },
      ],
    },
  ];

  return (
    <div className="max-w-md space-y-4 h-[150px]">
      <Breadcrumbs
        data={menuData}
        keyField="id"
        childrenField="children"
        labelField="label"
        hrefField="href"
        selectedId={4}
        onItemClick={(item) => setLastClicked(`${item.label} (id: ${item.id})`)}
      />
      {lastClicked && (
        <p className="text-sm text-alias-label-neutral">
          마지막 클릭: <strong>{lastClicked}</strong>
        </p>
      )}
    </div>
  );
}

'use client';import { Breadcrumbs } from '@aift/ui/Breadcrumbs';import { useState } from 'react';export default function OnItemClick() {  const [lastClicked, setLastClicked] = useState<string | null>(null);  const menuData = [    {      id: 1,      label: '홈',      href: '/',      children: [        {          id: 2,          label: '제품',          href: '/products',          children: [            { id: 3, label: '카테고리 A', href: '/products/a', children: [] },            { id: 4, label: '카테고리 B', href: '/products/b', children: [] },          ],        },      ],    },  ];  return (    <div className="max-w-md space-y-4 h-[150px]">      <Breadcrumbs        data={menuData}        keyField="id"        childrenField="children"        labelField="label"        hrefField="href"        selectedId={4}        onItemClick={(item) => setLastClicked(`${item.label} (id: ${item.id})`)}      />      {lastClicked && (        <p className="text-sm text-alias-label-neutral">          마지막 클릭: <strong>{lastClicked}</strong>        </p>      )}    </div>  );}

Props

Breadcrumbs 컴포넌트는 Radix UI의 Navigation Menu를 기반으로 하며, 두 가지 사용 방식을 지원합니다.

Compound 패턴 하위 컴포넌트

headless 컴포넌트를 직접 조합할 때 사용하는 하위 컴포넌트입니다.

import {
  BreadcrumbsRoot,
  BreadcrumbsList,
  BreadcrumbsItem,
  BreadcrumbsTrigger,
  BreadcrumbsContent,
  BreadcrumbsLink,
  BreadcrumbDropdownItem,
  BreadcrumbsSeparator,
} from '@aift/ui/Breadcrumbs';

export default function Compound() {
  return (
    <div className="max-w-md h-[150px]">
      <BreadcrumbsRoot>
        <BreadcrumbsList>
          <BreadcrumbsItem>
            <BreadcrumbsLink isHome href="/" />
          </BreadcrumbsItem>
          <BreadcrumbsSeparator />
          <BreadcrumbsItem>
            <BreadcrumbsTrigger isCurrent={false}>문서</BreadcrumbsTrigger>
            <BreadcrumbsContent>
              <BreadcrumbDropdownItem href="/docs">문서</BreadcrumbDropdownItem>
              <BreadcrumbDropdownItem href="/guides">
                가이드
              </BreadcrumbDropdownItem>
            </BreadcrumbsContent>
          </BreadcrumbsItem>
          <BreadcrumbsSeparator />
          <BreadcrumbsItem>
            <BreadcrumbsTrigger isCurrent>컴포넌트</BreadcrumbsTrigger>
            <BreadcrumbsContent>
              <BreadcrumbDropdownItem href="/docs/components/select">
                Select
              </BreadcrumbDropdownItem>
              <BreadcrumbDropdownItem
                href="/docs/components/breadcrumbs"
                isSelected
              >
                Breadcrumbs
              </BreadcrumbDropdownItem>
            </BreadcrumbsContent>
          </BreadcrumbsItem>
        </BreadcrumbsList>
      </BreadcrumbsRoot>
    </div>
  );
}

import {  BreadcrumbsRoot,  BreadcrumbsList,  BreadcrumbsItem,  BreadcrumbsTrigger,  BreadcrumbsContent,  BreadcrumbsLink,  BreadcrumbDropdownItem,  BreadcrumbsSeparator,} from '@aift/ui/Breadcrumbs';export default function Compound() {  return (    <div className="max-w-md h-[150px]">      <BreadcrumbsRoot>        <BreadcrumbsList>          <BreadcrumbsItem>            <BreadcrumbsLink isHome href="/" />          </BreadcrumbsItem>          <BreadcrumbsSeparator />          <BreadcrumbsItem>            <BreadcrumbsTrigger isCurrent={false}>문서</BreadcrumbsTrigger>            <BreadcrumbsContent>              <BreadcrumbDropdownItem href="/docs">문서</BreadcrumbDropdownItem>              <BreadcrumbDropdownItem href="/guides">                가이드              </BreadcrumbDropdownItem>            </BreadcrumbsContent>          </BreadcrumbsItem>          <BreadcrumbsSeparator />          <BreadcrumbsItem>            <BreadcrumbsTrigger isCurrent>컴포넌트</BreadcrumbsTrigger>            <BreadcrumbsContent>              <BreadcrumbDropdownItem href="/docs/components/select">                Select              </BreadcrumbDropdownItem>              <BreadcrumbDropdownItem                href="/docs/components/breadcrumbs"                isSelected              >                Breadcrumbs              </BreadcrumbDropdownItem>            </BreadcrumbsContent>          </BreadcrumbsItem>        </BreadcrumbsList>      </BreadcrumbsRoot>    </div>  );}

Breadcrumbs.Root: 루트 컴포넌트
Breadcrumbs.List: 경로 목록 컨테이너
Breadcrumbs.Item: 개별 경로 항목
Breadcrumbs.Trigger: 드롭다운 트리거
Breadcrumbs.Content: 드롭다운 콘텐츠
Breadcrumbs.Link: 링크 (홈 등)
Breadcrumbs.DropdownItem: 드롭다운 메뉴 아이템
Breadcrumbs.Separator: 경로 구분자

Simple Breadcrumbs (data 기반)

data prop과 selectedId를 사용하는 간편 API의 Props입니다.

Prop	Type	Default	Description
data	`T[]`	`undefined`	트리 구조 메뉴 데이터
selectedId	`Key`	`undefined`	선택된 아이템 ID
keyField	`keyof T`	(필수)	ID 필드명
childrenField	`keyof T`	(필수)	자식 배열 필드명
labelField	`keyof T`	(필수)	라벨 표시 필드명
hrefField	`keyof T`	(필수)	링크 URL 필드명
programIdField	`keyof T`	`undefined`	programId 필드 (아이콘 매핑용)
onItemClick	`(item: T) => void`	`undefined`	아이템 클릭 핸들러
customIcons	`Record<number, ReactComponent>`	`undefined`	programId별 아이콘 매핑
className	`string`	`undefined`	루트에 적용할 추가 클래스

Breadcrumbs

On this page