Item

updated

You've built this row a hundred times. Here's the last one. A row of media, title, description and actions, in five variants and five sizes.

Demo
Basic item

A title, a description and an action on one row.

Your profile has been verified.

Open Props in the corner of the example to try variant and size. The variants are Input's: ghost (default) is transparent, outline a border, soft a fill, subtle a fill and a border, filled a fill with a line underneath, and switching never moves the content. size goes from xs to xl and sets the row's density: padding, gap and media. Text keeps its size, so a compact row still reads at body size, and a text-body-sm of your own on a part is just a class. The media box follows --item-media on the root, and a size-* class on an ItemMedia wins over it.

Installation

Usage

<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { Item, ItemActions, ItemContent, ItemDescription, ItemTitle } from '@/components/ui/item'
</script>

<template>
  <Item variant="outline">
    <ItemContent>
      <ItemTitle>Two-step sign-in</ItemTitle>
      <ItemDescription>Ask for a code from your phone as well as your password.</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button variant="outline" color="neutral" size="sm">Turn on</Button>
    </ItemActions>
  </Item>
</template>
  • ItemMedia: an icon, image or avatar at the start
  • ItemContent: holds ItemTitle and ItemDescription, takes the free space
  • ItemActions: controls at the end
  • ItemHeader, ItemFooter: full-width rows above and below

Long text stays in its column. The description keeps two lines by default. A title is a flex row, so an icon or a badge can sit beside its text; to cut a long title with an ellipsis put line-clamp-1 on ItemTitle, or wrap the text in a <span class="truncate">. A plain truncate on the title clips without the ellipsis.

Examples

Media

variant="icon" puts an icon on a muted square, and variant="image" crops an image to a square. With a description, the media lines up with the title instead of the middle of the row.

Media
Icon

An icon on a muted square.

Midnight City cover
Midnight City

Nova Lane

Paper Suns cover
Paper Suns

The Quiet Hours

Group

ItemGroup stacks items, and ItemSeparator divides them.

Group
AL
Ada Lovelace

ada@example.com

GH
Grace Hopper

grace@example.com

AT
Alan Turing

alan@example.com

With as-child, the whole row becomes your link, with hover and press feedback. as="button" does the same for actions.

Header and footer
Aurora artwork
Aurora

Fast and light, for everyday answers.

128k context
Borealis artwork
Borealis

Slower and deeper, for long documents.

1M context

API Reference

Data attributes

data-slotAttributesDescription
itemdata-variant, data-sizeThe row.
item-group—A list of items.
item-separator—A line between two items.
item-mediadata-variantAn icon, image or avatar at the start.
item-content—The title and description.
item-title—The title.
item-description—Secondary text, clamped to two lines.
item-actions—Controls at the end.
item-header—A full-width row above.
item-footer—A full-width row below.

Accessibility

ItemGroup is a list, and its items are list items. Rows that are links or buttons can't be list items, so give their ItemGroup role="group" and an aria-label, as in the links example.

Changelog

  1. registry 0.22.1

    9398d0f — Item: a long title or description no longer pushes the content under the media or past the row's edge. ItemContent can shrink (min-w-0) and ItemTitle stops at its column (max-w-full), so line-clamp-1 on the title, or a truncate span inside it, cuts the text with an ellipsis.

  2. registry 0.22.0

    fbe99ae — InputNumber takes its text alignment from its own root through --input-number-align: a vertical InputNumber in a horizontal Field is no longer centred, an alignment class such as text-start on InputNumberInput wins, and a vertical decrement keeps its corner inside a filled Item.

    eedbfb0 — A class such as self-center or translate-y-0 on ItemMedia now wins over the top alignment it takes beside an ItemDescription: Item passes that alignment down through --item-media-align and --item-media-shift instead of a group variant that outranked the class.

  3. core 0.16.0

    26880d8 — state-layer no longer tints a natively disabled element or one marked data-disabled under the mouse or on press, only an aria-disabled one as before; a disabled Item as="button" stays flat.

  4. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  5. registry 0.19.0

    264c758 — Item: size is the row's density, as in shadcn. It sets padding, gap and the media size (through --item-media on the root), and no longer scales the text of ItemTitle and ItemDescription, which stay at text-label-lg and text-body-md. The parts carry no group-data-[size=…] variants any more, so a class of your own, like text-body-sm, line-clamp-none or size-12 on an ItemMedia, wins.

  6. registry 0.18.0

    779955e — Corners come in three roles: rounded-control-*, rounded-surface-* and rounded-item-*, each scaled from --radius and tunable on its own with --control-radius, --surface-radius and --item-radius, on :root or any element. Every component uses them, and cn() merges them, so a class prop still wins.

    - --control-radius was the Input family's frame variable. It now sets every control, and the frames use --frame-radius. - Nested parts no longer turn square at small radii: the InputGroup button, the InputNumber steppers, the TagsInput chips, the DatePicker trigger and the Toast and Tour close buttons. - Menus, lists, pill tabs, the menubar and the toolbar wrap their corners around their items. Pill tabs are rounder (12/8px at md instead of 8/4px), menus and lists grow by up to 2px, and their rows at sizes xs and xl follow their height. Item sm takes 8px instead of 6.4px.

  7. registry 0.15.0

    d09f26a — Pressable parts ripple on their own: Button, Toggle, ToggleGroupItem, Item as a link or a button, the calendar days, tabs, accordion, menubar and navigation menu triggers, the items of Menu, Menubar, Select, Combobox, Command, DrawerMenu, Listbox and Tree, and the clear buttons of TagsInput and Combobox. Each imports the directive from @/lib/ripple, so add brings the ripple item along and nothing needs registering. On menu, listbox and tree rows the wave replaces the pressed layer, as state-layer already did. Bind v-ripple="false" on a Button to turn one off, or set --kappa-ripple: none on :root to turn them all off.