Alert ​

Informs users about important changes or persistent conditions. Use this component if you need to communicate to users in a prominent way. Alerts are placed at the top of the page or section they apply to, and below the page or section header.

Usage ​

Use to convey general information or actions that aren't critical. For example, you might show an alert that asks for users feedback. Default alerts contain lower priority information and should always be dismissable.

<script lang="ts" setup>
import { Alert, AlertDescription, AlertTitle } from '@returnless/focus-ui';
</script>

<template>
  <Alert>
    <AlertTitle>Heads up!</AlertTitle>
    <AlertDescription>
      You can add components to your app using the cli.
    </AlertDescription>
  </Alert>
</template>

Informative ​

Use to communicate general information or actions that aren't critical. For example, you might show an alert that informs users about a new feature. Info alerts contain lower priority information.

<script lang="ts" setup>
import { Alert, AlertDescription, AlertTitle } from '@returnless/focus-ui';
</script>

<template>
  <Alert variant="informative">
    <AlertTitle>Heads-up</AlertTitle>
    <AlertDescription>
      A new version of the app is available. Refresh your browser to update.
    </AlertDescription>
  </Alert>
</template>

Destructive ​

Use to communicate critical information or actions that require immediate attention. For example, you might show an alert that warns users about a critical system failure. Destructive alerts contain higher priority information.

<script lang="ts" setup>
import { Alert, AlertDescription, AlertTitle } from '@returnless/focus-ui';
</script>

<template>
  <Alert variant="destructive">
    <AlertTitle>Error</AlertTitle>
    <AlertDescription>
      Your session has expired. Please log in again.
    </AlertDescription>
  </Alert>
</template>

Warning ​

Use to display information that needs attention or that user need to take action on. Seeing these banners can be stressful for user so be cautious about using them.

<script lang="ts" setup>
import { Alert, AlertDescription, AlertTitle } from '@returnless/focus-ui';
</script>

<template>
  <Alert variant="warning">
    <AlertTitle>Before you can purchase a shipping label, this change needs to be made:</AlertTitle>
    <AlertDescription>
      The name of the city you’re shipping to has characters that aren’t allowed. City name can only include spaces and hyphens.
    </AlertDescription>
  </Alert>
</template>

Best practices ​

Alerts should:

• Be used thoughtfully and sparingly for only the most important information.
• Not be used to call attention to what a user needs to do in the UI instead of making the action clear in the UI itself.
• Not be the primary entry point of information or actions users need on a regular basis.
• Be dismissible unless they contain critical information or an important step users need to take.

Placement ​

Alerts should be placed in the appropriate context:

• Alerts relevant to an entire page should be placed at the top of that page, below the page header. They should occupy the full width of the content area.
• Alerts related to a section of a page (like a card, popover, or modal) should be placed inside that section, below any section heading.
• Alerts related to an element more specific that a section should be placed immediately above or below that element.

Content guidelines ​

Alerts should:

• Focus on a single theme, piece of information, or required action to avoid overwhelming users.
• Be concise and scannable - users shouldn't need to spend a lot of time figuring out what the alert is trying to communicate.
• Be limited to a few important calls to action with no more than one primary action.

Body content ​

Body content should:

• Be concise: keep the content to 1 or 2 sentences where possible.
• Clarify the benefit of the main task.
• Be written in sentence case and use appropriate punctuation.
• Avoid repeating the heading.
• Explain how to resolve the issue, particularly for destructive alerts.

Accessibility ​

Alerts provide context and assist workflows for users with disabilities.

• Destructive alerts have a role="alert" attribute and are announced by assistive technologies when they appear.
• All other alerts have a role="status" attribute and are read after any critical announcements.
• Alert containers have a tabindex="0" attribute and display a visible keyboard focus indicator. Because of this, merchants can discover banners while tabbing through forms or other interactions, and developers can programmatically move focus to banners.