Lily Design System™

Collection List Item

A collection list item is one entry in a collection-list, presenting a required heading plus optional thumbnail image, meta line (date, category), and short description.

Use it inside CollectionList to render homogeneous summary cards for articles, events, search results, or news entries.

Example

CollectionListItem
Show demo markup 
<div class="collection-list-item" aria-label="one item in a collection list with optional image, heading, meta, and description">CollectionListItem</div>
Usage example 
<script lang="ts">
  import CollectionList from '../CollectionList/CollectionList.svelte';
  import CollectionListItem from './CollectionListItem.svelte';
</script>

<CollectionList label="Articles">
  <CollectionListItem
    heading="My article"
    href="/articles/my-article"
    meta="March 2026"
    description="A short summary of the article."
  />
</CollectionList>
Show Svelte source 
// In your Svelte component:
import CollectionListItem from "lily-design-system-svelte-headless/components/CollectionListItem/CollectionListItem.svelte";

<CollectionListItem>
  <!-- CollectionListItem content -->
</CollectionListItem>

Usage

Article entry with link, meta, and description:

<CollectionListItem
  heading="Plain language is for everyone"
  href="/blog/plain-language"
  meta="Published Jan 5, 2025"
  description="A short overview of why plain language matters in public services."
/>

Event entry with thumbnail:

<CollectionListItem
  heading="Annual conference"
  imageUrl="/img/conf.jpg"
  imageAlt="Speaker on stage"
  meta="May 12, 2025"
/>

Composition

This component is part of the *List *ListItem composition pattern. It must be a child of CollectionList.

Props

  • heading: string (required) -- item heading text
  • meta: string (optional) -- meta line such as a date or category
  • description: string (optional) -- body description text
  • imageUrl: string (optional) -- thumbnail image src
  • imageAlt: string (optional) -- thumbnail image alt text
  • href: string (optional) -- when provided, the heading is wrapped in an <a>
  • label: string (optional) -- aria-label override
  • children: slot -- additional content rendered after the description
  • ...restProps: any additional HTML attributes

Keyboard Interactions

  • Tab: moves focus to the heading link (when href is provided) or to descendants
  • All key handling is delegated to the contained interactive elements

ARIA

  • Implicit listitem role from <li> element
  • aria-label is rendered when label is supplied
  • Image alt attribute provides the image's accessible text

When to Use

  • Use as a child of CollectionList to render an entry in a homogeneous list.
  • Use when each entry has a heading and optional supporting information.
  • Use when the heading should optionally link to a detail page.

When Not to Use

  • Do not use outside a CollectionList.
  • Do not use for tabular data — use DataTableRow instead.
  • Do not use for navigation list items — use the appropriate *ListItem for the navigation.

Headless

Renders the structural skeleton — <li> with optional <img>, <h3>, <p class="...-meta">, <p class="...-description">, and slot. Visual spacing, image dimensions, and typography are entirely the consumer's responsibility.

Styles

Consumer CSS targets the collection-list-item class plus the inner collection-list-item-image, collection-list-item-heading, collection-list-item-meta, and collection-list-item-description classes for fine-grained control.

Testing

  • Verify the component renders an <li> element with class collection-list-item
  • Verify the heading text appears inside an <h3> element
  • Verify the heading is wrapped in an <a> when href is provided
  • Verify the heading is plain text when href is omitted
  • Verify the image renders only when imageUrl is provided
  • Verify the meta paragraph renders only when meta is provided
  • Verify the description paragraph renders only when description is provided
  • Verify children render after the description when supplied
  • Verify additional HTML attributes pass through to the root <li>

Advice

  • Designers: Keep heading length predictable so the list reads as a tidy stack. Use thumbnails sparingly and at consistent dimensions.
  • Developers: Always supply imageAlt when imageUrl is set. Use href to make the heading the link target so the entire heading text is announced as the link.

Implementation Notes

  • Renders a native <li> element with class collection-list-item
  • heading prop is required — it is rendered as an <h3> heading inside the item
  • When href is provided, the heading text is wrapped in an <a> element
  • Optional imageUrl + imageAlt render a leading <img> thumbnail
  • Optional meta renders a meta paragraph (e.g., date or category)
  • Optional description renders a body paragraph
  • Optional children render after the description for custom extra content
  • Optional label sets aria-label to override the default accessible name

Related components

  • collection-list — a compact list of multiple related items such as articles or events

References

  • US Web Design System Collection: https://designsystem.digital.gov/components/collection/
  • HTML <li>: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li
  • WCAG 1.1.1 Non-text Content: https://www.w3.org/WAI/WCAG22/Understanding/non-text-content

Canonical contract

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

Metadata

  • Component: collection-list-item
  • PascalCase: CollectionListItem
  • Description: one item in a collection list with optional image, heading, meta, and description
  • Status: beta — implemented and unit-tested in all seven frameworks with an axe-clean demo page; not yet exercised in composed flows
  • HTML tag: <li>
  • CSS class: .collection-list-item
  • Interactive: no (heading link is interactive when href is provided)

ARIA

  • Implicit listitem role from the <li> element
  • aria-label is rendered only when label is provided
  • Image alt provides the image's accessible text

Keyboard

  • Tab: moves focus to the heading link (when href is provided) or to descendants
  • All key handling is delegated to the contained interactive elements

Props

  • heading: string (REQUIRED) -- item heading text
  • meta: string (optional) -- meta line
  • description: string (optional) -- body description
  • imageUrl: string (optional) -- thumbnail image src
  • imageAlt: string (optional) -- thumbnail image alt
  • href: string (optional) -- wraps heading in <a>
  • label: string (optional) -- aria-label override
  • children: slot -- additional content
  • ...restProps: any additional HTML attributes