Sheaf UI

#Introduction

The Alerts component is a flexible notification system designed to communicate important information to users. It supports semantic variants, extensive color customization, two distinct icon layout patterns, and optional action controls for interactive notifications.

#Installation

Use the sheaf artisan command to install the alerts component easily:

php artisan sheaf:install alerts

Once installed, you can use the <x-ui.alerts />, <x-ui.alerts.heading /> and <x-ui.alerts.description /> components in any Blade view.

#Basic Usage

#Alert Variants

The alert component provides four semantic variants, each automatically applying appropriate colors when no custom color is specified.

<!-- Info alert (default) -->
<x-ui.alerts variant="info" icon="information-circle">
    <x-ui.alerts.heading>Information</x-ui.alerts.heading>
    <x-ui.alerts.description>This is an informational message.</x-ui.alerts.description>
</x-ui.alerts>

<!-- Success alert -->
<x-ui.alerts variant="success" icon="check-circle">
    <x-ui.alerts.heading>Success</x-ui.alerts.heading>
    <x-ui.alerts.description>Operation completed successfully.</x-ui.alerts.description>
</x-ui.alerts>

<!-- Warning alert -->
<x-ui.alerts variant="warning" icon="exclamation-triangle">
    <x-ui.alerts.heading>Warning</x-ui.alerts.heading>
    <x-ui.alerts.description>Please review this important notice.</x-ui.alerts.description>
</x-ui.alerts>

<!-- Error alert -->
<x-ui.alerts variant="error" icon="exclamation-circle">
    <x-ui.alerts.heading>Error</x-ui.alerts.heading>
    <x-ui.alerts.description>An error occurred during processing.</x-ui.alerts.description>
</x-ui.alerts>

#Description Only Alerts

You can create simple alerts with just a description, no heading required.

<!-- Alert with description only -->
<x-ui.alerts variant="info" icon="sparkles">
    <x-ui.alerts.description>Version 2.0 is now available for download.</x-ui.alerts.description>
</x-ui.alerts>

<x-ui.alerts variant="success" icon="check-circle">
    <x-ui.alerts.description>Your changes have been saved successfully.</x-ui.alerts.description>
</x-ui.alerts>

#Icon Placement

The alert component supports two distinct icon layout patterns to suit different design needs.

#Alert-Level Icons (Left Side)

Place icons at the alert level for a traditional notification layout with the icon positioned to the left of all content.

<!-- Icon positioned at alert level (left side) -->
<x-ui.alerts variant="success" icon="check-circle">
    <x-ui.alerts.heading>Payment successful</x-ui.alerts.heading>
    <x-ui.alerts.description>Your payment has been processed successfully.</x-ui.alerts.description>
</x-ui.alerts>

<x-ui.alerts variant="error" icon="shield-exclamation">
    <x-ui.alerts.heading>Authentication failed</x-ui.alerts.heading>
    <x-ui.alerts.description>Invalid credentials. Please check your email and password.</x-ui.alerts.description>
</x-ui.alerts>

Note: When both heading and description are present, the alert-level icon automatically aligns to the top for better visual balance.

#Heading-Level Icons (Inline)

Place icons directly in the heading for a more integrated, inline appearance.

<!-- Icon positioned at heading level (inline) -->
<x-ui.alerts variant="warning">
    <x-ui.alerts.heading icon="server-stack">Storage almost full</x-ui.alerts.heading>
    <x-ui.alerts.description>You've used 90% of your storage space. Consider upgrading your plan.</x-ui.alerts.description>
</x-ui.alerts>

<x-ui.alerts color="blue">
    <x-ui.alerts.heading icon="light-bulb">Information</x-ui.alerts.heading>
    <x-ui.alerts.description>This is a blue informational alert message.</x-ui.alerts.description>
</x-ui.alerts>

Important: Use either alert-level OR heading-level icons, not both. They represent two different layout patterns.

#Custom Colors

Override the default variant colors with any of the 22+ available color options.

#Custom Colors

Override the default variant colors with any of the 22+ available color options.

<x-ui.alerts color="red">...</x-ui.alerts>
<x-ui.alerts color="orange">...</x-ui.alerts>
<x-ui.alerts color="amber">...</x-ui.alerts>
<x-ui.alerts color="yellow">...</x-ui.alerts>
<x-ui.alerts color="lime">...</x-ui.alerts>
<x-ui.alerts color="green">...</x-ui.alerts>
<x-ui.alerts color="emerald">...</x-ui.alerts>
<x-ui.alerts color="teal">...</x-ui.alerts>
<x-ui.alerts color="cyan">...</x-ui.alerts>
<x-ui.alerts color="sky">...</x-ui.alerts>
<x-ui.alerts color="blue">...</x-ui.alerts>
<x-ui.alerts color="indigo">...</x-ui.alerts>
<x-ui.alerts color="violet">...</x-ui.alerts>
<x-ui.alerts color="purple">...</x-ui.alerts>
<x-ui.alerts color="fuchsia">...</x-ui.alerts>
<x-ui.alerts color="pink">...</x-ui.alerts>
<x-ui.alerts color="rose">...</x-ui.alerts>
<x-ui.alerts color="slate">...</x-ui.alerts>
<x-ui.alerts color="gray">...</x-ui.alerts>
<x-ui.alerts color="zinc">...</x-ui.alerts>
<x-ui.alerts color="neutral">...</x-ui.alerts>
<x-ui.alerts color="stone">...</x-ui.alerts>

#Alerts with Controls

Add interactive buttons or controls that users can act upon directly within the alert.

<!-- Alert with action button -->
<x-ui.alerts variant="info" icon="sparkles">
    <x-ui.alerts.description>Version 2.0 is now available for download.</x-ui.alerts.description>
    <x-slot:controls>
        <x-ui.button color="blue" icon="cloud-arrow-down">Download</x-ui.button>
    </x-slot:controls>
</x-ui.alerts>

<!-- Controls with custom alignment -->
<x-ui.alerts variant="success" icon="check-circle">
    <x-ui.alerts.heading>Payment successful</x-ui.alerts.heading>
    <x-ui.alerts.description>Your payment has been processed successfully.</x-ui.alerts.description>
    <x-slot:controls class="self-center">
        <x-ui.button color="neutral" icon="key">Grant Access</x-ui.button>
    </x-slot:controls>
</x-ui.alerts>

Tip: Use the class attribute on the controls slot to customize alignment (self-start, self-center, self-end).

#Component Props

#ui.alert

#ui.alert.heading

#ui.alert.description

The description component accepts only the default slot for content and automatically applies appropriate text styling.

#Default Variant Mappings