A NSW Government website
NSW GovernmentNSW GovernmentEmail Toolkit

List

A bulleted or numbered list, with items nested one level under it. Every spacing it draws comes from list in lib/list.ts, and its text from the type scale, as <NswText>'s does; resolveList validates the props.

Examples

List

A bulleted list with items nested under some, in three text colours.

54.7 KB built. Open the built email (opens in a new tab)

const items: readonly ListItem[] = [
  'First top-level item',
  { value: 'Second item', nestedItems: ['Nested A', 'Nested B'] },
  { value: 'Third item', nestedItems: ['Nested 1', 'Nested 2'] },
  'Fourth item',
  'Fifth item',
  { value: 'Sixth item', nestedItems: ['Nested 1', 'Nested 2', 'Nested 3'] },
]

const colors: readonly ColorValue[] = ['grey-800', 'primary-800', 'accent-800'];

<NswLayout title='List'>
  {colors.map((color) => (
    <Fragment key={color}>
      <NswColumns padding={false} background='white'>
        <NswColumn>
          <NswSpacer height={16} />
        </NswColumn>
      </NswColumns>
      <NswColumns background='white'>
        <NswColumn>
          <NswList items={items} color={color} />
        </NswColumn>
      </NswColumns>
      <NswColumns padding={false} background='white'>
        <NswColumn>
          <NswSpacer height={8} />
        </NswColumn>
      </NswColumns>
      <NswColumns padding={false} background='grey-100'>
        <NswColumn>
          <NswSpacer height={24} />
        </NswColumn>
      </NswColumns>
    </Fragment>
  ))}
</NswLayout>

Props

Props of NswList, read from the component
PropTypeDefaultDescription
backgroundColorValue—A fill behind the list: a theme colour name or a hex literal, or 'transparent' for none; anything else throws (see resolveColor). (Legacy bgcolor.)
devicesDevices—Which devices show the list: left out, every device; desktop hides it on a phone; mobile shows it on a phone only. A phone-only list is hidden inline and from Windows Outlook with mso-hide and the <!--[if !mso]> comments around it (see src/lib/devices.ts), as <NswText devices> is.
defaultsTextDefaults—The email's text settings (<NswLayout text>), handed down by the layout to every text-bearing primitive beneath it; the block's own props win. The walk reaches the package's own primitives wherever they stand in the tree, in children and in props that hold elements, but it cannot see inside a component of your own: give such a component the same settings you gave the layout (text, checked by resolveTextDefaults) as a prop, and hand them to the primitives it renders.
items (required)readonly ListItem[]—The items, in order: each its content (text, or inline markup such as a link), or { value, nestedItems } for an item with items nested under it, one level deep. Required, with at least one item.
orderedbooleanfalseNumber the items (1., 2., …) rather than bullet them. Nested items keep their en dash. Default false.
bulletPaddingnumberlist.bulletPaddingThe space between a marker and its item, in whole px. Nested items are indented by it too. Default list.bulletPadding.
typeTypeScaleNamebodyThe step of the NSW type scale the text is drawn in: display-lg, display-md, display-sm, headline-lg, headline-md, headline-sm, body-lg, body, body-sm, body-xs, label or label-sm. Every other prop overrides one value of that step. Default body.
sizenumberthe type step'sFont size in whole px, above 0. Default the type step's.
weightnumberthe type step'sFont weight, a multiple of 100 from 100 to 900. Default the type step's.
lineHeightnumberthe type step'sLine height in whole px (24), written in pixels because Windows Outlook ignores a unitless one. Default the type step's.
letterSpacingnumber | 'normal'the type step'sLetter spacing in px (-0.5), or 'normal'. Default the type step's.
colorColorValuethe type step's, primary-800 for display, headline and label, grey-800 otherwiseThe text colour: a theme colour name (grey-800) or a hex literal (#22272b); 'transparent' and anything else throws (see resolveColor). Default the type step's, primary-800 for display, headline and label, grey-800 otherwise.
family'sans' | 'serif' | 'mono'sansThe face: sans (Public Sans), serif (Merriweather) or mono (the platform monospace). Windows Outlook loads no web font and uses the first installed face in the family's stack (Arial, Georgia or Merriweather, Consolas or Roboto Mono). Default sans.
fontStyle'normal' | 'italic'normalitalic or normal. Default normal.
align'left' | 'center' | 'right'leftHorizontal alignment of the text. Default left.
valign'top' | 'middle' | 'bottom'topVertical alignment of the text in its cell (the cell's valign attribute), for a block beside a taller one. Default top.