Item

A versatile row for lists and settings: media, title, description and actions. When an item is narrower than 360vp its actions wrap under the text.

Usage

SItem({ variant: 'outline' }) {
  SItemContent() {
    SItemTitle({ text: 'Basic Item' })
    SItemDescription({ text: 'A simple item with title and description.' })
  }
  SItemActions() { SButton({ text: 'Action', variant: 'outline', sizing: 'sm' }) }
}
SItem({ variant: 'muted', sizing: 'sm' }) {
  SItemMedia({ icon: 'badge-check' })
  SItemContent() { SItemTitle({ text: 'Your profile has been verified.' }) }
  SItemActions() { SIcon({ name: 'chevron-right', sizing: 16 }) }
}

Approximate web preview — the HarmonyOS rendering is the reference.

Settings group

SItemGroup({ bordered, separators }) turns rows into a settings card: flush rows, inset hairlines, tinted icon tiles and pressed feedback on interactive rows.

SItemGroup({ bordered: true, separators: true }) {
  Stack() {
    SItem({ interactive: true }) {
      SItemMedia({ icon: 'bell', variant: 'icon', tint: theme.colors.chart1 })
      SItemContent() {
        SItemTitle({ text: 'Notifications' })
        SItemDescription({ text: 'Push, email and in-app alerts.' })
      }
      SItemActions() { SIcon({ name: 'chevron-right', color: theme.colors.mutedForeground }) }
    }
  }.onClick(() => this.open('notifications'))
  SItem() {
    SItemMedia({ icon: 'shield-check', variant: 'icon', tint: theme.colors.chart2 })
    SItemContent() {
      SItemTitle({ text: 'Two-factor authentication' }) { SBadge({ text: 'On', variant: 'secondary' }) }
      SItemDescription({ text: 'Require a code from your phone when signing in.' })
    }
    SItemActions() { SButton({ text: 'Manage', variant: 'outline', sizing: 'sm' }) }
  }
  ...
}

Approximate web preview — the HarmonyOS rendering is the reference.

Image & avatar media

SItem({ variant: 'outline' }) {
  SItemMedia({ variant: 'image', src: $r('app.media.startIcon') })
  SItemContent() {
    SItemTitle({ text: 'SparkUI Gallery' })
    SItemDescription({ text: 'Version 0.1.0 · HarmonyOS' })
  }
  SItemActions() { SButton({ variant: 'ghost', sizing: 'icon-sm', icon: 'download', label: 'Download' }) }
}
SItem({ variant: 'outline' }) {
  SItemMedia() { SAvatar({ fallback: 'ER', sizing: 40 }) }
  SItemContent() {
    SItemTitle({ text: 'Evil Rabbit' })
    SItemDescription({ text: 'Last seen 5 months ago' })
  }
  SItemActions() { SButton({ text: 'Invite', sizing: 'sm', icon: 'plus' }) }
}

Approximate web preview — the HarmonyOS rendering is the reference.

Narrow

Below 360vp the actions move to their own line under the text.

// same SItem, placed in a 300vp wide column

Approximate web preview — the HarmonyOS rendering is the reference.

API

Extracted from the @Param / @Event / @BuilderParam declarations in the library sources.

SItemGroup

shadcn-vue ItemGroup: a vertical list of SItem. bordered turns it into a settings-style card (bg-card border, rounded-xl, items flush and clipped); separators draws a hairline between items automatically (inset to the text column when insetSeparators).

Prop	Type	Default	Description
bordered	boolean	false
separators	boolean	false
insetSeparators	boolean	true
spacing	number	0	vertical gap between items in vp (shadcn ItemGroup has none; outline items often use 16)
modifier	AttributeModifier<ColumnAttribute>	new SparkNoopModifier<ColumnAttribute>()

Slots: children (trailing closure)

SItem

shadcn-vue Item: flex flex-wrap items-center gap-4 rounded-md border border-transparent p-4 text-sm (sm: gap-2.5 px-4 py-3). Variants: default (transparent), outline (border-border), muted (bg-muted/50).

interactive adds hover (bg-accent/50) and pressed (bg-accent) feedback and focusability; attach the action with a wrapping Stack() { SItem(...) { ... } }.onClick(...) (slot components cannot chain events).

Responsive: when the item itself is narrower than 360vp, SItemActions wraps onto its own line under the text.

Prop	Type	Default	Description
variant	ItemVariant ItemVariant = 'default' | 'outline' | 'muted'	'default'
sizing	ItemSize ItemSize = 'default' | 'sm'	'default'
interactive	boolean	false	hover / pressed feedback + focusable (use when the row is clickable)
modifier	AttributeModifier<FlexAttribute>	new SparkNoopModifier<FlexAttribute>()

Slots: children (trailing closure)

SItemSeparator

Separator between items when not using SItemGroup({ separators: true }).

No props.

SItemMedia

ItemMedia: default (bare icon / avatar, 20vp icon), icon (size-8 rounded-sm border bg-muted, 16vp icon) or image (size-10 rounded-sm overflow-hidden, object-cover src). Aligns to the top when the item has a description.

tint (an #AARRGGBB token such as theme.colors.chart2) gives the icon variant a soft coloured tile — handy for settings lists.

Prop	Type	Default	Description
icon	string | undefined	undefined
variant	ItemMediaVariant ItemMediaVariant = 'default' | 'icon' | 'image'	'default'
src	ResourceStr | undefined	undefined	image for the image variant
tint	string | undefined	undefined

Slots: children (trailing closure)

SItemContent

flex flex-1 flex-col gap-1: title + description.

Slots: children (trailing closure)

SItemTitle

flex w-fit items-center gap-2 text-sm leading-snug font-medium; the slot holds trailing badges.

Prop	Type	Default	Description
text	ResourceStr	''

Slots: children (trailing closure)

SItemDescription

text-muted-foreground line-clamp-2 text-sm leading-normal.

Prop	Type	Default	Description
text	ResourceStr	''
maxLineCount	number	2	line clamp (shadcn: 2)

SItemActions

flex items-center gap-2, trailing; wraps under the text (aligned with it) when the item is narrow.

Slots: children (trailing closure)