Alert
In-page alerts are non-intrusive notifications within a webpage, providing users with timely information or feedback without disrupting their experience.
Installation
npm install --save @godaddy/antaresProps
emphasis?AlertEmphasis | undefined'info'Describes the importance or nature of the message.
title?string | undefined—Sets title text for the alert.
children?React.ReactNode—Optional body text.
actions?React.ReactNode—Adds action button(s).
onClose?(() => void) | undefined—Callback fired when the dismiss button is clicked. When provided, renders a dismiss (X) icon button.
ariaLabels?{ close?: string; } | undefined—Screen reader labels for sub-elements.
className?string | undefined—Additional CSS class names applied to the root element.
ref?React.Ref<HTMLDivElement> | undefined—Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
inputMode?"search" | "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | undefined—Hints at the type of data that might be entered by the user while editing the element or its contents
is?string | undefined—Specify that a standard HTML element should behave like a defined custom built-in element
Examples
Basic Usage
A minimal alert with a title and body text.
import { Alert, type AlertProps } from '@godaddy/antares';export function DefaultExample(props: Partial<AlertProps>) { return ( <Alert emphasis="info" title="Your domain is ready" {...props}> You can now start building your website. </Alert> );}Emphasis Variants
All 7 emphasis categories. Each variant carries a distinct visual accent and semantic icon so the type of message is never communicated by color alone.
import { Alert } from '@godaddy/antares';const emphases = ['critical', 'warning', 'success', 'info', 'highlight', 'premium', 'internal'] as const;export function EmphasesExample() { return ( <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}> {emphases.map((emphasis) => ( <Alert key={emphasis} emphasis={emphasis} title={`This is a ${emphasis} alert`}> Description for the {emphasis} emphasis variant. </Alert> ))} </div> );}Dismissible
When an onClose callback is provided, a dismiss button is rendered. The component does not manage its own visibility — the parent is responsible for unmounting or hiding the alert when onClose fires.
import { Alert, type AlertProps, Button } from '@godaddy/antares';import { useState } from 'react';export function DismissibleExample(props?: Partial<AlertProps>) { const [visible, setVisible] = useState(true); if (!visible) return <Button onPress={() => setVisible(true)}>Show alert</Button>; return ( <Alert emphasis="success" title="Your account's been verified" onClose={() => setVisible(false)} {...props}> We've successfully verified your identity. </Alert> );}With Action
Pass a Button to the actions slot to give the user a clear path to resolve the alert.
import { Alert, Button } from '@godaddy/antares';export function WithActionExample() { return ( <Alert emphasis="warning" title="Your payment method is expiring" actions={ <Button variant="secondary" size="sm"> Update Payment Method </Button> } onClose={() => undefined} > Please update your payment method before it expires. </Alert> );}Accessibility
Keyboard
| Key | Description |
|---|---|
Tab | Moves focus to the dismiss button or action button |
Space / Enter | Activates the focused button |
Screen readers
The alert container uses role="alert", which creates an ARIA live region. When an alert is rendered or its content changes, screen readers announce the message automatically — the user does not need to navigate to the alert to hear it.
Dismiss button label
The dismiss button defaults to aria-label="Close". Override it via ariaLabels={{ close: '...' }} to provide more specific context for screen readers (e.g. "Dismiss payment warning"). This is especially useful when multiple alerts are visible at the same time.
Best Practices
- Write alert content from the user's perspective: describe what happened and what they can do next, not the underlying technical error.
- Use
criticalonly when the user truly cannot continue without resolving the issue. Overusing it reduces its impact. - Always provide a
titlewhen the alert includes a dismiss button — it improves the reading experience for screen reader users. - When using
actions, prefersecondaryortertiaryButton variants. Avoid placing a primary action inside an alert. - Do not stack multiple alerts of the same emphasis; consolidate the message into a single alert.