Button

A call-to-action link drawn as a button, in one of the NSW colour tones, solid or outlined. Every number it draws comes from button and every colour from the tone, both in lib/button.ts; resolveButton validates the props.

Examples

Button

Every tone, solid and outline, then the button left, centred and right.

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

const href = 'https://email.designsystem.nsw.gov.au'

const tones: readonly ButtonTone[] = ['primary', 'secondary', 'tertiary', 'accent', 'grey']

const examples: ReadonlyArray<{ variant: ButtonVariant; tone: ButtonTone; align: Align }> = [
  ...tones.map((tone) => ({ variant: 'solid' as const, tone, align: 'left' as const })),
  ...tones.map((tone) => ({ variant: 'outline' as const, tone, align: 'left' as const })),
  ...(['left', 'center', 'right'] as const).map((align) => ({
    variant: 'solid' as const,
    tone: 'primary' as const,
    align,
  })),
];

<NswLayout title='Button'>
  {examples.map(({ variant, tone, align }, i) => {
    const surface: ColorValue = tone === 'secondary' ? 'primary-800' : 'white'
    return (
      <Fragment key={i}>
        <NswColumns padding={false} background={surface}>
          <NswColumn>
            <NswSpacer height={16} />
          </NswColumn>
        </NswColumns>
        <NswColumns background={surface}>
          <NswColumn>
            <NswButton href={href} variant={variant} tone={tone} align={align}>
              Get started
            </NswButton>
          </NswColumn>
        </NswColumns>
        <NswColumns padding={false} background={surface}>
          <NswColumn>
            <NswSpacer height={16} />
          </NswColumn>
        </NswColumns>
        <NswSection background='grey-100' padding={0}>
          <NswColumns padding={false} background='grey-100'>
            <NswColumn>
              <NswSpacer height={24} />
            </NswColumn>
          </NswColumns>
        </NswSection>
      </Fragment>
    )
  })}
</NswLayout>

Props

Props of NswButton, read from the component
Prop	Type	Default	Description
`href` (required)	`string`	—	Where the button links to. Required; an empty link throws.
`mobileClass`	`string`	`mobile-<align>` (`mobile-left`, `mobile-center`, `mobile-right`), which keeps the button where it sits on a phone	Mobile utility class(es) on the button's wrapper, for a document's own `@media` rule. Default `mobile-<align>` (`mobile-left`, `mobile-center`, `mobile-right`), which keeps the button where it sits on a phone. (Legacy `mobileClass`.)
`devices`	`Devices`	—	Which devices show the button: left out, every device; `desktop` hides it on a phone (`hide-on-mobile`); `mobile` shows it on a phone only — hidden inline everywhere else, shown by the document's `.show-on-mobile` rule, and kept from Windows Outlook, which reads no `@media`, by `mso-hide: all` and the `<!--[if !mso]>` comments around it (see `src/lib/devices.ts`). On the wrapper, which a phone-only button also marks `show-on-mobile-block`: the document's rule shows it as a block again, not a table.
`defaults`	`TextDefaults`	—	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.
`variant`	`ButtonVariant`	`solid`	`solid` fills the button with its colour; `outline` draws only the border and label in it. Default `solid`.
`tone`	`ButtonTone`	`primary`	The colour tone: `primary`, `secondary` (a light fill for dark surfaces), `tertiary`, `accent` or `grey`. Sets the fill, label and hover colours. Default `primary`.
`align`	`Align`	`left`	Where the button sits in its column. Default `left`.
`width`	`number`	the label's own width plus padding	A fixed width in whole px, the label centred inside it. Default the label's own width plus padding.
`background`	`ColorValue`	the tone's	The button's colour, overriding the tone's: the fill of a `solid` button, the border and label of an `outline` one. A theme colour name or a hex literal; `'transparent'` and anything else throws (see `resolveColor`). Setting it drops the tone's hover colours. Default the tone's.
`color`	`ColorValue`	the tone's label colour (`white` for most tones), or the button's colour for `outline`	The label colour, overriding the tone's. A theme colour name or a hex literal; `'transparent'` and anything else throws. Setting it drops the tone's hover colours. Default the tone's label colour (`white` for most tones), or the button's colour for `outline`.