Lily Design System™

Collection List

A collection list is a compact <ul> of related items — typically articles, events, search results, or news entries — rendered as a vertical stack of collection-list-item children.

Use it whenever a page presents many small content cards that share a template (heading, optional meta, optional thumbnail) and should be announced as a single list to assistive technology.

Example

CollectionList
Show demo markup 
<div class="collection-list" aria-label="a compact list of multiple related items such as articles or events">CollectionList</div>
Usage example 
<script lang="ts">
  import CollectionList from './CollectionList.svelte';
  import CollectionListItem from '../CollectionListItem/CollectionListItem.svelte';
</script>

<CollectionList label="Latest articles">
  <CollectionListItem heading="Article one" href="/a/1" />
  <CollectionListItem heading="Article two" href="/a/2" />
</CollectionList>
Show Svelte source 
// In your Svelte component:
import CollectionList from "lily-design-system-svelte-headless/components/CollectionList/CollectionList.svelte";

<CollectionList>
  <!-- list children -->
</CollectionList>

Usage

Basic collection of articles:

<CollectionList label="Recent articles">
  <CollectionListItem heading="First post" meta="Jan 5" />
  <CollectionListItem heading="Second post" meta="Jan 12" />
</CollectionList>

Composition

This component is part of the *List *ListItem composition pattern. Pair it with CollectionListItem children to form a complete collection.

Props

  • label: string (optional) -- aria-label for the list
  • children: slot -- collection-list-item children
  • ...restProps: any additional HTML attributes

Keyboard Interactions

  • Tab: focus moves to interactive descendants (links, buttons) within items
  • The list itself is not interactive

ARIA

  • Implicit list role from <ul> element
  • aria-label is provided when the label prop is set
  • Each child contributes a list item via its <li> element

When to Use

  • Use to present a homogeneous series of related content cards.
  • Use when items share the same template and should be announced as a single list.
  • Use as the body of search results, news feeds, event calendars.

When Not to Use

  • Do not use for navigation menus — use a Nav + List + ListItem composition.
  • Do not use for tabular data — use DataTable.
  • Do not use for a single item — use the underlying card or article element directly.

Headless

Renders only the <ul> semantics. The list spacing, item dividers, and any visual rhythm are entirely the consumer's responsibility.

Styles

Consumer CSS targets the collection-list class. Typical treatments remove default list bullets, apply consistent vertical spacing, and add optional dividers between items.

Testing

  • Verify the component renders a <ul> element with class collection-list
  • Verify aria-label is present when label is supplied
  • Verify aria-label is absent when label is omitted
  • Verify children render inside the list
  • Verify additional HTML attributes pass through to the root <ul>

Advice

  • Designers: Keep item templates consistent so the list reads predictably. Use a generous vertical rhythm to separate items.
  • Developers: Always supply CollectionListItem children. Add label when the list's purpose is not clear from surrounding context.

Implementation Notes

  • Renders a native <ul> element with class collection-list
  • label prop is optional — when supplied it sets aria-label on the list
  • Children are expected to be collection-list-item elements
  • The <ul> semantics provide list count and item position to screen readers
  • Pass-through attributes are forwarded to the root <ul>

Related components

  • collection-list-item — one item in a collection list with optional image, heading, meta, and description

References

  • US Web Design System Collection: https://designsystem.digital.gov/components/collection/
  • HTML <ul>: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul
  • WCAG 1.3.1 Info and Relationships: https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: collection-list
  • PascalCase: CollectionList
  • Description: a compact list of multiple related items such as articles or events
  • Status: beta — implemented and unit-tested in all seven frameworks with an axe-clean demo page; not yet exercised in composed flows
  • HTML tag: <ul>
  • CSS class: .collection-list
  • Interactive: no

ARIA

  • Implicit list role from the <ul> element
  • aria-label is rendered only when label is provided

Keyboard

  • Tab: moves focus to interactive descendants of the items
  • The list itself is not interactive

Props

  • label: string (optional) -- aria-label for the list
  • children: slot -- collection-list-item children
  • ...restProps: any additional HTML attributes