List
UiListGroup wraps UiListItem entries. Make items interactive for navigation or selection.
Add a list
<template>
<UiListGroup>
<UiListItem title="Inbox" text="12 new" icon="" />
<UiListItem title="Drafts" icon="" />
<UiListItem title="Archive" icon="" disabled />
</UiListGroup>
</template>
Use an image instead of an icon
Pass imageUrl to render an image in place of the icon (it takes precedence over icon), or use the media slot for arbitrary content such as UiIconSvg.
<template>
<UiListGroup>
<UiListItem
title="Jane Cooper"
text="jane.cooper@example.com"
image-url="/avatars/jane.jpg"
image-alt="Jane Cooper avatar"
/>
<UiListItem title="GitHub" text="@giancarlosgza">
<template #media>
<UiIconSvg :content="brandIcons.github" size="sm" />
</template>
</UiListItem>
</UiListGroup>
</template>
Make it interactive
<template>
<UiListGroup is-interactive variant="flush" size="sm">
<UiListItem title="Profile" active />
<UiListItem title="Billing" />
</UiListGroup>
</template>
Use it as a link
Pass to or href to render UiListItem as a link instead of a plain item. The rendered tag defaults to a; override it with as for framework router links (e.g. NuxtLink, RouterLink). Link mode automatically implies the hover / active / arrow styling that UiListGroup's isInteractive prop provides, so you don't need to also set it on the group. disabled strips href/to and blocks pointer events, without changing any markup for items that don't pass a link prop.
<template>
<UiListGroup>
<UiListItem title="Dashboard" icon="" to="/dashboard" />
<UiListItem title="Colorffy" icon="" href="https://colorffy.com" />
<UiListItem title="Router link" icon="" to="/settings" as="router-link" />
<UiListItem title="Unavailable" icon="" to="/billing" disabled />
</UiListGroup>
</template>
UiListGroup props
| Prop | Type | Default | Description |
|---|---|---|---|
variant | 'flush' | 'low-contrast' | — | Surface style. |
size | 'sm' | 'md' | — | Item size. |
isInteractive | boolean | false | Hover / active styles. |
isUndecorated | boolean | false | Hide the interactive arrow indicator. |
customClass | string | string[] | Record<string, boolean> | null | — | Extra classes. |
UiListItem props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | null | — | Primary text. |
text | string | null | — | Supporting text. |
icon | string | null | — | Leading Material Symbols code. |
imageUrl | string | null | — | Image rendered in place of the icon (takes precedence over icon). |
imageAlt | string | null | '' | Alt text for the image (empty = decorative). |
customClass | string | string[] | Record<string, boolean> | null | — | Extra classes for the <li>. |
customIconWrapperClass | string | string[] | Record<string, boolean> | null | — | Extra classes for the icon wrapper. |
customIconClass | string | string[] | Record<string, boolean> | null | — | Extra classes for the icon. |
customImageClass | string | string[] | Record<string, boolean> | null | — | Extra classes for the image (e.g. rounded-full). |
active | boolean | false | Active styling. |
disabled | boolean | false | Disable the item. Strips href/to and blocks pointer events in link mode. |
hasActions | boolean | false | Layout for trailing actions. |
to | string | object | null | — | Navigation destination. Activates link mode. |
href | string | null | — | Standard href for link mode (e.g. external links). |
as | string | object | null | 'a' | Tag/component rendered in link mode (e.g. 'router-link', 'nuxt-link'). Ignored unless to or href is set. |
Slots: media replaces the whole image/icon area; list-action renders trailing actions when hasActions is set.
CSS variables
Set these on :root, or on any wrapper to restyle only the lists inside it. In a stacked list, --cffy-list-radius sets the outer corners of the first and last items and --cffy-list-item-radius the items in between (and a lone item); the inner corners stay small. The sm and md sizes, flush, low-contrast and disabled styles keep their own values. Hover and pressed backgrounds come from the shared state layer.
:root {
--cffy-list-radius: var(--cffy-radius-xl);
--cffy-list-icon-bg-color: var(--cffy-on-primary-container);
--cffy-list-icon-color: var(--cffy-on-primary);
}
| Variable | Default | Controls |
|---|---|---|
--cffy-list-gap | --cffy-space-6 | Space between items |
--cffy-list-bg-color / --cffy-list-border-color | --cffy-surface-container / transparent | Item background and border |
--cffy-list-color / --cffy-list-subtitle-color | --cffy-on-background / --cffy-muted-a10 | Title and subtitle text |
--cffy-list-title-font-size / --cffy-list-title-font-weight | --cffy-fs-3xs / --cffy-fw-600 | Title text |
--cffy-list-subtitle-font-size | --cffy-fs-3xs | Subtitle text |
--cffy-list-radius | --cffy-shape-container | Outer corners of the first and last items |
--cffy-list-item-radius | --cffy-radius-md, up to --cffy-shape-container | Corners of the items in between, and of a lone item |
--cffy-list-item-padding / --cffy-list-item-gap | --cffy-space-8 / --cffy-space-14 | Item padding and the gap between icon and text |
--cffy-list-icon-bg-color / --cffy-list-icon-color | --cffy-surface-container-lowest / --cffy-on-background | Icon tile |
--cffy-list-icon-size / --cffy-list-icon-padding / --cffy-list-icon-radius | --cffy-fs-lg / 0.625rem / --cffy-radius-md | Icon size, tile padding and corners |
--cffy-list-image-size / --cffy-list-image-radius | 2.75rem / --cffy-radius-md | Leading image |
--cffy-list-arrow-color | --cffy-muted-a10 | Trailing arrow of interactive and link items |
--cffy-list-active-bg-color / --cffy-list-active-border-color | Surface tinted with --cffy-primary-base | Active item |
--cffy-list-active-icon-bg-color / --cffy-list-active-icon-color | --cffy-on-primary-container / --cffy-on-background-inverse | Active item icon tile |
--cffy-list-easing / --cffy-list-duration | --cffy-ease-decelerate / --cffy-duration-200 | Background and border transitions |