Alert

01Preview

Change the controls to try every supported combination. The preview uses role="none" so changing controls doesn't announce anything.

import { Alert, AlertAction } from '@nuton/ui'

<Alert
  status="information"
  size="large"
  title="What’s a space?"
  description="Space keeps chats, documents, and videos in one place for better organization and efficient learning."
  dismissible
  actions={<>
    <AlertAction onClick={openSpaces}>Open spaces</AlertAction>
    <AlertAction href="/help/spaces">Learn more</AlertAction>
  </>}
/>

02Installation

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

03Usage

import { Alert } from '@nuton/ui'

<Alert
  title="What’s a space?"
  description="Space keeps chats, documents, and videos in one place for better organization and efficient learning."
/>

• Place the alert next to what it's about: at the top of a form, a lesson or a settings group.
• Keep the title short. Put the detail in the description, and one or two next steps in actions as AlertActions.
• Pick the size by content: xsmall or small for one line (a banner, a toast), large when there's a description. Without size, an alert with a description is large and one without is small.
• Pick the appearance by emphasis: filled for the strongest, light and lighter for most in-page alerts, stroke on tinted surfaces or for toasts.
• Pick the status by meaning, not colour: error for something that failed, warning for a risk, success for a finished task, information or neutral for help.
• For a short confirmation after an action, use a Toast. For a decision that blocks the page, use a Modal.

04Variants and sizes

Five statuses (rows) in four appearances (columns), in three sizes. This is the owner's reference matrix, built with Nuton tokens.

X-small

One line, 32 tall: 16px icon, Paragraph/X Small text, Label/X Small action, radius 8.

<Alert size="xsmall" status="error" appearance="filled" title="Insert your alert title here!"
  actions={<AlertAction>Button</AlertAction>} dismissible />

Small

One line, 36 tall: 20px icon, Paragraph/Small text, Label/Small action, radius 8.

<Alert size="small" status="success" appearance="light" title="Insert your alert title here!"
  actions={<AlertAction>Button</AlertAction>} dismissible />

Large

Title, a description and actions under the text with a dot between them; padding 14, radius 12, close at the top end.

<Alert
  status="warning"
  appearance="lighter"
  title="Insert your alert title here!"
  description="Insert the alert description here. It would look better as two lines of text."
  actions={<>
    <AlertAction onClick={…}>Button</AlertAction>
    <AlertAction href="/help">Learn more</AlertAction>
  </>}
  dismissible
/>

Examples on this page pass role="none" so the docs don't announce them on load. In your app, leave the default role.

Colours and contrast

Every text pair is at least 4.5:1 and every icon at least 3:1. Where the reference colours fell short, code uses the next step of the same hue.

Content options

<Alert description="Only the description, no title." />
<Alert icon={<RiSparklingLine />} title="AI Tutor tip" description="Ask for a worked example of any formula." />

05States and interactions

Dismissing and focus

When the close button is pressed the alert disappears and focus would be lost. Use onDismiss to move focus somewhere sensible, such as the section heading.

const headingRef = useRef<HTMLHeadingElement>(null)

<h3 ref={headingRef} tabIndex={-1}>Biology 101</h3>
<Alert
  status="information"
  title="New lessons added"
  description="Two lessons on cell respiration are ready."
  dismissible
  onDismiss={() => headingRef.current?.focus()}
/>

State tokens

Set on .nu-alert. Each status sets --nu-alert-strong, --nu-alert-light and --nu-alert-lighter; each appearance maps them to --nu-alert-bg, --nu-alert-border, --nu-alert-fg, --nu-alert-muted, --nu-alert-icon and --nu-alert-close; each size sets --nu-alert-radius, --nu-alert-pad-block, --nu-alert-pad-inline, --nu-alert-gap and the icon sizes.

06Composition examples

Error after submit

An error alert at the top of a form uses role="alert" by default, so screen readers announce it straight away.

{error ? (
  <Alert status="error" title="We couldn’t save the lesson"
    description="Check your connection and try again. Your draft is kept on this device." />
) : null}
<Button type="submit">Save lesson</Button>

07API reference

Props

Accessibility

You must: write a title or description that makes sense alone, and move focus when a dismissed alert held it.

Figma mapping

08Guidelines and related components

Do and don't

Related components

• ToastThe same anatomy as a brief, floating confirmation.
• ModalFor decisions that must be made before going on.
• Status BadgeA compact status on an item, using the same icons.