mirror of
https://github.com/shadcn-ui/ui.git
synced 2026-06-27 14:44:12 +00:00
363 lines
7.3 KiB
Plaintext
363 lines
7.3 KiB
Plaintext
---
|
|
title: Item
|
|
description: A versatile component that you can use to display any content.
|
|
base: base
|
|
component: true
|
|
---
|
|
|
|
The `Item` component is a straightforward flex container that can house nearly any type of content. Use it to display a title, description, and actions. Group it with the `ItemGroup` component to create a list of items.
|
|
|
|
You can pretty much achieve the same result with the `div` element and some classes, but **I've built this so many times** that I decided to create a component for it. Now I use it all the time.
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-demo"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
## Installation
|
|
|
|
<CodeTabs>
|
|
|
|
<TabsList>
|
|
<TabsTrigger value="cli">Command</TabsTrigger>
|
|
<TabsTrigger value="manual">Manual</TabsTrigger>
|
|
</TabsList>
|
|
<TabsContent value="cli">
|
|
|
|
```bash
|
|
npx shadcn@latest add item
|
|
```
|
|
|
|
</TabsContent>
|
|
|
|
<TabsContent value="manual">
|
|
|
|
<Steps className="mb-0 pt-2">
|
|
|
|
<Step>Copy and paste the following code into your project.</Step>
|
|
|
|
<ComponentSource
|
|
name="item"
|
|
title="components/ui/item.tsx"
|
|
styleName="base-nova"
|
|
/>
|
|
|
|
<Step>Update the import paths to match your project setup.</Step>
|
|
|
|
</Steps>
|
|
|
|
</TabsContent>
|
|
|
|
</CodeTabs>
|
|
|
|
## Usage
|
|
|
|
```tsx showLineNumbers
|
|
import {
|
|
Item,
|
|
ItemActions,
|
|
ItemContent,
|
|
ItemDescription,
|
|
ItemFooter,
|
|
ItemHeader,
|
|
ItemMedia,
|
|
ItemTitle,
|
|
} from "@/components/ui/item"
|
|
```
|
|
|
|
```tsx showLineNumbers
|
|
<Item>
|
|
<ItemHeader>Item Header</ItemHeader>
|
|
<ItemMedia />
|
|
<ItemContent>
|
|
<ItemTitle>Item</ItemTitle>
|
|
<ItemDescription>Item</ItemDescription>
|
|
</ItemContent>
|
|
<ItemActions />
|
|
<ItemFooter>Item Footer</ItemFooter>
|
|
</Item>
|
|
```
|
|
|
|
## Item vs Field
|
|
|
|
Use `Field` if you need to display a form input such as a checkbox, input, radio, or select.
|
|
|
|
If you only need to display content such as a title, description, and actions, use `Item`.
|
|
|
|
## Examples
|
|
|
|
### Variants
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-variant"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Size
|
|
|
|
The `Item` component has different sizes for different use cases. For example, you can use the `sm` size for a compact item or the `default` size for a standard item.
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-size"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Icon
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-icon"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Avatar
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-avatar"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Image
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-image"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Group
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-group"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Header
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-header"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
### Link
|
|
|
|
To render an item as a link, use the `asChild` prop. The hover and focus states will be applied to the anchor element.
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-link"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
```tsx showLineNumbers
|
|
<Item asChild>
|
|
<a href="/dashboard">
|
|
<ItemMedia />
|
|
<ItemContent>
|
|
<ItemTitle>Dashboard</ItemTitle>
|
|
<ItemDescription>Overview of your account and activity.</ItemDescription>
|
|
</ItemContent>
|
|
<ItemActions />
|
|
</a>
|
|
</Item>
|
|
```
|
|
|
|
### Dropdown
|
|
|
|
<ComponentPreview
|
|
styleName="base-nova"
|
|
name="item-dropdown"
|
|
className="[&_.preview]:p-4"
|
|
/>
|
|
|
|
## API Reference
|
|
|
|
### Item
|
|
|
|
The main component for displaying content with media, title, description, and actions.
|
|
|
|
| Prop | Type | Default |
|
|
| --------- | ----------------------------------- | ----------- |
|
|
| `variant` | `"default" \| "outline" \| "muted"` | `"default"` |
|
|
| `size` | `"default" \| "sm"` | `"default"` |
|
|
| `asChild` | `boolean` | `false` |
|
|
|
|
```tsx
|
|
<Item size="" variant="">
|
|
<ItemMedia />
|
|
<ItemContent>
|
|
<ItemTitle>Item</ItemTitle>
|
|
<ItemDescription>Item</ItemDescription>
|
|
</ItemContent>
|
|
<ItemActions />
|
|
</Item>
|
|
```
|
|
|
|
You can use the `asChild` prop to render a custom component as the item, for example a link. The hover and focus states will be applied to the custom component.
|
|
|
|
```tsx showLineNumbers
|
|
import {
|
|
Item,
|
|
ItemContent,
|
|
ItemDescription,
|
|
ItemMedia,
|
|
ItemTitle,
|
|
} from "@/components/ui/item"
|
|
|
|
export function ItemLink() {
|
|
return (
|
|
<Item asChild>
|
|
<a href="/dashboard">
|
|
<ItemMedia variant="icon">
|
|
<Home />
|
|
</ItemMedia>
|
|
<ItemContent>
|
|
<ItemTitle>Dashboard</ItemTitle>
|
|
<ItemDescription>
|
|
Overview of your account and activity.
|
|
</ItemDescription>
|
|
</ItemContent>
|
|
</a>
|
|
</Item>
|
|
)
|
|
}
|
|
```
|
|
|
|
### ItemGroup
|
|
|
|
The `ItemGroup` component is a container that groups related items together with consistent styling.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemGroup>
|
|
<Item />
|
|
<Item />
|
|
</ItemGroup>
|
|
```
|
|
|
|
### ItemSeparator
|
|
|
|
The `ItemSeparator` component is a separator that separates items in the item group.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemGroup>
|
|
<Item />
|
|
<ItemSeparator />
|
|
<Item />
|
|
</ItemGroup>
|
|
```
|
|
|
|
### ItemMedia
|
|
|
|
Use the `ItemMedia` component to display media content such as icons, images, or avatars.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------------------------------- | ----------- |
|
|
| `variant` | `"default" \| "icon" \| "image"` | `"default"` |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemMedia variant="icon">
|
|
<Icon />
|
|
</ItemMedia>
|
|
```
|
|
|
|
```tsx
|
|
<ItemMedia variant="image">
|
|
<img src="..." alt="..." />
|
|
</ItemMedia>
|
|
```
|
|
|
|
### ItemContent
|
|
|
|
The `ItemContent` component wraps the title and description of the item.
|
|
|
|
You can skip `ItemContent` if you only need a title.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemContent>
|
|
<ItemTitle>Item</ItemTitle>
|
|
<ItemDescription>Item</ItemDescription>
|
|
</ItemContent>
|
|
```
|
|
|
|
### ItemTitle
|
|
|
|
Use the `ItemTitle` component to display the title of the item.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemTitle>Item Title</ItemTitle>
|
|
```
|
|
|
|
### ItemDescription
|
|
|
|
Use the `ItemDescription` component to display the description of the item.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemDescription>Item description</ItemDescription>
|
|
```
|
|
|
|
### ItemActions
|
|
|
|
Use the `ItemActions` component to display action buttons or other interactive elements.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemActions>
|
|
<Button>Action</Button>
|
|
<Button>Action</Button>
|
|
</ItemActions>
|
|
```
|
|
|
|
### ItemHeader
|
|
|
|
Use the `ItemHeader` component to display a header in the item.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemHeader>Item Header</ItemHeader>
|
|
```
|
|
|
|
### ItemFooter
|
|
|
|
Use the `ItemFooter` component to display a footer in the item.
|
|
|
|
| Prop | Type | Default |
|
|
| ----------- | -------- | ------- |
|
|
| `className` | `string` | |
|
|
|
|
```tsx
|
|
<ItemFooter>Item Footer</ItemFooter>
|
|
```
|