Semantic Alerts

Alerts communicate important messages, warnings, errors, and confirmations to users. They use semantic colors and icons to convey meaning at a glance while maintaining accessibility.

Overview

The SemanticAlert component provides a consistent way to display feedback messages across your application. Each variant has a specific purpose and visual treatment that helps users quickly understand the message type and importance.

Interactive Demo

Usage

Basic Implementation

<script>
import SemanticAlert from '$lib/shared/components/feedback/SemanticAlert.svelte';
</script>

<SemanticAlert 
  variant="success" 
  message="Your changes have been saved successfully." 
/>

Without Icons

For a cleaner, text-only appearance:

<SemanticAlert 
  variant="info" 
  message="3 new messages" 
  showIcon={false}
/>

Custom Styling

Apply custom classes for specific use cases:

<SemanticAlert 
  variant="warning" 
  message="This action cannot be undone." 
  class="my-custom-alert"
/>

Variants

Error

Use for critical errors, validation failures, or operations that couldn’t be completed.

When to use:

• Form validation errors
• API request failures
• Permission denied messages
• Data processing errors

Success

Confirm successful operations and completed actions.

When to use:

• Form submission confirmations
• Save operations completed
• Upload successful
• Account created

Warning

Alert users to potential issues or important considerations.

When to use:

• Destructive action warnings
• Quota limits approaching
• Compatibility notices
• Deprecation warnings

Info

Provide helpful information or tips without implying success or failure.

When to use:

• Feature announcements
• Helpful tips
• Status updates
• General notifications

API Reference

Props

CSS Classes

The component applies these CSS classes that you can target:

• .alert-semantic - Base alert class
• .alert-semantic-{variant} - Variant-specific class
• .icon-semantic-alert - Icon wrapper class
• .icon-{variant} - Variant-specific icon class

Patterns

Dismissible Alerts

Wrap the alert with a container and add a dismiss button:

<script>
let showAlert = $state(true);
</script>

{#if showAlert}
  <div class="alert-container">
    <SemanticAlert 
      variant="info" 
      message="This message can be dismissed." 
    />
    <button 
      class="dismiss-btn" 
      onclick={() => showAlert = false}
      aria-label="Dismiss alert"
    >
      ×
    </button>
  </div>
{/if}

Alert Stack

Display multiple alerts in a managed stack:

<script>
let alerts = $state([
  { id: 1, variant: 'success', message: 'File uploaded' },
  { id: 2, variant: 'warning', message: 'Large file size' }
]);

function dismissAlert(id) {
  alerts = alerts.filter(a => a.id !== id);
}
</script>

<div class="alert-stack">
  {#each alerts as alert (alert.id)}
    <div class="alert-container">
      <SemanticAlert 
        variant={alert.variant} 
        message={alert.message} 
      />
      <button onclick={() => dismissAlert(alert.id)}>
        Dismiss
      </button>
    </div>
  {/each}
</div>

Auto-dismiss

Implement auto-dismissing alerts for non-critical messages:

<script>
import { onMount } from 'svelte';

let showSuccess = $state(false);

function showTempAlert() {
  showSuccess = true;
  setTimeout(() => showSuccess = false, 5000);
}
</script>

{#if showSuccess}
  <SemanticAlert 
    variant="success" 
    message="Saved! This message will auto-dismiss." 
  />
{/if}

Accessibility

ARIA Attributes

• role=“alert”: Default role for important messages that need immediate attention
• role=“status”: Use for non-critical status updates
• aria-live: Implicitly set to “assertive” for alerts

Keyboard Support

When implementing dismissible alerts:

• Ensure dismiss buttons are keyboard accessible
• Provide clear focus indicators
• Support Escape key for dismissal where appropriate

Screen Reader Considerations

• Alert messages are announced immediately when they appear
• Icon descriptions are hidden from screen readers (decorative)
• Message text provides complete context without relying on color or icons

Best Practices

Do’s

✅ Keep messages concise and actionable

• Tell users what happened and what to do next
• Use plain language, avoid technical jargon

✅ Use appropriate variants consistently

• Reserve error for actual failures
• Don’t use warning for simple information

✅ Position alerts contextually

• Place near the relevant content
• Top of page for global messages
• Inline for field-specific feedback

✅ Provide clear dismissal options

• Critical errors should persist
• Success messages can auto-dismiss
• Always allow manual dismissal for non-critical alerts

Don’ts

❌ Don’t overwhelm with too many alerts

• Combine related messages
• Prioritize the most important
• Consider progressive disclosure

❌ Don’t rely solely on color

• Always include text descriptions
• Use icons as reinforcement, not replacement
• Ensure sufficient contrast ratios

❌ Don’t block user actions unnecessarily

• Allow interaction with the page
• Use modals only for critical errors
• Provide escape routes

Examples

Form Validation

{#if form.errors.email}
  <SemanticAlert 
    variant="error" 
    message="Please enter a valid email address." 
  />
{/if}

API Response Handling

{#if response.status === 'success'}
  <SemanticAlert 
    variant="success" 
    message="Data saved successfully." 
  />
{:else if response.status === 'error'}
  <SemanticAlert 
    variant="error" 
    message={response.message || 'An error occurred. Please try again.'} 
  />
{/if}

System Status

<SemanticAlert 
  variant="warning" 
  message="Scheduled maintenance: System will be offline from 2-4 AM EST." 
  role="status"
/>

Troubleshooting

Alert not visible

• Check z-index in relation to other elements
• Ensure parent containers aren’t hiding overflow
• Verify the message prop is not empty

Icons not showing

• Confirm icon files exist at specified paths
• Check showIcon prop is not set to false
• Verify Icon component is properly imported

Screen reader not announcing

• Ensure role attribute is properly set
• Check that alert is added to DOM (not just made visible)
• Verify aria-live regions aren’t being suppressed

Related Components

• SemanticMessage: Inline messages for form fields
• Tooltip: Contextual help on hover
• EmptyState: Full-page feedback when no content exists
• ErrorBoundary: Catching and displaying component errors