Alert
Communicates a contextual, timely system message that needs a user's attention.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import {
GlAlert,
GlAlertActions,
GlAlertDescription,
} from "gitlab-ui-react/alert";
import { GlButton } from "gitlab-ui-react/button";<GlAlert dismissible={false}>
<GlAlertDescription>Your preferences were updated.</GlAlertDescription>
<GlAlertActions>
<GlButton>Review changes</GlButton>
</GlAlertActions>
</GlAlert>Default
Use an alert for a dynamic system condition in the current context. Start with a non-dismissible alert when the message must remain available until its underlying condition is resolved.
import {
GlAlert,
GlAlertDescription,
} from "gitlab-ui-react/alert";
export default function AlertExample() {
return (
<GlAlert dismissible={false}>
<GlAlertDescription>
Your preferences were updated and will apply to new projects.
</GlAlertDescription>
</GlAlert>
);
}
Dismissible alerts
Allow dismissal only when the message can safely be removed. GlAlert does not hide itself, so the parent must update its state and remove the alert when onDismiss runs.
import { useState } from "react";
import {
GlAlert,
GlAlertDescription,
} from "gitlab-ui-react/alert";
import { GlButton } from "gitlab-ui-react/button";
export default function AlertDismissibleExample() {
const [visible, setVisible] = useState(true);
if(!visible) {
return <GlButton onClick={() => setVisible(true)}>Show alert again</GlButton>;
}
return (
<GlAlert onDismiss={() => setVisible(false)}>
<GlAlertDescription>
Your preferences were updated and will apply to new projects.
</GlAlertDescription>
</GlAlert>
);
}
Variants
Choose a variant for the message’s meaning, not merely its visual emphasis. Use danger for critical problems, warning for risks, success for outcomes completed elsewhere, information for changing status, and tip for useful product guidance.
Deployment failed
Storage is almost full
Import complete
Pipeline is running
Save time with templates
import {
GlAlert,
GlAlertDescription,
} from "gitlab-ui-react/alert";
export default function AlertVariantsExample() {
return (
<div className="grid gap-3">
<GlAlert dismissible={false} title="Deployment failed" variant="danger">
<GlAlertDescription>Resolve the job errors, then run the deployment again.</GlAlertDescription>
</GlAlert>
<GlAlert dismissible={false} title="Storage is almost full" variant="warning">
<GlAlertDescription>Free some space before the storage limit is reached.</GlAlertDescription>
</GlAlert>
<GlAlert dismissible={false} title="Import complete" variant="success">
<GlAlertDescription>The project is now ready to use.</GlAlertDescription>
</GlAlert>
<GlAlert dismissible={false} title="Pipeline is running" variant="info">
<GlAlertDescription>This page updates as jobs finish.</GlAlertDescription>
</GlAlert>
<GlAlert dismissible={false} title="Save time with templates" variant="tip">
<GlAlertDescription>Start from a template when creating a new issue.</GlAlertDescription>
</GlAlert>
</div>
);
}
Titles and actions
Add a short title when it helps users identify what triggered the alert. Put up to two explicit recovery or continuation controls in GlAlertActions; use a confirm primary action and a default secondary action.
Pipeline could not start
import {
GlAlert,
GlAlertActions,
GlAlertDescription,
} from "gitlab-ui-react/alert";
import { GlButton } from "gitlab-ui-react/button";
export default function AlertActionsExample() {
return (
<GlAlert dismissible={false} title="Pipeline could not start" variant="danger">
<GlAlertDescription>
Check the pipeline configuration, then try again.
</GlAlertDescription>
<GlAlertActions>
<GlButton variant="confirm">Retry</GlButton>
<GlButton category="secondary">View details</GlButton>
</GlAlertActions>
</GlAlert>
);
}
Accessibility
- Use alerts for dynamic notifications, not permanently visible documentation or contextual help.
- Danger, warning, and success variants use
role="alert"; information and tip variants userole="status". The defaultaria-live="polite"avoids interrupting current screen-reader speech. - Set
politeness="assertive"only for critical, time-sensitive messages. For a message that requires action, place it near the related content and move focus to the alert through its ref when appropriate. - Choose
headerLevelto keep the title in the page’s logical heading hierarchy. - Provide a localized
dismissLabel, handleonDismiss, and offer dismissal only when the message can safely be removed. - Set
aria-atomic="true"when assistive technology should announce the entire message after an update.
API
These are the component-specific props. GlAlert, GlAlertDescription, and GlAlertActions also forward supported div attributes and refs.
GlAlert
| Prop | Description | Default |
|---|---|---|
variant |
Sets the semantic style to danger, warning, success, info, or tip. |
"info" |
title |
Adds a short heading before the alert content. | — |
headerLevel |
Sets the title heading level from 1 through 6. |
2 |
dismissible |
Shows the dismiss button; visibility remains controlled by the parent. | true |
dismissLabel |
Sets the dismiss button’s accessible label. | "Dismiss" |
onDismiss |
Runs when the dismiss button is activated. | — |
politeness |
Sets aria-live to polite, assertive, or off. |
"polite" |
sticky |
Keeps the alert at the top of its scrolling container. Use only one sticky alert at a time. | false |
children |
Alert content, normally composed with the description and actions helpers. | — |
GlAlertDescription
Provides the standard message layout and accepts children plus supported div attributes.
GlAlertActions
Lays out custom action controls and accepts children plus supported div attributes.