Breadcrumbs

Breadcrumbs display the user's current location within a navigational hierarchy, allowing them to trace their path back to the starting point.

Installation

$ cbui-cli install breadcrumbs

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Breadcrumbs, BreadcrumbItem, useBreadcrumbsContext, BreadcrumbsContext } from '@/crossbuildui/breadcrumbs';
import Icon from 'react-native-vector-icons/MaterialIcons'; // If using custom icons

The Breadcrumbs component uses react-native-vector-icons for its default separator. Ensure this library is installed and linked in your Expo project.

Basic Usage

Create a breadcrumb trail by nesting BreadcrumbItem components within a Breadcrumbs container. Use the isCurrent prop to indicate the active page.

index.tsx

<Breadcrumbs>
  <BreadcrumbItem href="/home">Home</BreadcrumbItem>
  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
  <BreadcrumbItem isCurrent>Laptops</BreadcrumbItem>
</Breadcrumbs>

With Icons

You can include icons or other custom content within breadcrumb items using the startContent or endContent props.

index.tsx

<Breadcrumbs>
  <BreadcrumbItem href="/home" startContent={<Icon name="home" size={16} />}>
    Home
  </BreadcrumbItem>
  <BreadcrumbItem href="/settings" startContent={<Icon name="settings" size={16} />}>
    Settings
  </BreadcrumbItem>
  <BreadcrumbItem isCurrent startContent={<Icon name="person" size={16} />}>
    Profile
  </BreadcrumbItem>
</Breadcrumbs>

Variants & Colors

Breadcrumbs support light (default), solid, bordered, and glass variants. The color prop influences item text color and container background/border for solid/bordered variants. For the glass variant, item text color often defaults to the theme's foreground.

index.tsx

// Light (default)
<Breadcrumbs>
  <BreadcrumbItem>Light</BreadcrumbItem>
  <BreadcrumbItem>Variant</BreadcrumbItem>
</Breadcrumbs>

// Solid
<Breadcrumbs variant="solid" color="primary" radius="md">
  <BreadcrumbItem>Solid</BreadcrumbItem>
  <BreadcrumbItem>Primary</BreadcrumbItem>
</Breadcrumbs>

// Bordered
<Breadcrumbs variant="bordered" color="secondary" radius="lg">
  <BreadcrumbItem>Bordered</BreadcrumbItem>
  <BreadcrumbItem>Secondary</BreadcrumbItem>
</Breadcrumbs>

// Glass
<Breadcrumbs variant="glass" glassIntensity={70} glassTint="light" radius="md">
  <BreadcrumbItem href="/store">Store</BreadcrumbItem>
  <BreadcrumbItem isCurrent>Accessories</BreadcrumbItem>
</Breadcrumbs>

Sizes

Adjust the size of breadcrumb items using the size prop. Available sizes are sm, md (default), and lg.

index.tsx

<Breadcrumbs size="sm">
  <BreadcrumbItem>Small</BreadcrumbItem>
  <BreadcrumbItem>Size</BreadcrumbItem>
</Breadcrumbs>

<Breadcrumbs size="md">
  <BreadcrumbItem>Medium</BreadcrumbItem>
  <BreadcrumbItem>Size</BreadcrumbItem>
</Breadcrumbs>

<Breadcrumbs size="lg">
  <BreadcrumbItem>Large</BreadcrumbItem>
  <BreadcrumbItem>Size</BreadcrumbItem>
</Breadcrumbs>

Glass Variant

The glass variant applies a frosted glass effect to the breadcrumbs container using expo-blur. Customize it with glassIntensity (0-100) and glassTint ('light', 'dark', 'default'). Item text and separator colors adapt for better contrast on the blurred background. You might need to adjust item colors manually for dark glass tints.

index.tsx

<Breadcrumbs variant="glass" glassIntensity={80} glassTint="light" radius="lg" style={{padding: 8}}>
  <BreadcrumbItem href="/home" startContent={<Icon name="home" size={16} />}>
    Home
  </BreadcrumbItem>
  <BreadcrumbItem isCurrent>Dashboard</BreadcrumbItem>
</Breadcrumbs>

<Breadcrumbs variant="glass" glassIntensity={40} glassTint="dark" radius="md" style={{padding: 8, marginTop: 16}}>
  <BreadcrumbItem href="/settings" itemStyles={{content: {color: 'white'}, startContent: {color: 'white'}}} startContent={<Icon name="settings" size={16} />}>
    Settings
  </BreadcrumbItem>
  <BreadcrumbItem isCurrent itemStyles={{content: {color: 'lightgray'}}}>Appearance</BreadcrumbItem>
</Breadcrumbs>

Collapsing Items

When there are many breadcrumb items, you can use maxItems to collapse intermediate items into an ellipsis (...). Control the number of visible items before and after the ellipsis with itemsBeforeCollapse and itemsAfterCollapse.

index.tsx

<Breadcrumbs maxItems={3} itemsBeforeCollapse={1} itemsAfterCollapse={1}>
  <BreadcrumbItem href="/section1">Section 1</BreadcrumbItem>
  <BreadcrumbItem href="/section2">Section 2</BreadcrumbItem>
  <BreadcrumbItem href="/section3">Section 3</BreadcrumbItem>
  <BreadcrumbItem href="/section4">Section 4</BreadcrumbItem>
  <BreadcrumbItem href="/section5" isCurrent>Section 5</BreadcrumbItem>
</Breadcrumbs>

Custom Separators

Provide a custom separator globally via the separator prop on Breadcrumbs, or for individual items using the separator prop on BreadcrumbItem.

index.tsx

<Breadcrumbs separator={<Icon name="arrow-forward-ios" size={12} color="gray" />}>
  <BreadcrumbItem href="/path1">Path One</BreadcrumbItem>
  <BreadcrumbItem href="/path2">Path Two</BreadcrumbItem>
  <BreadcrumbItem isCurrent>Current Page</BreadcrumbItem>
</Breadcrumbs>

// Item-specific separator
<Breadcrumbs>
  <BreadcrumbItem href="/docs">Docs</BreadcrumbItem>
  <BreadcrumbItem href="/components" separator={<Text style={{marginHorizontal: 4}}>→</Text>}>
    Components
  </BreadcrumbItem>
  <BreadcrumbItem isCurrent>Breadcrumbs</BreadcrumbItem>
</Breadcrumbs>

Props Overview

Breadcrumbs Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactElement<BreadcrumbItemProps>[]`	-	The breadcrumb items.
`variant`	`'solid' \| 'bordered' \| 'light' \| 'glass'`	`'light'`	Visual style.
`color`	`Theme color key`	`'foreground'`	Color theme.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of items.
`radius`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'full'`	`'md'`	Container border radius for solid/bordered variants.
`underline`	`'none' \| 'hover' \| 'active' \| 'always'`	`'hover'`	Underline style.
`separator`	`ReactNode`	Chevron Icon	Custom global separator.
`maxItems`	`number`	-	Max items before collapsing.
`itemsBeforeCollapse`	`number`	1	Items before ellipsis.
`itemsAfterCollapse`	`number`	1	Items after ellipsis.
`hideSeparator`	`boolean`	`false`	Hide all separators.
`isDisabled`	`boolean`	`false`	Disable all items (except current).
`itemStyle`	`BreadcrumbItemSlotsStyles`	-	Global styles for item slots.
`styles`	`BreadcrumbsSlotsStyles`	-	Styles for container slots (base, list, ellipsis).
`style`	`StyleProp<ViewStyle>`	-	Style for the outer container.
`glassTint`	`'default' \| 'light' \| 'dark'`	Theme-derived	Tint for the 'glass' variant blur effect.
`glassIntensity`	`number`	50	Intensity (0-100) for the 'glass' variant blur effect.

BreadcrumbItem Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Content of the item.
`color`, `size`, `underline`	various	Inherited	Overrides parent settings.
`startContent`, `endContent`	`ReactNode`	-	Content at start/end.
`separator`	`ReactNode`	Inherited	Item-specific separator.
`isCurrent`	`boolean`	`false`	Marks item as current page.
`isLast`	`boolean`	Injected	(Injected by Breadcrumbs) Marks item as last.
`hideSeparator`	`boolean`	`false`	Hides separator after this item.
`disabled`	`boolean`	`false`	Disables the item.
`itemStyles`	`BreadcrumbItemSlotsStyles`	-	Styles for this item's slots.
`style`	`StyleProp<ViewStyle>`	-	Style for the Pressable wrapper.
`onPress`	`(event) => void`	-	Handler for press events.
`...PressableProps`	various	-	Other props from React Native's Pressable.

Styling

Customize the appearance using:

style prop on Breadcrumbs for the outer container.
styles prop on Breadcrumbs for internal slots like base, list, and ellipsis.
itemStyle prop on Breadcrumbs for global styling of all item slots.
itemStyles prop on BreadcrumbItem for specific item slot styling.
style prop on BreadcrumbItem for the Pressable wrapper.
For the glass variant, the background is rendered by BlurView from expo-blur, controlled by glassIntensity and glassTint. The styles.base.backgroundColor will be overridden for this variant.

index.tsx

<Breadcrumbs
  style={{ marginVertical: 10 }} // Style for the outer container
  styles={{
    base: { padding: 8, backgroundColor: '#f0f0f0' }, // Style for the main list container
    list: { justifyContent: 'center' },
    ellipsis: { fontWeight: 'bold' }
  }}
  itemStyle={{ // Global styles for all items
    base: { marginHorizontal: 2 },
    content: { fontFamily: 'Arial' }
  }}
>
  <BreadcrumbItem
    itemStyles={{ // Specific styles for this item
      base: { backgroundColor: 'lightblue' },
      content: { color: 'darkblue', fontWeight: 'bold' },
      startContent: { marginRight: 8 }
    }}
    startContent={<Icon name="star" size={16} />}
  >
    Styled Item
  </BreadcrumbItem>
  <BreadcrumbItem>Another Item</BreadcrumbItem>
</Breadcrumbs>

Using Breadcrumbs Context

For advanced customization or to build components that react to the Breadcrumbs state, you can use the useBreadcrumbsContext hook. This hook provides access to properties like variant, color, size, maxItems, items (the children passed to Breadcrumbs), and more.

Any component that calls useBreadcrumbsContext must be a descendant of a Breadcrumbs component.

MyCustomBreadcrumbComponent.tsx

import { Breadcrumbs, BreadcrumbItem, useBreadcrumbsContext } from '@/crossbuildui/breadcrumbs';
import { Text, View } from 'react-native';

const CustomBreadcrumbContent = () => {
  const context = useBreadcrumbsContext();

  if (!context) {
    return <Text>This component must be used within Breadcrumbs.</Text>;
  }

  const { variant, color, size, maxItems, items } = context;

  return (
    <View style={{ marginTop: 8, padding: 8, backgroundColor: '#f0f0f0', borderRadius: 4 }}>
      <Text>Breadcrumbs Info:</Text>
      <Text>- Variant: {variant}</Text>
      <Text>- Color: {color}</Text>
      <Text>- Size: {size}</Text>
      <Text>- Max Items: {maxItems ?? 'Not set'}</Text>
      <Text>- Total Items (passed as children): {items.length}</Text>
    </View>
  );
};

// Later in your component:
// <Breadcrumbs size="sm" color="primary"><BreadcrumbItem href="/home">Home</BreadcrumbItem><CustomBreadcrumbContent /></Breadcrumbs>

Accessibility

The Breadcrumbs component has accessibilityRole="menubar". Each interactive BreadcrumbItem has accessibilityRole="link" and appropriate accessibilityState (disabled, selected).

Footer Navbar Pagination