Alert

Summary

Alert presents short feedback or status messages with optional icon, title, and content areas. It is the message-level feedback surface when a Badge is too small and a Card would be too neutral.

Imports

import {
  Alert,
  AlertIcon,
  AlertMain,
  AlertTitle,
  AlertContent,
  type AlertProps,
} from '@vega-ui/react';

Exported Types

• AlertProps
• AlertIconProps
• AlertMainProps
• AlertTitleProps
• AlertContentProps

Minimal Composition

import {
  Alert,
  AlertContent,
  AlertIcon,
  AlertMain,
  AlertTitle,
} from '@vega-ui/react';

export default function MinimalComposition() {
  return (
    <Alert variant='success' style={{ width: '100%' }}>
      <AlertIcon />

Required Parts

• Alert: root feedback surface
• AlertMain: main text wrapper

Optional Parts

• AlertIcon: semantic icon surface
• AlertTitle: stronger visual hierarchy
• AlertContent: supporting message copy

Composition Order

1. Alert
2. AlertIcon
3. AlertMain
4. AlertTitle
5. AlertContent

Variants

• Semantic variants: success, error, warning, info
• Appearances: fill, surface
• Compositional variants: with or without icon, with or without title

Edge Cases

• Use a title only when the alert needs stronger hierarchy.
• Keep content short; long-form content belongs elsewhere.
• Match the alert variant to semantics, not just visual color.
• If the content becomes procedural, multi-step, or highly interactive, the right pattern is usually no longer an alert.

Common Mistakes

• Using alerts for persistent page layout instead of feedback.
• Encoding severity only by color or icon.
• Placing complex workflows into an alert body.

Examples

Basic

Basic: the four variants

Each variant gets its matching default icon from AlertIcon. appearance='surface' adds a border for messages that need more weight, like the declined card. These alerts are part of the page from the start, so they need no live-region role.

import { Alert, AlertContent, AlertIcon, AlertMain, AlertTitle } from '@vega-ui/react';

export default function Variants() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%', maxWidth: 560 }}>
      <Alert variant='info'>
        <AlertIcon />
        <AlertMain>
          <AlertTitle>Scheduled maintenance</AlertTitle>
          <AlertContent>The dashboard will be read-only on Sunday from 02:00 to 03:00 UTC.</AlertContent>
        </AlertMain>
      </Alert>

Controlled/Stateful

Controlled/Stateful: dismissible announcement

The parent owns visibility. The dismiss button has its own accessible name, and after dismissal focus moves to the section heading so keyboard users do not lose their place.

import { useRef, useState } from 'react';
import type { CSSProperties } from 'react';
import { Alert, AlertContent, AlertIcon, AlertMain, AlertTitle, Button, Heading, Icon, IconButton } from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';

export default function Dismissible() {
  const [visible, setVisible] = useState(true);
  const headingRef = useRef<HTMLHeadingElement>(null);

  const dismiss = () => {
    setVisible(false);
    headingRef.current?.focus();

Form/Integration

Form/Integration: save result after submit

The form reads values with FormData and simulates a request. Success is rendered into a role='status' container that exists before the message appears, so screen readers announce it; a failure is an assertive role='alert'.

import { FormEvent, useState } from 'react';
import {
  Alert,
  AlertContent,
  AlertIcon,
  AlertMain,
  AlertTitle,
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,

Layout/Overlay

Layout/Overlay: warning inside a confirmation dialog

The warning explains the consequence of the destructive action and is linked to the dialog with aria-describedby, so it is read together with the dialog title.

import type { CSSProperties } from 'react';
import {
  Alert,
  AlertContent,
  AlertIcon,
  AlertMain,
  AlertTitle,
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,

Error

Error: error summary above a form

On submit, invalid fields get aria-invalid and a linked HelperText, and an alert lists every error with a link that focuses the field. Errors update as the user types and the summary disappears once everything is valid.

import { FormEvent, MouseEvent, useState } from 'react';
import {
  Alert,
  AlertIcon,
  AlertMain,
  AlertTitle,
  Button,
  HelperText,
  Label,
  Text,
  TextField,
  TextFieldInput,

Edge

Edge: long unbreakable content and actions

The domain and the TXT record have no spaces, so they need overflow-wrap: anywhere and min-width: 0 on AlertMain to stay inside the alert. Actions sit in AlertMain and report their result through a status region.

import { useState } from 'react';
import { Alert, AlertContent, AlertIcon, AlertMain, AlertTitle, Button, Text } from '@vega-ui/react';

const record = 'vega-site-verification=8c1f0b6e2d9a4f7b93e5c2a1d0f4e6b8a7c3d9e1f2b4a6c8d0e2f4a6b8c0d2e4';

export default function DomainVerification() {
  const [message, setMessage] = useState('');

  const copy = async () => {
    await navigator.clipboard.writeText(record);
    setMessage('Copied to clipboard.');
  };

Anatomy

Overview

Alert is a compound component because the root, icon, title, and content parts work together as one message pattern with shared semantic variant context.

Required Parts

Alert

Required. Owns semantic variant and appearance.

AlertMain

Required in most product alerts. Wraps the message hierarchy.

Optional Parts

AlertIcon

Optional semantic icon surface.

AlertTitle

Optional title for stronger emphasis.

AlertContent

Optional supporting message copy.

Composition Order

1. Alert
2. AlertIcon
3. AlertMain
4. AlertTitle
5. AlertContent

Valid Composition Patterns

import { Alert, AlertContent, AlertIcon, AlertMain, AlertTitle } from '@vega-ui/react';

export default function Variants() {
  return (
    <div style={{ display: 'grid', gap: 'var(--spacing-6)', width: '100%', maxWidth: 560 }}>
      <Alert variant='info'>
        <AlertIcon />
        <AlertMain>
          <AlertTitle>Scheduled maintenance</AlertTitle>
          <AlertContent>The dashboard will be read-only on Sunday from 02:00 to 03:00 UTC.</AlertContent>
        </AlertMain>
      </Alert>

Invalid Composition Patterns

Alert used as a full-page layout shell

Alerts are feedback messages, not a replacement for page structure.

Long action-heavy workflow inside the alert

Once the content becomes task-heavy, another pattern is usually a better fit.