---
url: https://docs.tailor.tech/app-shell/components/sidebar-item.md
description: >-
Individual navigation item for customizing sidebar with icons, active states,
and external links
---
# SidebarItem
`SidebarItem` represents an individual navigation link in the sidebar. It automatically resolves titles and icons from resource definitions and provides active state highlighting.
## Import
```tsx
import { SidebarItem } from "@tailor-platform/app-shell";
```
## Basic Usage
```tsx
import { DefaultSidebar, SidebarItem } from "@tailor-platform/app-shell";
;
```
When you only provide `to`, the title and icon are automatically resolved from the matching resource's `meta` property.
## Props
| Prop | Type | Default | Description |
| ------------- | ---------------------- | ------------- | ---------------------------------------------- |
| `to` | `string` | **Required** | Target URL (internal or external) |
| `title` | `string` | Auto-resolved | Override the display title |
| `icon` | `React.ReactNode` | Auto-resolved | Override the icon |
| `external` | `boolean` | `false` | Opens link in new tab with external icon |
| `activeMatch` | `"exact" \| "prefix"` | `"prefix"` | How to match the current path for active state |
| `render` | `(props) => ReactNode` | - | Custom render function for full control |
## Auto-Resolution
### Title Resolution
The title is automatically resolved from the resource's `meta.title`:
```tsx
// In your module definition
const dashboardModule = defineModule({
path: "dashboard",
component: DashboardPage,
meta: {
title: "Dashboard", // ← Automatically used
},
});
// In sidebar - no title needed!
;
// Renders as: Dashboard
```
For the root path (`/` or `""`), when no `meta.title` is set, the title falls back to the localized string `"Home"` (English) or `"ホーム"` (Japanese).
### Icon Resolution
Icons are resolved from the module's `meta.icon`:
```tsx
import { Home, Package } from "lucide-react";
const modules = [
defineModule({
path: "dashboard",
meta: {
title: "Dashboard",
icon: , // ← Automatically used in sidebar
},
}),
defineModule({
path: "products",
meta: {
title: "Products",
icon: ,
},
}),
];
{/* Shows Home icon */}
{/* Shows Package icon */}
;
```
## Manual Override
### Override Title
```tsx
```
### Override Icon
```tsx
import { Home } from "lucide-react";
} // Override auto-resolved icon
/>;
```
### Both Title and Icon
```tsx
import { Settings } from "lucide-react";
} />;
```
## External Links
Open links in a new tab with an external link icon:
```tsx
import { ExternalLink } from "lucide-react";
}
external
/>;
```
The external link icon is automatically added to the end of the item.
## Active State Matching
Control how the active state is determined:
### Prefix Matching (Default)
Highlights when the current path **starts with** the `to` path:
```tsx
// Active when:
// - /products
// - /products/123
// - /products/categories
```
### Exact Matching
Highlights only when the current path **exactly matches** the `to` path:
```tsx
// Active when:
// - /products (only)
// NOT active when:
// - /products/123
// - /products/categories
```
## Custom Rendering
For full control, use the `render` prop:
```tsx
(
{icon}
{title}
{isActive && New}
5
)}
/>
```
The render function receives:
```typescript
type SidebarItemRenderProps = {
title: string; // Auto-resolved or overridden
url: string; // The `to` prop value
icon?: ReactNode; // Auto-resolved or overridden
isActive: boolean; // Whether this item matches the current route
};
```
## Examples
### Basic Sidebar
```tsx
```
### With Manual Overrides
```tsx
import { Home, Package, ShoppingCart, Users } from "lucide-react";
} />
} />
} />
} />
;
```
### With External Links
```tsx
import { HelpCircle, FileText, ExternalLink } from "lucide-react";
} external />
} external />
;
```
### With Notification Badge
```tsx
(
<>
{icon}
{title}12
)}
/>
```
### With Active Indicator
```tsx
(
<>
{icon}
{title}
{isActive && •}
)}
/>
```
### Exact Match for Root
```tsx
```
Without `activeMatch="exact"`, the root item would be active on all pages since every path starts with `/`.
### Conditional Rendering with Guards
```tsx
import { WithGuard } from "@tailor-platform/app-shell";
const isAdmin = ({ context }) => (context.currentUser?.role === "admin" ? pass() : hidden());
;
```
### In SidebarGroup
```tsx
import { SidebarGroup, SidebarItem } from "@tailor-platform/app-shell";
import { Package } from "lucide-react";
}>
;
```
## Styling
### Active State
Active items automatically receive the `astw:bg-sidebar-accent` background class:
```css
/* Active item styling (automatic) */
.astw:bg-sidebar-accent {
background: var(--sidebar-accent);
font-weight: 500;
}
```
### Custom Styling
Add custom classes via the `render` prop:
```tsx
(