CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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-table or c-table.

Interactive items

An item is static by default: a row of content with no hover state and no place in the Tab order.

  • href turns 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. target says where the link opens, as on a native <a>: the same tab unless set, _blank for a new one.
  • ripple adds a pointer cursor, the hover tint and a ripple on press, and puts an item without href in the Tab order, where Enter and Space press it: each fires click, as a mouse click does. Give navigation an href; an action of the item's own can also go in a c-button in the post slot.
  • hoverable adds 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

Basic
Vue React Angular TypeScript
<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>
Basic · c-list-item
Vue React Angular TypeScript
<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>
Basic · c-list-item-title
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
borderedborderedbooleanfalse Draw a 1px border with rounded corners around each item; an `active` item's border turns primary.
disableddisabledbooleanfalse Disable every item, items added later included; clearing it re-enables only the items the list disabled.

Slots

SlotDescription
defaultc-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.

PartDescription
rootThe 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

PropertyAttributeTypeDefaultDescription
activeactivebooleanfalse Mark the item as the current one: a primary tint and ring, announced as current (`aria-current`).
disableddisabledbooleanfalse Grey the item out, ignore the pointer and take it out of the Tab order; a link item stops being a link.
hoverablehoverablebooleanfalse Add the hover tint alone, without a link or a ripple.
hrefhrefstring'' URL that turns the item's content box into a real link, with a hover tint on the row.
rippleripplebooleanfalse 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`.
targettargetstring'' Where the `href` opens, as on a native `<a>`: the same tab unless set — `_blank` for a new one.

Slots

SlotDescription
preLeading content (e.g. an icon) shown before the item's main content
defaultMain content of the item, e.g. a c-list-item-title
postTrailing 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.

PartDescription
rootThe 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

SlotDescription
defaultThe 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.

PartDescription
rootThe element wrapping the title text