Alert

GradeTested

UsageCopy Anchor Link

import { Alert, AlertAction, AlertDescription, AlertTitle, Button } from "@cadence-clinical/ui";

<Alert variant="critical">
  <AlertTitle>The observation was not saved</AlertTitle>
  <AlertDescription>The connection dropped before it was sent.</AlertDescription>
  <AlertAction>
    <Button size="sm" variant="outline" onClick={retry}>
      Try again
    </Button>
  </AlertAction>
</Alert>;

Say what happened in AlertTitle and what to do next in AlertDescription. AlertAction holds a button or two. Every part is optional.

Alert follows the shadcn Alert and keeps its part names. For a status on a short label, use a Badge. For a message about one form control, use the error of a Field.

StatusCopy Anchor Link

variant takes default and the four statuses: critical, warning, success and info.

A status is never shown by colour alone. Each status variant carries four things:

• a tinted fill and its border token, which gives a pale fill an edge on a white page
• an icon whose outline differs from the others: an octagon, a triangle, a ticked circle and a circled "i"
• the status in words for a screen reader, in place of the icon: "Critical", "Warning", "Success" or "Information"
• the title in the status's text colour, and the message in the page's text colour at full contrast

An alert shows the status it is given. It never works one out: what counts as critical is decided outside Cadence, as Clinical safety explains. The status colours are the same in every theme.

Change the iconCopy Anchor Link

Pass icon to replace a variant's icon. A status variant always has one, and still says its status in words. Pass iconLabel to change those words, for example into another language:

<Alert variant="critical" icon={<WifiOff />} iconLabel="Offline">
  <AlertTitle>Changes are kept on this device</AlertTitle>
</Alert>

A quieter alertCopy Anchor Link

emphasis="edge" keeps the fill, the icon and the words, and turns the outline into a bar down the leading edge. Use it for a note beside what it is about, such as this one, rather than for something that has just happened:

<Alert variant="warning" emphasis="edge" role="note">
  <AlertTitle>Grades</AlertTitle>
  <AlertDescription>No component is above Tested yet.</AlertDescription>
</Alert>

The bar is the status's own border token, so the status is still marked by more than its fill. Without a status, the bar is the page's rule on the muted fill. Its padding is even on all four sides, where an outlined alert is tighter above and below.

Every callout on this site is one of these, so the documentation is built from what it documents.

When it is announcedCopy Anchor Link

An alert that appears in response to something is announced by a screen reader. critical and warning have role="alert", which interrupts. The other variants have role="status", which waits until the screen reader is idle. For a short message that goes away on its own, such as a record saved, use a Toast. An alert stays where it is.

Those roles are for a message that appears. A message that is on the page from the start is not an announcement, so give it a role that suits it. The GOV.UK notification banner makes a standing message a region named by its title, which a screen reader can move to:

<Alert variant="warning" role="region" aria-labelledby="training-title">
  <AlertTitle id="training-title">This is a training environment</AlertTitle>
  <AlertDescription>Nothing entered here reaches a real record.</AlertDescription>
</Alert>

What Cadence changesCopy Anchor Link

• Four statuses with their tokens, where shadcn has default and destructive. The shadcn destructive is critical here.
• The icon is a prop, and a status always has one. In shadcn the icon is an svg you place as a child, so a status alert can be left with colour only. Here each status supplies its icon and its word.
• The message is at full contrast. shadcn sets it in muted text, or in the destructive colour at 90%. The contrast of the page's text colour on each status fill is asserted in the @cadence-clinical/tokens test suite.
• The role follows the urgency. shadcn gives every alert role="alert".
• The action has its own column. shadcn positions it over the corner and reserves a fixed 72px for it, which a wider button overruns. Here it takes the width it needs, and drops under the words when the alert is narrower than 24rem. The alert measures itself and not the screen, so this holds in a side panel.
• Padding and text follow the density, and long words wrap.
• A quieter emphasis, for a note on a page rather than something that has just happened. shadcn has one weight of alert.

PropsCopy Anchor Link