Get startedFoundationsComponentsTemplatesBlocksAI
This site is a work in progress as part of GovTech {build} hackathon. Content may be incomplete or subject to change.
Browse Components

Components

AccordionAlertBadgeBreadcrumbButtonCard groupCardIcon cardImage cardThumbnail cardCheckboxClose buttonCombo boxDatepickerDescription listDividerDrawerDropdownFile uploadFooterIcon buttonIcon listInputLinkMainnavMastheadModalOverflow menuPaginationProgress barQuantity toggleRadioSelectSidebarSidenavSkeletonSpinnerStepperSubnavSwitchSystem bannerTabTableTable of contentsTextareaToastTooltip

Description list

Description lists pair terms with values in a structured, readable layout.

GitHub
Storybook
DesignUsageAccessibilityUpdates

Purpose

Pair labels with values

Use description lists for names and values, terms and definitions, or attributes and data.

Support review

Show entered details on summary or confirmation pages before users submit.

Keep details readable

The layout separates labels and values in a compact summary.

Anatomy

Title Description Label Data Label Data Label Data
1

Title (optional)

2

Description (optional)

3

Label

4

Data

5

Divider

Configuration

Layout direction

Use stacked to display the label above the data instead of side by side.

Full name Tan Mei Ling Email meiling.tan@example.gov.sg

Default layout displays the label and data side by side.

Bordered

Use bordered to add dividers between each description list item and around the group.

Application status In review Submitted on 12 Mar 2026

Borderless presentation suits compact summaries within other surfaces.

Structure

Application status Pending verification by service team Updated 31 Mar 2026, 10:30am

Design tokens used

Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.

CategoryTokenValueWhere it's usedPaddingsgds-padding-xl24pxSpace between the left and right edges of the component and its contentsgds-padding-lg20pxSpace between the top and bottom edges of the component and its contentGapsgds-gap-2-xl—Spacing between items of the containersgds-gap-2-xs4pxSpacing between items of the containersgds-gap-xs8pxSpacing between items of the headerBordersgds-border-radius-md8pxCorner radius of the containersgds-border-width-11pxBorder of the container; bottom border of the has headerTypographysgds-font-size-1616pxFont size of the content; font size of the labelsgds-font-size-24—Font size of the contentsgds-font-weight-regular—Font weight of the content; font weight of the datasgds-font-weight-semibold—Font weight of the content; font weight of the labelsgds-letter-spacing-tight—Letter spacing of the contentsgds-line-height-2424pxLine height of the contentsgds-line-height-32Height variesLine height of the contentSizesgds-dimension-280—Maximum width of the label container

Usage

When to use

  • Use description list when it gives users a clearer, more consistent SGDS interaction for the task at hand.
  • Use the built-in SGDS pattern when it helps users recognise the component quickly and act with confidence.

When not to use

  • Do not use this component when a simpler SGDS pattern would communicate the same thing more clearly.
  • Do not add repeated or decorative instances that compete with the main content.

Best practices

Application reference SG-2026-04823 Submitted on 12 Mar 2026 Status In review
Use description lists for read-only key-value pairs

Description lists display paired information for review. Use them on summary, confirmation, and detail pages.

Applicant 1 Tan Mei Ling. Approved Applicant 2 Lim Wei Jie. Pending Applicant 3 Nur Aisyah. Rejected
Do not use a description list for tabular data

Use a table for row-by-row comparison. Description lists describe one entity at a time.

Mailing address Block 123, Toa Payoh Lorong 4, #08-456, Singapore 310123 Notes from officer Documents have been verified. Awaiting final approval from the assessment team.
Stack the layout when values are long

Use the stacked layout when values wrap to multiple lines or in narrow columns and small screens.

What is the applicant's full legal name? Tan Mei Ling Email address: meiling.tan@example.gov.sg Contact number provided by applicant +65 9123 4567
Do not make labels hard to scan

Avoid long question-style labels or inconsistent wording. Full-sentence content belongs elsewhere.

Full name Tan Mei Ling Email meiling.tan@example.gov.sg Phone +65 9123 4567
Keep labels short and consistent

Use concise, parallel labels so users can scan the left column. Avoid sentence-style labels or colons.

Phone Alternate email
Do not leave empty values without a placeholder

If a value is missing, show a placeholder such as 'Not provided' rather than leaving the slot empty.

Accessibility considerations

Built-in accessibility

  • Description lists present terms and supporting details as paired content.
  • The component does not add custom keyboard behaviour.

Labels and content

  • Use short terms and clear descriptions.
  • Keep each term and description pair complete when read on its own.

Focus and interaction

  • Do not place unrelated interactive controls inside description list values.
  • If a value includes a link, the link should be reachable in normal tab order.

Keyboard interaction

This component does not have a separate keyboard interaction table because:

  • Description lists are structural content for term and detail pairs.
  • Keyboard interaction only applies to links, buttons, or controls placed inside a value.

Updates

DateVersionDescription18 Dec 2025v3.6.0Allow the non-stacked list to stack in mobile, apply max width for label in #471.04 Apr 2025v3.0.0- **Description List** – Provides a structured way to display term-description pairs.

Roadmap

Planned itemStatusTargetFuture enhancements for description listPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #ask-sgds-v3

Bug Reports

Found a bug or issue?

Report it on GitHub Issues → sgds/components/description-list

Singapore Government Design System

The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.

Past VersionsSGDS v1SGDS v2