# NavigationItem

## Introduction

NavigationItem is a single navigation element used within sidebar navigation systems. Built on Joy UI's ListItem and ListItemButton, it provides a clickable navigation item with support for icons, selection states, and nesting levels. NavigationItem is typically used within Navigator or as a standalone navigation element in custom sidebar implementations.

```text
// Unable to derive source for Default
```

| Field                        | Description | Default |
| ---------------------------- | ----------- | ------- |
| Controls resolved at runtime | —           | —       |

## Usage

```tsx
import { NavigationItem } from '@ceed/cds';

function Sidebar() {
  return (
    <NavigationItem
      id="dashboard"
      startDecorator={<DashboardIcon />}
      selected={true}
      onClick={(id) => console.log('Selected:', id)}
    >
      Dashboard
    </NavigationItem>
  );
}
```

## Examples

### Default

Basic navigation item with text content.

```text
// Unable to derive source for Default
```

### Selected State

Shows the visual indicator for the currently active navigation item.

```text
// Unable to derive source for Selected
```

### With Start Decorator

Add an icon before the navigation item text.

```text
// Unable to derive source for WithStartDecorator
```

### Nesting Levels

NavigationItem supports different indentation levels for hierarchical navigation.

```text
// Unable to derive source for Level1
```

```text
// Unable to derive source for Level2
```

### Levels with Icons

Icons work at any nesting level.

```text
// Unable to derive source for Level1WithStartDecorator
```

```text
// Unable to derive source for Level2WithStartDecorator
```

## When to Use

### ✅ Good Use Cases

- **Sidebar navigation**: Individual menu items in a sidebar
- **Nested menus**: Items within expandable navigation groups
- **Settings navigation**: Links to different settings sections
- **Dashboard menus**: Quick access to different dashboard views
- **Custom navigation**: Building custom navigation components

### ❌ When Not to Use

- **Horizontal navigation**: Use Tabs or horizontal menu patterns instead
- **Action buttons**: Use Button for triggering actions, not navigation
- **Breadcrumbs**: Use Breadcrumbs component for path navigation
- **Dropdown menus**: Use Dropdown with Menu for popup menus

## Common Use Cases

### Sidebar with Selection State

```tsx
function Sidebar({ currentPath }) {
  const handleClick = (id) => {
    navigate(`/${id}`);
  };

  return (
    <List>
      <NavigationItem
        id="dashboard"
        startDecorator={<DashboardIcon />}
        selected={currentPath === '/dashboard'}
        onClick={handleClick}
      >
        Dashboard
      </NavigationItem>
      <NavigationItem
        id="users"
        startDecorator={<PeopleIcon />}
        selected={currentPath === '/users'}
        onClick={handleClick}
      >
        Users
      </NavigationItem>
      <NavigationItem
        id="settings"
        startDecorator={<SettingsIcon />}
        selected={currentPath === '/settings'}
        onClick={handleClick}
      >
        Settings
      </NavigationItem>
    </List>
  );
}
```

### Nested Navigation Items

```tsx
function NestedNavigation() {
  return (
    <>
      <NavigationItem id="reports" startDecorator={<ReportIcon />}>
        Reports
      </NavigationItem>
      {/* Nested items at level 1 */}
      <NavigationItem id="daily" level={1}>
        Daily Reports
      </NavigationItem>
      <NavigationItem id="weekly" level={1}>
        Weekly Reports
      </NavigationItem>
      <NavigationItem id="monthly" level={1}>
        Monthly Reports
      </NavigationItem>
    </>
  );
}
```

### Dynamic Navigation from Data

```tsx
function DynamicNavigation({ menuItems, selectedId, onSelect }) {
  return (
    <List>
      {menuItems.map((item) => (
        <NavigationItem
          key={item.id}
          id={item.id}
          startDecorator={item.icon}
          selected={selectedId === item.id}
          level={item.level}
          onClick={onSelect}
        >
          {item.label}
        </NavigationItem>
      ))}
    </List>
  );
}
```

## Props and Customization

### Key Props

| Prop             | Type                   | Default | Description                            |
| ---------------- | ---------------------- | ------- | -------------------------------------- |
| `id`             | `string`               | -       | Unique identifier for the item         |
| `children`       | `ReactNode`            | -       | Navigation item content/label          |
| `startDecorator` | `ReactNode`            | -       | Icon or element before the label       |
| `level`          | `number`               | `0`     | Nesting level for indentation          |
| `selected`       | `boolean`              | `false` | Whether the item is currently selected |
| `onClick`        | `(id: string) => void` | -       | Click handler receiving the item id    |

### Indentation by Level

NavigationItem automatically applies indentation based on the `level` prop:

```tsx
// Root level (no indentation)
<NavigationItem id="home" level={0}>Home</NavigationItem>

// First level (slight indentation)
<NavigationItem id="sub1" level={1}>Sub Item 1</NavigationItem>

// Second level (more indentation)
<NavigationItem id="sub2" level={2}>Sub Item 2</NavigationItem>
```

### Custom Styling

```tsx
<NavigationItem
  id="custom"
  sx={{
    '& .NavigationItem-Button': {
      borderRadius: 'md',
    },
  }}
>
  Custom Styled Item
</NavigationItem>
```

## Accessibility

NavigationItem includes built-in accessibility features:

### ARIA Attributes

- Uses `aria-current` to indicate the selected item
- Built on semantic list item structure
- Proper button role for clickable behavior

### Keyboard Navigation

- **Tab**: Focus the navigation item
- **Enter/Space**: Activate the item (trigger onClick)

### Screen Reader Support

```tsx
// Selected state is announced
<NavigationItem selected={true}>
  Dashboard {/* Announced as "Dashboard, current page" */}
</NavigationItem>
```

## Best Practices

### ✅ Do

1. **Provide unique IDs**: Each item needs a unique identifier for selection tracking

```tsx
// ✅ Good: Unique IDs
<NavigationItem id="users">Users</NavigationItem>
<NavigationItem id="settings">Settings</NavigationItem>
```

2. **Use consistent icons**: Either all items have icons or none

```tsx
// ✅ Good: All items have icons
<NavigationItem id="home" startDecorator={<HomeIcon />}>Home</NavigationItem>
<NavigationItem id="users" startDecorator={<PeopleIcon />}>Users</NavigationItem>
```

3. **Keep labels concise**: Short, descriptive labels work best

4. **Manage selection at parent level**: Track selected state in the parent component

### ❌ Don't

1. **Don't nest NavigationItem inside NavigationItem**: Use the `level` prop instead

```tsx
// ❌ Bad: Nested components
<NavigationItem>
  Parent
  <NavigationItem>Child</NavigationItem>
</NavigationItem>

// ✅ Good: Use level prop
<NavigationItem id="parent">Parent</NavigationItem>
<NavigationItem id="child" level={1}>Child</NavigationItem>
```

2. **Don't use for non-navigation purposes**: Use Button for actions

3. **Don't skip levels**: Go from level 0 to 1 to 2, not 0 to 2

## Performance Considerations

### Memoize Click Handlers

When rendering many items, memoize the click handler:

```tsx
const handleClick = useCallback((id) => {
  setSelectedId(id);
}, []);

// Pass stable handler to all items
<NavigationItem id="item1" onClick={handleClick}>Item 1</NavigationItem>
```

### Avoid Inline Objects

Don't create new decorator elements on each render:

```tsx
// ❌ Bad: New element created each render
<NavigationItem startDecorator={<HomeIcon />}>Home</NavigationItem>

// ✅ Good: Memoized or static
const homeIcon = <HomeIcon />;
<NavigationItem startDecorator={homeIcon}>Home</NavigationItem>
```

NavigationItem provides a foundational building block for sidebar navigation. Use it within Navigator for automatic item management, or combine it with NavigationGroup for custom hierarchical navigation structures.
