> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Alert

> An Alert communicates information about a specific user action on a page. It lives inside the page and appears contextually within a task flow and disappears when the user closes it, resolves the issue, or (if required by feature) navigates away from the page.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-alert--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--basic&viewMode=story&globals=theme:light" title="Alert basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* **For contextual guidance or inline recommendations:** When users need clarification or additional context about their current task or when suggesting next steps within the workflow.

*Example:* Displaying an Alert within a symbols or mapping list to help explain how a user can link or unlink assets.

* **To communicate warnings or issues:** When an action requires attention, but isn't blocking progress or the user can resolve the issue in a separate context.

*Example:* Alerting the user that transformations have failed and user action is required to troubleshoot the problem.

* **When actions need to be taken:** If the user should resolve an issue directly within the Alert.

*Example:* Re-establishing a failed connection.

## When to use something else

* **When the message is critical and must be acknowledged:** Use a [Dialog](/cdf/aura/primitives/dialog) instead to capture user attention.
* **For system-wide notifications or alerts:** Use a [Sonner](/cdf/aura/primitives/sonner), [Banner](/cdf/aura/primitives/banner), or the notification center.
* **For immediate feedback such as success or failure of an operation when the user does not need to be given a lot of details:** Use a [Sonner](/cdf/aura/primitives/sonner) and allow them to try again.
* **When the errors prevent the user from continuing such as "page not found", "no access" or server error:** Use a full page [Empty state](/cdf/aura/primitives/empty-state).
* **If the information is not tied to a specific user action or context:** Use [Tooltip](/cdf/aura/primitives/tooltip)s or inline text for passive guidance.
* **If a form field requires validation:** Use inline validation messages provided with [Combobox](/cdf/aura/primitives/combobox), [Input](/cdf/aura/primitives/input), [Select](/cdf/aura/primitives/select), or [Textarea](/cdf/aura/primitives/textarea).

## Dos and don'ts

* **Do** use action [Button](/cdf/aura/primitives/button)s when the action is specific to the message and will resolve (dismiss) it.
* **Do** consider other methods for feedback before using an Alert, such as inline validation on forms. Avoid mixing multiple feedback states as this becomes confusing or frustrating to a user.
* **Do** use the correct status type depending on the alert. If none exists, use a neutral or info type.
* **Do** place Alerts near the content they relate to and set the width.
* **Do** use a strip style Alert if the content must span the full page.
* **Don't** use action [Button](/cdf/aura/primitives/button)s for unrelated activities or activities that don't resolve the Alert.

## Placement

* Always align the edge of the Alert relative to the surrounding content. Alerts should never be flush to a container's divider.
* Use the card style Alert when content needs to wrap and applies to a small container.
* Use the strip style Alert when content is short and applies to a larger container.

## Behavior

* Inline to the page: it does not block the full viewport like a [Dialog](/cdf/aura/primitives/dialog) or [Alert dialog](/cdf/aura/primitives/alert-dialog).
* Dismissal removes the alert from the layout (or hides it) per variant; optional actions should complete or dismiss the alert in one clear step.
* If the alert includes focusable controls, manage focus appropriately; otherwise it typically does not trap focus.
* Product rules decide whether dismissed state persists across navigation or sessions.

## Often used with

[Button](/cdf/aura/primitives/button) for dismiss or fix-it actions; optional inline icon; sits above related content, not inside unrelated [Card](/cdf/aura/primitives/card) chrome unless scoped to that region.

## Accessibility

* ARIA roles: Use `role="alert"` (assertive) for urgent visual notifications requiring immediate user attention, and `role="status"` (polite) for routine status changes.
* Color redundancy: Never rely on color alone (e.g., green/red fills) to distinguish success from error states—always pair with explicit icons and text prefixes like "Error:" or "Success:".
* Contrast: Maintain a minimum text-to-background contrast ratio of 4.5:1 for light and dark variant alerts.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--accessibility" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--accessibility&viewMode=story&globals=theme:light" title="Alert accessibility story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Dismissible

Use a dismissible Alert when the message is informational or resolved by the user, and they should be able to close it manually without taking further action.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--dismissible" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--dismissible&viewMode=story&globals=theme:light" title="Alert dismissible story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Secondary

Use the secondary Alert variant for lower-emphasis guidance that supplements the main content without drawing as much attention as info, warning, or error styles.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--secondary" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--secondary&viewMode=story&globals=theme:light" title="Alert secondary story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Neutral card type

Use the neutral card-type Alert when context applies to a smaller container and the message may wrap across multiple lines—for example, within a card or narrow panel.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--neutral-card-type" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--neutral-card-type&viewMode=story&globals=theme:light" title="Alert neutral card type story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Info strip type

Use the info strip-type Alert for short, inline messages that span a wider container, such as contextual tips above a data table or form section.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--info-strip-type" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--info-strip-type&viewMode=story&globals=theme:light" title="Alert info strip type story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Warning

Use a warning Alert when an action or state requires attention but does not block progress—for example, a failed background job that the user can troubleshoot later.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--warning" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--warning&viewMode=story&globals=theme:light" title="Alert warning story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Error alert

Use an error Alert when something has failed and the user must take action or acknowledge the problem before continuing—for example, a connection failure that blocks the current task.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--error-alert" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--error-alert&viewMode=story&globals=theme:light" title="Alert error alert story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### All variants

Reference this example to compare all Alert visual variants side by side when choosing the appropriate emphasis, layout, and semantic color for a given message.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--all-variants" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--all-variants&viewMode=story&globals=theme:light" title="Alert all variants story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Description only

Use a description-only Alert when a short message is sufficient and a title would add unnecessary redundancy—for example, a single-line clarification within a workflow.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--description-only" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--description-only&viewMode=story&globals=theme:light" title="Alert description only story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Custom icon

Use a custom icon in an Alert when the default semantic icon does not match the message context, but keep icon usage consistent with the alert's intent.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--custom-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--custom-icon&viewMode=story&globals=theme:light" title="Alert custom icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Multiple actions

Use multiple action buttons in an Alert when the user has more than one valid way to resolve the issue—for example, "Retry" and "View details"—and limit choices to avoid decision overload.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--multiple-actions" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--multiple-actions&viewMode=story&globals=theme:light" title="Alert multiple actions story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Controlled visibility

Use controlled visibility when the Alert's open or closed state must follow application logic—for example, reopening after a failed save attempt or syncing with parent state.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--controlled-visibility" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--controlled-visibility&viewMode=story&globals=theme:light" title="Alert controlled visibility story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case long text

Test long text in Alerts to ensure titles and descriptions wrap correctly within card and strip layouts without breaking alignment or truncating critical information.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--edge-case-long-text" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--edge-case-long-text&viewMode=story&globals=theme:light" title="Alert edge case long text story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case special characters

Verify that Alerts render special characters and unicode correctly in titles and descriptions, especially when displaying dynamic user-generated or localized content.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--edge-case-special-characters" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--edge-case-special-characters&viewMode=story&globals=theme:light" title="Alert edge case special characters story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case no icon

Use an Alert without an icon when the message is neutral or when visual noise should be minimized, but ensure the text alone conveys severity clearly.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--edge-case-no-icon" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--edge-case-no-icon&viewMode=story&globals=theme:light" title="Alert edge case no icon story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge case no icon with close

Combine a no-icon Alert with a close control when the message is low emphasis and users should be able to dismiss it without a primary action button.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-alert--edge-case-no-icon-with-close" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-alert--edge-case-no-icon-with-close&viewMode=story&globals=theme:light" title="Alert edge case no icon with close story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>