Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    DescriptionList

    Shows the fields of a record as term and value pairs, with native dl, dt and dd elements.

    Storybook
    Storybook
    Source
    Source

    When to use

    Section titled “When to use”

    DescriptionList shows the fields of one record as terms and values: the detail panel of a record, a settings summary, a side panel. Terms are short; values are the information to read.

    When not to use

    Section titled “When not to use”
    • To compare many records: use Table or DataTable for data whose rows and columns are compared.
    • For a numeric summary: use StatCard for a value, change and trend.
    • For editable fields: use Field and the matching controls for form fields.
    • For a bulleted or ordered list: use a plain list for items without terms.

    Anatomy

    Section titled “Anatomy”
    1. Root (DescriptionList): a native <dl>; sets the layout, size and dividers.
    2. Item (DescriptionList.Item): a <div> that wraps the term, the value and the action; a valid group inside <dl>.
    3. Term (DescriptionList.Term): a <dt>; in the subtle colour, medium weight.
    4. Details (DescriptionList.Details): a <dd>; in the default colour. A dash and a hidden reason when empty.
    5. Action (DescriptionList.Action): a separate <dd> at the end of the row; optional.

    Behaviour

    Section titled “Behaviour”
    • DescriptionList is static: it has no entrance motion and is not a tab stop. Only the actions inside it are tab stops.
    • The inline layout stacks below 1024 px and sits side by side from 1024 px. The term column is the same width in every row (a third of the row).
    • A long value wraps; with the term and value side by side the value does not overflow.
    • An empty value shows —; the row is not removed.

    Guidelines

    Section titled “Guidelines”

    Keep the term short and the value clear

    Section titled “Keep the term short and the value clear”

    The term says what the value is; the value is the information.

    Status
    Active
    Created
    28 October 2026
    DoA short term, a clear value.
    What is the current status of this item
    Active
    Don'tThe term is as long as a sentence; it blends with the value.

    Do not hide an empty value

    Section titled “Do not hide an empty value”

    When there is no information, keep the row and show a dash. Rows stay in the same place from record to record.

    Name
    First item
    Description
    bilgi yok
    DoNo value: a dash and a hidden reason.
    Name
    First item
    Don'tThe empty row is removed; rows shift between records.

    Show status in text

    Section titled “Show status in text”

    A Badge can be the value; the status reads as text.

    Status
    Active
    DoThe status is in a Badge, as text.
    Status
    Don'tOnly a coloured dot carries the status.

    Content

    Section titled “Content”
    • Write the term as a noun phrase in sentence case: “Created”, “Identifier”.
    • Do not add a colon to the term; the layout separates them.
    • Have your app format the value with Intl.
    • Name the action with a verb and say what it affects: “Copy identifier”.
    Section titled “Related components”
    • StatCard: for numeric summaries.
    • Card: to group a DescriptionList on a surface.
    • Badge: for status values.
    • Button: for actions at the end of a row.