Description list

Labels and their values, for display. Inside it, use the native parts: dt for a label and dd for its value, optionally a div around each pair. Reticle styles them. Values wrap; an empty dd shows "—", which screen readers read as "Not available". A columns list measures its own width, so it fills the width it is given: in a flex row, give it flex: 1. Props and ref go to the outer div.

Owner: Sam Lee
Email: ana.ruiz@etched.com
Phone

import type { CSSProperties } from "react";
import { DescriptionList } from "@etched/reticle/description-list";

/** A panel around a list, like Orbit's side cards. The app sets its width. */
const panel = (inlineSize: string): CSSProperties => ({ boxSizing: "border-box", inlineSize, padding: "var(--et-space-4)" });

export function Preview() {
  return (
    <div className="card" style={panel("18rem")}>
      <DescriptionList layout="columns">
        <div>
          <dt>Owner</dt>
          <dd>Sam Lee</dd>
        </div>
        <div>
          <dt>Email</dt>
          <dd>ana.ruiz@etched.com</dd>
        </div>
        <div>
          <dt>Phone</dt>
          <dd />
        </div>
      </DescriptionList>
    </div>
  );
}

Installation

import { DescriptionList } from "@etched/reticle/description-list";

Examples

Columns, with actions

Orbit's candidate details. The Edit button sits at the top end. An empty value shows a dash; long values wrap.

Email: ana.ruiz@etched.com
Phone
Education: MS Electrical Engineering, University of Illinois Urbana-Champaign; BS Physics, Universidad de Buenos Aires
LinkedIn: linkedin.com/in/ana-ruiz-asic-design
Added by: Sam Lee

import type { CSSProperties } from "react";
import { Button } from "@etched/reticle/button";
import { Link, LinkExternalIcon } from "@etched/reticle/link";
import { DescriptionList } from "@etched/reticle/description-list";

/** A panel around a list, like Orbit's side cards. The app sets its width. */
const panel = (inlineSize: string): CSSProperties => ({ boxSizing: "border-box", inlineSize, padding: "var(--et-space-4)" });

export function ColumnsWithActions() {
  return (
    <div className="card" style={panel("22rem")}>
      <DescriptionList layout="columns" actions={<Button size="sm" variant="ghost" aria-label="Edit details for Ana Ruiz">Edit</Button>}>
        <div>
          <dt>Email</dt>
          <dd>
            <Link href="mailto:ana.ruiz@etched.com">ana.ruiz@etched.com</Link>
          </dd>
        </div>
        <div>
          <dt>Phone</dt>
          <dd />
        </div>
        <div>
          <dt>Education</dt>
          <dd>MS Electrical Engineering, University of Illinois Urbana-Champaign; BS Physics, Universidad de Buenos Aires</dd>
        </div>
        <div>
          <dt>LinkedIn</dt>
          <dd>
            <Link href="https://www.linkedin.com/in/ana-ruiz-asic-design" target="_blank" rel="noopener noreferrer">
              linkedin.com/in/ana-ruiz-asic-design <LinkExternalIcon />
            </Link>
          </dd>
        </div>
        <div>
          <dt>Added by</dt>
          <dd>Sam Lee</dd>
        </div>
      </DescriptionList>
    </div>
  );
}

Stacked

Orbit's submitted referral: long questions above long answers. Line breaks in an answer stay.

How do you know this person?: We worked together for three years on the memory controller team at a previous job.
Why are they a strong fit for this role?: She owned timing closure for two tape-outs and led the bring-up of the first silicon. She also wrote most of the team's verification plan.
Anything else we should know?

import { DescriptionList } from "@etched/reticle/description-list";

export function Stacked() {
  return (
    <div style={{ maxInlineSize: "36rem" }}>
      <DescriptionList>
        <div>
          <dt>How do you know this person?</dt>
          <dd>We worked together for three years on the memory controller team at a previous job.</dd>
        </div>
        <div>
          <dt>Why are they a strong fit for this role?</dt>
          <dd>
            {"She owned timing closure for two tape-outs and led the bring-up of the first silicon.\nShe also wrote most of the team's verification plan."}
          </dd>
        </div>
        <div>
          <dt>Anything else we should know?</dt>
          <dd />
        </div>
      </DescriptionList>
    </div>
  );
}

Columns stack when narrow

The same list at 24 rem and at 12 rem. Below 14 rem, a columns list stacks. Pairs need no div, and a label can have two values.

Schedule: Every 10 days
Delivery: Candidate’s hiring Slack channel; Owner’s email
Ends: When the status changes

Schedule: Every 10 days
Delivery: Candidate’s hiring Slack channel; Owner’s email
Ends: When the status changes

import type { CSSProperties } from "react";
import { DescriptionList } from "@etched/reticle/description-list";

/** A panel around a list, like Orbit's side cards. The app sets its width. */
const panel = (inlineSize: string): CSSProperties => ({ boxSizing: "border-box", inlineSize, padding: "var(--et-space-4)" });

export function ColumnsStackWhenNarrow() {
  const schedule = (
    <DescriptionList layout="columns">
      <dt>Schedule</dt>
      <dd>Every 10 days</dd>
      <dt>Delivery</dt>
      <dd>Candidate’s hiring Slack channel</dd>
      <dd>Owner’s email</dd>
      <dt>Ends</dt>
      <dd>When the status changes</dd>
    </DescriptionList>
  );

  return (
    <div className="row" style={{ alignItems: "flex-start" }}>
      <div className="card" style={panel("24rem")}>
        {schedule}
      </div>
      <div className="card" style={panel("12rem")}>
        {schedule}
      </div>
    </div>
  );
}

API reference

Prop	Type	Default	Description
layout	"stacked" \| "columns"	"stacked"
actions	ReactNode	–	Controls at the top end, beside the list, such as an Edit button. They come before the list in focus and reading order.
children *	ReactNode	–	The pairs, as native `dt` and `dd` elements. Put each pair in a `div` or not; a label can have more than one value.