Skip to main content
U.S. Flag

An official website of the United States government

Alert

Alerts give feedback to users, provide critical information, and/or offer key supplementary details about a task.

Examples

Informational (Default)

Loading

Error

Loading

Warning

Loading

Success

Loading

Lightweight

Loading

Code

React

React Properties Documentation
NameTypeDefaultDescription
alertRef(...args: any[]) => anyAccess a reference to the alert div element
autoFocusbooleanSets the focus on Alert during the first mount
childrenReactNodeThe alert's body content
classNamestring
headingstringText for the alert heading
headingIdstringOptional id used to link the aria-labelledby attribute to the heading. If not provided, a unique id will be automatically generated and used.
headingLevelAlertHeadingLevel2Heading type to override default <h2>.
hideIconbooleanBoolean to hide the Alert icon
roleAlertRoleregionARIA role, defaults to 'region'
weight"lightweight"A string corresponding to the Alert weight classes (lightweight)
variationAlertVariationA string corresponding to the Alert variation classes (error, warn, success)
analyticsbooleanAnalytics events tracking is enabled by default. Set this value to false to disable tracking for this component instance.
analyticsLabelOverridestringAn override for the dynamic content sent to analytics services. By default this content comes from the heading. In cases where this component’s heading may contain sensitive information, use this prop to override what is sent to analytics.
analyticsEventTypeOverridestringIf you need the event_type to be overridden for your use case, you can provide an alternate string here. Suggested values can be found in the EventType enum.
onAnalyticsEvent(event: AnalyticsEvent) => voidOptional callback that will intercept analytics events for this component. If none is specified, the design system will use the default analytics function, which can be overwritten globally with setDefaultAnalyticsFunction.
This component passes any additional props to its underlying <div> element as attributes. See the corresponding MDN documentation for <div> for a list of valid attributes.

Styles

The following CSS variables can be overridden to customize Alert components:

CSS variables for alert
VariableDefault Core Theme Value
--alert__background-colorhex value: #e6f9fd--color-primary-alt-lightest
--alert__background-color--errorhex value: #fce8ec--color-error-lightest
--alert__background-color--lightweighthex value: #ffffff--color-white
--alert__background-color--successhex value: #e7f3e7--color-green-lightest
--alert__background-color--warnhex value: #fef9e9--color-gold-lightest
--alert__border-left-colorhex value: #02bfe7--color-focus-inverse
--alert__border-color--errorhex value: #e31c3d--color-error
--alert__border-color--successhex value: #12890e--color-green
--alert__border-color--warnhex value: #f8c41f--color-gold
--alert__font-colorhex value: #262626--color-base
--alert__icon-size40px
--alert__padding16px
--alert-bar__width8px
--alert-link__font-colorhex value: #004f84--color-primary-darker
--alert-link__font-color--hoverhex value: #00395e--color-background-inverse
--alert-link__font-color--focushex value: #00395e--color-background-inverse
--alert-link__font-color--activehex value: #00395e--color-background-inverse

Analytics

This component has analytics tracking available. Please see our developer documentation about using analytics in the design system.

Guidance

Usage

  • Don’t overdo it — too many notifications will either overwhelm or annoy the user and are likely to be ignored.
  • Write the message in concise, human readable language; avoid jargon and computer code.
  • Don’t include notifications that aren’t related to the user’s current goal.
  • When the user is required to do something in response to an alert, let them know what they need to do and make that task as easy as possible.
  • Be mindful of other elements on the page that may compete for the user’s attention.

When to use

  • As a validation message that alerts someone that they just did something that needs to be corrected or as confirmation that a task was completed successfully.
  • As a callout or notification for important or timely information. This includes errors, warnings, and general information.
  • Drawing focus to an error or an incomplete task by prompting the user to review or take other action.
  • Confirming the successful competition of a task.
  • Providing key supplementary or contextual information to support the successful completion of tasks or aid overall comprehension.

When to consider alternatives

  • On long forms, always include in-line validation in addition to any error messages that appear at the top of the form. When possible, simplify forms by rewriting and where possible, splitting long forms across multiple pages
  • If an action will result in destroying a user’s work (for example, deleting an application) use a more intrusive pattern, such as a confirmation modal dialogue, to allow the user to confirm that this is what they want.
  • When you need to display content that isn't related to the user’s current goal.

When the alert is for an error:

  • Be polite in error messages — don’t place blame on the user.
  • Users generally won’t read documentation but will read a message that helps them resolve an error; include some educational material in your error message.
  • If the error relates to specific text fields, give these fields an error state as well.

Display & behavior

  • Alerts are static and shouldn't be associated with a timer or dismiss button.
  • Can be displayed statically on page load or dynamically loaded.
  • When the user is required to do something in response to an alert, let them know what they need to do and make that task as easy as possible.

Accessibility

  • Use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message that is not interactive. If the message is interactive, use the role="alertdialog" instead.
  • Consider putting the alert inside a div with aria-live="polite" and aria-relevant="additions removals". These ARIA attributes ensure screen readers will announce alerts that have been added or updated dynamically.
  • If you choose to shift focus to the Alert, be mindful that using other techniques like role="alert", and aria-live="polite" will cause some browser and screen reader combinations to read out the content more than once. Typically, shifting focus alone will be enough to alert screen readers of the content.
  • Do not visually hide alert messages on the page and then make them visible when they are needed. Users of older assistive technologies may still be able to perceive the alert messages even if they are not currently applicable.

Learn more

Component maturity

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Not applicable

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete