<c-list>
A vertical list of rows, each a `c-list-item` with its main content and optional leading and trailing content, for settings entries, related pages or a short set of records.
Usage
Put the row's main content, usually a c-list-item-title, in the item's default slot, an icon or other leading content in the pre slot and trailing content in the post slot. Empty pre and post slots take no space. The default slot stacks its children, so a title can carry a second line of text under it.
<c-list bordered>
<c-list-item href="/settings/profile" active>
<c-list-item-title>Profile</c-list-item-title>
<span>Name, email and language</span>
</c-list-item>
<c-list-item href="/settings/notifications">
<c-list-item-title>Notifications</c-list-item-title>
</c-list-item>
</c-list>
When to use
- A short list of rows the user reads or opens: settings sections, related pages, the members of a project.
- For the application's main navigation, use
c-side-navigation; for a panel of commands,c-menu. - For records with several columns, use
c-data-tableorc-table.
Interactive items
An item is static by default: a row of content with no hover state and no place in the Tab order.
hrefturns the item's content box into a real link, with focus, Enter, middle-click and open-in-new-tab from the platform, and a hover tint on the row.targetsays where the link opens, as on a native<a>: the same tab unless set,_blankfor a new one.rippleadds a pointer cursor, the hover tint and a ripple on press, and puts an item withouthrefin the Tab order, where Enter and Space press it: each firesclick, as a mouse click does. Give navigation anhref; an action of the item's own can also go in ac-buttonin thepostslot.hoverableadds the hover tint alone.
Active and disabled items
active marks the current item with a primary tint and an inset primary ring; in a bordered list its border turns primary too. Assistive technology hears it as the current item: aria-current="page" on a link item, aria-current="true" on any other.
disabled greys an item out, a slotted c-icon included, ignores the pointer, and takes the item out of the Tab order (a disabled link item stops being a link). disabled on the list disables every item, also items added later. Clearing it re-enables only the items the list disabled, so an item you disabled yourself stays disabled.
Accessibility
The list has role="list" and each item role="listitem", so a screen reader announces the list and how many items it holds. An item with href is a link named by its content.
Customization
bordered draws a 1px border with rounded corners around each item. c-list::part(root) is the grid holding the items, 4px apart; c-list-item::part(root) is an item's content box (a <div>, or the <a> when href is set); c-list-item-title::part(root) is the title text.
c-list::part(root) {
gap: 0;
}
Examples
<template>
<div>
<c-list bordered>
<c-list-item
v-for="item in items"
:key="item.label"
:active="selected === item.label"
ripple
@click="selected = item.label"
>
<c-icon slot="pre" :path="item.icon" />
<c-list-item-title>{{ item.label }}</c-list-item-title>
</c-list-item>
</c-list>
</div>
</template>
<script setup lang="ts">
import { mdiAccount, mdiBell, mdiCog } from '@mdi/js';
import { ref } from 'vue';
const items = [
{ icon: mdiAccount, label: 'Profile' },
{ icon: mdiBell, label: 'Notifications' },
{ icon: mdiCog, label: 'Settings' },
];
const selected = ref('Profile');
</script>
<template>
<div>
<c-list>
<c-list-item hoverable>
<c-icon slot="pre" :path="mdiAccount" />
<c-list-item-title>Profile</c-list-item-title>
</c-list-item>
<c-list-item active>
<c-icon slot="pre" :path="mdiBell" />
<c-list-item-title>Notifications</c-list-item-title>
<c-icon slot="post" :path="mdiChevronRight" />
</c-list-item>
<c-list-item disabled>
<c-icon slot="pre" :path="mdiCog" />
<c-list-item-title>Settings</c-list-item-title>
</c-list-item>
</c-list>
</div>
</template>
<script setup lang="ts">
import { mdiAccount, mdiBell, mdiChevronRight, mdiCog } from '@mdi/js';
</script>
<template>
<div>
<c-list>
<c-list-item>
<c-list-item-title>Profile</c-list-item-title>
</c-list-item>
<c-list-item active>
<c-list-item-title>Notifications</c-list-item-title>
</c-list-item>
<c-list-item>
<c-list-item-title>Settings</c-list-item-title>
</c-list-item>
</c-list>
</div>
</template>
API reference
<c-list>
A vertical list of rows, each a `c-list-item` with its main content and optional leading and trailing content, for settings entries, related pages or a short set of records.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
bordered | bordered | boolean | false | Draw a 1px border with rounded corners around each item; an `active` item's border turns primary. |
disabled | disabled | boolean | false | Disable every item, items added later included; clearing it re-enables only the items the list disabled. |
Slots
| Slot | Description |
|---|---|
default | c-list-item components of the list |
CSS parts
Style from outside with c-list::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The grid container laying out the list items |
<c-list-item>
One row of a `c-list`: its main content goes in the default slot, leading content such as an icon in the `pre` slot and trailing content in the `post` slot. The row is static unless it has an `href`, which makes it a real link; `ripple` adds a press effect and a Tab stop that Enter and Space press, firing `click`; give navigation an `href`.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
active | active | boolean | false | Mark the item as the current one: a primary tint and ring, announced as current (`aria-current`). |
disabled | disabled | boolean | false | Grey the item out, ignore the pointer and take it out of the Tab order; a link item stops being a link. |
hoverable | hoverable | boolean | false | Add the hover tint alone, without a link or a ripple. |
href | href | string | '' | URL that turns the item's content box into a real link, with a hover tint on the row. |
ripple | ripple | boolean | false | Add a pointer cursor, the hover tint and a ripple on press; an item without `href` also becomes a Tab stop that Enter and Space press, firing `click`. |
target | target | string | '' | Where the `href` opens, as on a native `<a>`: the same tab unless set — `_blank` for a new one. |
Slots
| Slot | Description |
|---|---|
pre | Leading content (e.g. an icon) shown before the item's main content |
default | Main content of the item, e.g. a c-list-item-title |
post | Trailing content (e.g. an icon or action) shown after the item's main content |
CSS parts
Style from outside with c-list-item::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The item's content box — a `<div>`, or an `<a>` when `href` is set |
<c-list-item-title>
The main text of a `c-list-item`, in medium-weight type; place it in the item's default slot. It takes the active row's ink by itself when its item is `active`.
Slots
| Slot | Description |
|---|---|
default | The title text of the list item |
CSS parts
Style from outside with c-list-item-title::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The element wrapping the title text |