Library Components API

@Alert

A notification component for displaying important messages with contextual styling and optional dismiss functionality. Alerts are essential for communicating important information, warnings, errors, or success messages to users in a clear and noticeable way. They support different severity levels through color-coded variants, can include icons for better visual recognition, and offer optional dismiss functionality for user control. With built-in animation support, alerts can appear smoothly and grab attention without being jarring.

Props

• variant::Union{Symbol,String}: Alert variant (:info, :success, :warning, :error) (default: :info)
• dismissible::Bool: Whether alert can be dismissed (shows close button) (default: false)
• icon::Bool: Whether to show icon (default: true)
• animated::Bool: Whether to show fade-in animation (default: true)

Slots

• Alert message content - can include text, links, or other inline elements

Interactive Features

When dismissible=true, this component uses Alpine.js for interactive dismiss functionality. To enable interactivity, include Alpine.js in your page:

@script {defer=true, src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"}

Without Alpine.js, the component will display the close button but won't be interactive.

Example

# Simple alerts
@Alert "This is an informational message."
@Alert {variant = :success} "Operation completed successfully!"
@Alert {variant = :error} "An error occurred. Please try again."

# Dismissible alert
@Alert {variant = :warning, dismissible = true} begin
    @strong "Warning:"
    @text " Your session will expire in 5 minutes."
end

# Alert with custom content
@Alert {variant = :info, icon = false} begin
    @Text "New version available. "
    @Link {href = "/changelog"} "View changelog"
end

See also

• Badge - For small status indicators
• Card - For general content containers
• Tooltip - For contextual help messages

@Avatar

A user profile image component that displays user avatars with automatic fallbacks and consistent styling. Avatars are essential for personalizing user interfaces, making them feel more human and helping users quickly identify accounts, authors, or participants in conversations. This component handles the common challenges of avatar display including missing images, different aspect ratios, and the need for fallback representations. It provides multiple size options and shape variants (circular or square) while ensuring images load smoothly and fallbacks appear gracefully when no image is available.

Props

• src::Union{String,Nothing}: Image source URL (optional)
• alt::String: Alternative text (required when src is provided, ignored otherwise)
• size::Union{Symbol,String}: Avatar size (:xs, :sm, :md, :lg, :xl) (default: :md)
• shape::Union{Symbol,String}: Avatar shape (:circle, :square) (default: :circle)
• fallback::Union{String,Nothing}: Fallback content when no src provided (optional)

@Badge

A small label component for displaying status, counts, or categorization. Badges are compact visual indicators that draw attention to important information without disrupting the flow of content. They're commonly used to show notification counts, status indicators, tags, or to highlight new features. With support for multiple color variants and sizes, badges can effectively communicate different states and priorities while maintaining visual hierarchy in your interface.

Props

• variant::Union{Symbol,String}: Badge variant (:default, :primary, :secondary, :success, :warning, :danger, :gradient) (default: :default)
• size::Union{Symbol,String}: Badge size (:xs, :sm, :base, :lg, :xl) (default: :base)
• role::Union{String,Nothing}: ARIA role (e.g., "status" for dynamic updates) (optional)
• animated::Bool: Whether badge has subtle animation (default: false)
• outline::Bool: Whether badge has outline style (default: false)

Slots

• Badge text or content (typically short text, numbers, or icons)

Example

# Status badges
@Badge {variant = :success} "Active"
@Badge {variant = :danger} "Expired"
@Badge {variant = :warning} "Pending"

# Count badge
@Badge {variant = :primary, size = :sm} "99+"

# Animated badge for live updates
@Badge {variant = :gradient, animated = true, role = "status"} "Live"

# Outline style
@Badge {variant = :secondary, outline = true} "Beta"

See also

• Card - Container component often used with badges
• Button - Interactive element with similar variants
• Alert - For larger notification messages

@Breadcrumb

A navigation breadcrumb component that displays the hierarchical path to the current page. Breadcrumbs are crucial wayfinding elements that help users understand their location within a website's structure and provide quick navigation to parent pages. This component automatically handles the visual styling of links versus the current page, includes proper ARIA attributes for accessibility, and uses semantic HTML markup. The customizable separator and responsive text sizing ensure breadcrumbs remain readable and functional across all device sizes.

Props

• items::Vector{Tuple{String,String}}: Breadcrumb items as (href, label) tuples
• separator::String: Separator character/string (default: "/")

Accessibility

ARIA: Uses <nav aria-label="Breadcrumb"> with aria-current="page" for current page. Ordered list conveys hierarchy.

Keyboard: Tab through breadcrumb links, Enter follows navigation. Current page is skipped in tab order.

Guidelines: Include home page as first item, use descriptive titles, keep text concise.

@Button

A versatile button component for triggering actions with multiple variants, sizes, and states. Supports icons, loading states, and full accessibility with proper ARIA attributes and keyboard navigation.

Props

• variant::Union{Symbol,String}: Button variant (:primary, :secondary, :neutral, :success, :warning, :danger, :gradient, :ghost, :outline) (default: :primary)
• size::Union{Symbol,String}: Button size (:xs, :sm, :base, :lg, :xl) (default: :base)
• type::String: Button type attribute (default: "button")
• disabled::Bool: Whether button is disabled (default: false)
• loading::Bool: Whether button is in loading state (default: false)
• full_width::Bool: Whether button should be full width (default: false)
• icon_left::Union{String,Nothing}: Icon HTML to display on the left (optional)
• icon_right::Union{String,Nothing}: Icon HTML to display on the right (optional)
• rounded::Union{Symbol,String}: Border radius (:base, :lg, :xl, :full) (default: :xl)

Slots

• Button label text or content

Example

# Basic buttons
@Button "Click me"
@Button {variant = :secondary} "Cancel"
@Button {variant = :danger, size = :sm} "Delete"

# Button with icon
@Button {icon_left = @Icon {name = "save"}} "Save changes"

# Loading state
@Button {loading = true} "Processing..."

# Full width button
@Button {variant = :gradient, full_width = true} "Get Started"

# Icon-only button
@Button {variant = :ghost, size = :sm, rounded = :full} begin
    @Icon {name = "settings"}
end

Accessibility

ARIA & Keyboard: Semantic <button> element with standard Enter/Space activation. Disabled and loading states are properly announced to screen readers.

Icon-only buttons: Must include aria-label for screen reader context.

Visual Design: High contrast focus indicators and 4.5:1 color contrast across all variants.

See also

• Link - For navigation links
• Icon - For button icons
• DropdownMenu - For button dropdowns
• Badge - For button badges/counters

@Card

A versatile content container with customizable styling, borders, and shadows. Cards provide clean visual separation for grouped content and can be used for content blocks, product listings, user profiles, or dashboard widgets.

Props

• padding::Union{Symbol,String}: Padding size (:none, :sm, :base, :lg, :xl) (default: :base)
• shadow::Union{Symbol,String}: Shadow type (:none, :sm, :base, :lg, :colored) (default: :base)
• border::Union{Bool,Symbol}: Border style (true, false, :gradient) (default: true)
• rounded::Union{Symbol,String}: Border radius (:none, :sm, :base, :lg, :xl) (default: :lg)
• variant::Union{Symbol,String}: Card variant (:default, :glass, :gradient) (default: :default)
• hoverable::Bool: Whether card has hover effects (default: false)

Slots

• Card content - can be any elements like text, images, buttons, or other components

Example

# Basic card
@Card begin
    @Heading {level = 3} "Card Title"
    @Text "This is the card content."
    @Button {variant = :primary} "Action"
end

# Hoverable card with gradient border
@Card {border = :gradient, hoverable = true} begin
    @Text "Hover over me!"
end

# Glass morphism card
@Card {variant = :glass, shadow = :lg} begin
    @Badge "New"
    @Text "Glass effect card"
end

See also

• Badge - For status indicators within cards
• Alert - For notification messages
• Container - For page-level containers
• Stack - For arranging multiple cards

@Checkbox

A styled checkbox input that allows users to toggle between checked and unchecked states. Checkboxes are fundamental form controls for binary choices, terms acceptance, or selecting multiple options from a list. This component enhances the native checkbox with custom styling that matches your design system while preserving full keyboard accessibility and screen reader support. It can be used standalone or with an integrated label, and supports different color schemes and sizes to fit various UI contexts.

Props

• size::Union{Symbol,String}: Checkbox size (:sm, :md, :lg) (default: :md)
• color::Union{Symbol,String}: Checkbox color (:slate, :primary, :success) (default: :primary)
• label::Union{String,Nothing}: Label text (optional)
• name::Union{String,Nothing}: Checkbox name attribute (optional)
• value::Union{String,Nothing}: Checkbox value (optional)
• checked::Bool: Whether checkbox is checked (default: false)
• required::Bool: Whether checkbox is required (default: false)
• disabled::Bool: Whether checkbox is disabled (default: false)

@Container

A responsive container component that constrains content width and provides consistent padding. This component serves as the primary layout wrapper for page content, ensuring readable line lengths and appropriate spacing across different screen sizes. It automatically centers content and applies responsive breakpoints to maintain optimal viewing experiences from mobile devices to large desktop displays.

Props

• size::Union{Symbol,String}: Container size (:sm, :md, :lg, :xl, "2xl", :full) (default: :xl)
• padding::Bool: Whether to include horizontal padding (default: true)
• centered::Bool: Whether to center the container (default: true)
• role::Union{String,Nothing}: ARIA role for the container (e.g., "main") (optional)
• glass::Bool: Whether to apply glassmorphism effect (default: false)

Slots

• Content to be contained within the responsive wrapper

Example

@Container {size = :lg} begin
    @Heading "Welcome"
    @Text "This content is constrained to a large container width."
end

# With glass effect
@Container {glass = true, size = :md} begin
    @Card "Glassmorphic content"
end

See also

• Section - For page sections with vertical spacing
• Stack - For stacking elements with consistent gaps
• Grid - For grid-based layouts

@Divider

A horizontal or vertical separator component that creates visual boundaries between sections of content. Dividers are subtle yet important design elements that help organize interfaces by creating clear visual separation without adding clutter. They guide the eye through layouts, group related content, and provide breathing room between different sections. This component supports both horizontal and vertical orientations with customizable spacing and colors, adapting seamlessly to light and dark themes while maintaining appropriate visual weight for non-intrusive content separation.

Props

• orientation::Union{Symbol,String}: Divider orientation (:horizontal, :vertical) (default: :horizontal)
• spacing::Union{String,Nothing}: Custom spacing class (optional)
• color::Union{String,Nothing}: Border color class (optional)

@DrawerModal

A modal that slides in from the edge of the screen, ideal for navigation menus, settings panels, or secondary content that benefits from a slide-in presentation.

Props

• id::String: Unique identifier for the modal (required)
• position::Union{Symbol,String}: Slide direction (:left, :right, :top, :bottom) (default: :right)
• size::Union{Symbol,String}: Drawer size (:sm, :md, :lg) (default: :md)
• persistent::Bool: Prevent closing on backdrop click (default: false)

Slots

• Drawer content - typically contains ModalHeader and ModalContent components

Example

# Right-side drawer (default)
@DrawerModal {id = "settings-drawer", size = :lg} begin
    @ModalHeader "Settings"
    @ModalContent begin
        @Text "Settings content here..."
    end
end

# Left-side navigation drawer
@DrawerModal {id = "nav-drawer", position = :left} begin
    @ModalContent begin
        @nav begin
            @Link {href = "/"} "Home"
            @Link {href = "/about"} "About"
            @Link {href = "/contact"} "Contact"
        end
    end
end

# Bottom drawer for mobile-friendly forms
@DrawerModal {id = "filter-drawer", position = :bottom} begin
    @ModalHeader "Filter Options"
    @ModalContent begin
        @FormGroup {label = "Sort By"} begin
            @Select {options = [("date", "Date"), ("name", "Name")]}
        end
    end
end

Accessibility

ARIA: Uses native <dialog> semantics with automatic focus trapping.

Keyboard: Escape closes drawer, Tab cycles through focusable elements.

Touch: Designed for mobile interaction with proper touch targets.

See also

• Modal - Standard centered modal
• ModalHeader - Drawer header section
• ModalContent - Drawer body content
• ModalTrigger - Button to open drawers

Note: Requires Alpine.js. Drawer corners are sharp (no rounding) for edge-to-edge appearance.

@DropdownContent

The container for dropdown menu items that appears when the dropdown is triggered, providing the visual menu panel. This component creates a floating panel that positions itself intelligently relative to the trigger using Alpine Anchor, automatically adjusting to stay within viewport bounds. It manages the menu's appearance with smooth transitions, handles keyboard navigation between items, and provides proper focus management. The content container supports various menu patterns including simple lists, grouped items with dividers, and complex layouts with nested submenus.

Props

• class::String: Additional CSS classes
• attrs...: Additional attributes

Slots

• Dropdown menu items - should contain @DropdownItem, @DropdownDivider, and @DropdownSubmenu components

Example

@DropdownContent begin
    @DropdownItem {href = "/profile"} "Profile"
    @DropdownItem {href = "/settings"} "Settings"
    @DropdownDivider
    @DropdownSubmenu {label = "More"} begin
        @DropdownItem "Option 1"
        @DropdownItem "Option 2"
    end
end

Accessibility

ARIA: Uses role="menu" with proper ARIA relationships and focus management.

Keyboard: Arrow keys navigate, Home/End jump to first/last, Enter/Space activate, Escape closes.

Screen Reader: Menu structure and item states are announced with positional feedback.

See also

• DropdownMenu - Parent dropdown container
• DropdownItem - Menu items
• DropdownDivider - Visual separator
• DropdownSubmenu - Nested menus

@DropdownDivider

Visual separator between dropdown items.

Props

• class::String: Additional CSS classes
• attrs...: Additional attributes

@DropdownItem

An individual menu item within dropdown menus that represents a selectable action or navigation option. Dropdown items are the core interactive elements of any menu, supporting various states like hover, disabled, and different semantic variants (default, danger, success). They can function as either buttons for actions or links for navigation, include optional icons for visual clarity, and maintain consistent styling across different uses. The component ensures proper keyboard accessibility and provides visual feedback through smooth hover transitions.

Props

• href::Union{String,Nothing}: Optional link URL
• disabled::Bool: Whether item is disabled (default: false)
• icon::Union{String,Nothing}: Optional icon name
• variant::Symbol: Item variant (:default, :danger, :success)
• class::String: Additional CSS classes
• attrs...: Additional attributes

Slots

• Menu item text or content

Example

# Basic item
@DropdownItem "Settings"

# Link item with icon
@DropdownItem {href = "/profile", icon = "user"} "My Profile"

# Danger variant
@DropdownItem {variant = :danger} "Delete Account"

# Disabled item
@DropdownItem {disabled = true} "Coming Soon"

Accessibility

ARIA: Uses role="menuitem" with proper disabled states via aria-disabled.

Keyboard: Enter/Space activates, participates in parent menu's navigation flow.

Visual Design: High contrast focus indicators and disabled states with reduced opacity.

See also

• DropdownContent - Parent content container
• DropdownSubmenu - For nested items
• DropdownDivider - For separating items
• Icon - For item icons

@DropdownMenu

A flexible dropdown menu component with support for nested submenus, powered by Alpine.js and Alpine Anchor. Provides trigger buttons, menu items, dividers, and intelligent positioning with click-outside behavior and keyboard navigation.

Requirements

This component requires Alpine.js and Alpine Anchor for intelligent positioning:

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/anchor@latest/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are automatically loaded via @__once__ for optimal performance.

Accessibility

ARIA: Uses role="menu" with aria-haspopup and aria-expanded states. Menu items have proper roles and state attributes.

Keyboard: Escape to close, Arrow keys to navigate, Enter/Space to activate, Tab to exit.

Focus Management: Returns to trigger when closed, moves to first item when opened via keyboard.

Props

• class::String: Additional CSS classes
• attrs...: Additional attributes

Slots

• Should contain exactly one @DropdownTrigger and one @DropdownContent component

Usage

@DropdownMenu begin
    @DropdownTrigger begin
        @Button "Options" {variant=:secondary}
    end

    @DropdownContent begin
        @DropdownItem {href="/profile"} "Profile"
        @DropdownItem {href="/settings"} "Settings"
        @DropdownDivider
        @DropdownItem {variant=:danger} "Logout"
    end
end

See also

• DropdownTrigger - Dropdown trigger component
• DropdownContent - Dropdown content container
• DropdownItem - Individual menu items
• DropdownSubmenu - Nested dropdown menus
• Button - Common trigger element

@DropdownSubmenu

A nested submenu component that creates hierarchical flyout menus within dropdowns for organizing complex menu structures. Submenus are essential for creating multi-level navigation without overwhelming users with too many options at once. This component manages its own open state while coordinating with the parent dropdown, positions itself to the side of the parent menu item, and includes visual indicators like chevrons to show that it contains nested options. The submenu supports the same rich content as regular dropdown menus, enabling deep menu hierarchies while maintaining usability.

Props

• label::String: The label for the submenu trigger
• icon::Union{String,Nothing}: Optional icon name
• class::String: Additional CSS classes
• attrs...: Additional attributes

Slots

• Submenu items - typically @DropdownItem components

Example

@DropdownSubmenu {label = "Export As"} begin
    @DropdownItem {icon = "document"} "PDF"
    @DropdownItem {icon = "file"} "CSV"
    @DropdownItem {icon = "code"} "JSON"
end

Implementation Notes

The submenu uses Alpine Anchor for positioning. The key to making this work is the x-anchor directive on the submenu content, which references its trigger button using $el.previousElementSibling. This works because:

1. The DOM structure places the trigger button immediately before the submenu content
2. $el in the x-anchor context refers to the element with the directive (submenu content)
3. previousElementSibling reliably points to the trigger button
4. This avoids complex ref lookups that can fail due to Alpine scope boundaries

The submenu state is managed by the parent dropdown's Alpine component through the openSubmenus object, allowing multiple submenus to be open simultaneously.

Accessibility

ARIA: Maintains proper hierarchy for nested menus with expandable content indicators.

Keyboard: Arrow Right opens submenu, Arrow Left closes, Escape closes all menus.

Focus Management: Logical movement between menu levels with proper focus return.

See also

• DropdownMenu - Root dropdown component
• DropdownContent - Parent content container
• DropdownItem - Menu items within submenu

@DropdownTrigger

The trigger element for dropdown menus that wraps any clickable element to control menu visibility. This component transforms its child element into an interactive trigger that opens the associated dropdown content on click. It automatically manages ARIA attributes for accessibility, including expanded state and menu ownership. The trigger can wrap various elements like buttons, links, or custom components, making it flexible for different design needs. It coordinates with the parent DropdownMenu to handle proper focus management and state synchronization.

Props

• attrs...: Additional attributes passed to the wrapper

Slots

• Clickable element that triggers the dropdown (typically a Button)

Example

@DropdownTrigger begin
    @Button {variant = :secondary} "Menu"
end

Accessibility

ARIA: Uses aria-haspopup="true" and maintains aria-expanded state.

Keyboard: Enter/Space and Arrow Down open dropdown, Escape closes (handled by parent).

See also

• DropdownMenu - Parent dropdown container
• DropdownContent - Dropdown content that appears
• Button - Common trigger element

@FormGroup

A form field wrapper that provides consistent layout for form controls with labels, help text, and error messages. Automatically generates unique IDs and establishes proper accessibility relationships between elements.

Props

• label::Union{String,Nothing}: Field label (optional)
• help::Union{String,Nothing}: Help text (optional)
• error::Union{String,Nothing}: Error message (optional)
• required::Bool: Whether field is required (default: false)
• id::Union{String,Nothing}: ID for the form field (will be auto-generated if not provided) (optional)

Slots

• Form control element(s) - typically Input, Textarea, Select, Checkbox, or Radio components

Example

# Basic form field
@FormGroup {label = "Email", help = "We'll never share your email."} begin
    @Input {type = "email", placeholder = "name@example.com"}
end

# Required field with error
@FormGroup {label = "Password", required = true, error = "Password must be at least 8 characters"} begin
    @Input {type = "password", state = :error}
end

# Checkbox group
@FormGroup {label = "Preferences"} begin
    @Checkbox {label = "Send me updates"}
end

See also

• Input - Text input component
• Textarea - Multi-line text input
• Select - Dropdown select component
• Checkbox - Checkbox input
• Radio - Radio button group

@Grid

A responsive grid layout component for arranging content in columns. The Grid component provides a powerful and flexible way to create multi-column layouts that automatically adapt to different screen sizes. It handles the complexity of responsive design by allowing you to specify different column counts for various breakpoints, making it ideal for galleries, card layouts, product listings, and any content that benefits from a structured grid arrangement.

Props

• cols::Int: Default number of columns (default: 1)
• sm::Int: Columns on small screens (optional)
• md::Int: Columns on medium screens (optional)
• lg::Int: Columns on large screens (optional)
• xl::Int: Columns on extra large screens (optional)
• gap::Int: Gap size using Tailwind spacing scale (default: 4)

Slots

• Grid items to be arranged in columns

Example

# Responsive card grid
@Grid {cols = 1, md = 2, lg = 3, gap = 6} begin
    @Card "Item 1"
    @Card "Item 2"
    @Card "Item 3"
    @Card "Item 4"
    @Card "Item 5"
    @Card "Item 6"
end

# Simple two-column layout
@Grid {cols = 2, gap = 4} begin
    @Section "Left content"
    @Section "Right content"
end

See also

• Stack - For single-direction layouts
• Container - For constraining grid width
• Card - Common grid item component

@Heading

A semantic heading component that establishes clear visual hierarchy and structure in your content through flexible typography options. Headings are fundamental to web accessibility and SEO, providing both visual and semantic structure that helps users and search engines understand content organization. This component automatically renders the appropriate HTML heading element (h1-h6) based on the specified level while allowing complete control over visual appearance through size overrides, weight adjustments, and color options. Special features like gradient text effects enable eye-catching headlines that maintain readability and accessibility standards.

Props

• level::Int: Heading level (1-6) (default: 1)
• size::Union{Symbol,String,Nothing}: Override size (:xs, :sm, :base, :lg, :xl, "2xl", "3xl", "4xl", "5xl", "6xl") (optional)
• weight::Union{Symbol,String}: Font weight (:light, :normal, :medium, :semibold, :bold, :extrabold) (default: :bold)
• color::Union{String,Nothing}: Text color class (optional)
• gradient::Bool: Whether to use gradient text effect (default: false)
• tracking::Union{Symbol,String}: Letter spacing (:tight, :normal, :wide) (default: :tight)

Slots

• Heading text content

Example

# Basic headings
@Heading "Welcome to Our Site"
@Heading {level = 2} "About Us"
@Heading {level = 3, weight = :medium} "Our Services"

# Gradient heading
@Heading {gradient = true} "Amazing Features"

# Custom sized heading
@Heading {level = 2, size = "4xl"} "Large Subheading"

# Colored heading
@Heading {level = 4, color = "text-blue-600 dark:text-blue-400"} "Blue Heading"

See also

• Text - For body text
• Link - For hyperlinks
• Badge - For small labels

@Icon

A flexible icon component that supports both built-in icons and custom SVG content. Icons are essential visual elements that enhance user interfaces by providing quick visual recognition of actions, states, and categories. This component offers a comprehensive library of built-in icons covering common UI needs, while also allowing custom SVG content for specialized requirements. With consistent sizing options and color inheritance, icons integrate seamlessly into buttons, links, navigation elements, and standalone contexts. The component ensures proper accessibility through ARIA attributes, making icons work well for both decorative and interactive purposes.

Props

• size::Union{Symbol,String}: Icon size (:xs, :sm, :md, :lg, :xl) (default: :md)
• color::Union{String,Nothing}: Icon color class (optional)
• name::Union{String,Nothing}: Icon name for built-in icons (optional)
• aria_label::Union{String,Nothing}: ARIA label for interactive icons (optional)
• decorative::Bool: Whether icon is purely decorative (default: true)

Slots

• Custom SVG content - used when name prop is not provided or when the named icon is not found

Available Icons

Icons are loaded from SVG files in the assets/icons/ directory. Available icons include:

• Navigation: home, arrow-up/down/left/right, chevron-up/down/left/right, external-link
• Actions: edit, trash, save, download, upload, copy, refresh
• Communication: mail, phone, chat
• Media: play, pause, stop, camera, image
• Status: info, info-circle, warning, exclamation-triangle, error, x-circle, question, bell, check-circle
• Files: file, document, code
• UI Controls: filter, sort, grid, list, eye, eye-off, lock, unlock
• Time: calendar, clock
• E-commerce: cart, credit-card, tag
• Social: heart, star, bookmark, share
• UI: check, x, plus, minus, menu, search, user, settings, logout, folder, dots-vertical, dots-horizontal, spinner

Example

# Using a built-in icon
@Icon {name = "check", size = :lg}
@Icon {name = "heart", color = "text-red-500"}

# Interactive icon with ARIA label
@Icon {name = "trash", aria_label = "Delete item", decorative = false}

# Custom SVG icon
@Icon {size = :xl, color = "text-purple-500"} begin
    @svg {viewBox = "0 0 24 24", fill = "currentColor"} begin
        @path {d = "M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z"}
    end
end

# Fallback when icon not found
@Icon {name = "nonexistent"} begin
    @text "?"  # Fallback content
end

See also

• Button - Commonly used with icons
• Link - For icon links
• Badge - Can contain icons
• DropdownItem - Supports icon props

@Input

A styled text input field for collecting user input with support for various types (text, email, password, number). Features different states (default, error, success), optional icons, and full accessibility with smooth focus transitions.

Props

• type::String: Input type (default: "text")
• size::Union{Symbol,String}: Input size (:xs, :sm, :base, :lg, :xl) (default: :base)
• state::Union{Symbol,String}: Input state (:default, :error, :success) (default: :default)
• icon::Union{String,Nothing}: Icon HTML to display (optional)
• placeholder::Union{String,Nothing}: Placeholder text (optional)
• name::Union{String,Nothing}: Input name attribute (optional)
• value::Union{String,Nothing}: Input value (optional)
• required::Bool: Whether input is required (default: false)
• disabled::Bool: Whether input is disabled (default: false)
• id::Union{String,Nothing}: Input ID for label association (optional)
• aria_describedby::Union{String,Nothing}: ID of element describing the input (optional)

Accessibility

This component implements comprehensive form accessibility standards:

ARIA Patterns:

• Uses aria-invalid="true" for error states to communicate validation status
• Supports aria-describedby for associating help text or error messages
• Maintains proper input semantics with appropriate type attributes
• Required fields are marked with HTML required attribute

Keyboard Navigation:

• Tab: Moves focus to input field
• Shift+Tab: Moves focus to previous element
• Enter: Submits form (for most input types)
• All keyboard input works as expected for each input type

Screen Reader Support:

• Input purpose is communicated through type, name, and placeholder
• Error states are announced through aria-invalid and associated descriptions
• Required status is communicated to assistive technology
• Icon content is properly marked as decorative or informative

Form Integration:

• Inputs should be associated with labels using for/id relationships
• Error messages should be linked via aria-describedby
• Help text should be associated with input for context
• Fieldsets and legends should group related inputs

Visual Design:

• Focus indicators are clearly visible with high contrast
• Error states use both color and other visual indicators
• Sufficient color contrast maintained across all states (4.5:1 minimum)
• Icons and decorative elements don't interfere with screen readers

@Link

A styled anchor component that creates consistent, accessible hyperlinks with smooth hover effects and proper visual feedback. Links are critical navigation elements that connect pages and resources, requiring careful attention to usability, accessibility, and visual design. This component enhances standard HTML anchors with customizable styling variants, automatic handling of external links with security attributes, and smooth color transitions that provide clear interactive feedback. It maintains proper focus states for keyboard navigation and supports integration with icons for enhanced visual communication while ensuring links remain distinguishable and accessible to all users.

Props

• href::String: Link destination (required)
• variant::Union{Symbol,String}: Link variant (:default, :underline, :hover_underline) (default: :default)
• color::Union{String,Nothing}: Text color class (optional)
• external::Bool: Whether this is an external link (adds target="_blank") (default: false)
• aria_label::Union{String,Nothing}: ARIA label for additional context (optional)

Slots

• Link text or content

Example

# Basic link
@Link {href = "/about"} "About Us"

# External link
@Link {href = "https://example.com", external = true} "Visit Example.com"

# Underlined link
@Link {href = "/contact", variant = :underline} "Contact Us"

# Custom colored link
@Link {href = "/products", color = "text-purple-600 hover:text-purple-700"} "Our Products"

# Link with icon
@Link {href = "/download"} begin
    @Icon {name = "download", size = :sm}
    @text " Download PDF"
end

See also

• Button - For button-style links
• Text - For regular text
• Heading - For heading text
• Icon - For link icons

@List

A styled list component that enhances standard HTML lists with consistent visual design and flexible presentation options. Lists are essential for presenting sequential or related information in a scannable format, from simple bullet points to numbered steps or checklists. This component offers multiple variants including traditional bullets, numbers, checkmarks, or no markers at all, combined with adjustable spacing to suit different content densities. The styling is carefully crafted to maintain readability while providing visual interest through custom markers and proper indentation.

Props

• variant::Union{Symbol,String}: List variant (:bullet, :number, :check, :none) (default: :bullet)
• spacing::Union{Symbol,String}: Item spacing (:tight, :normal, :loose) (default: :normal)

Slots

• List items - should contain li elements

Example

# Bulleted list
@List begin
    @li "First item"
    @li "Second item"
    @li "Third item"
end

# Numbered list
@List {variant = :number} begin
    @li "Step one"
    @li "Step two"
    @li "Step three"
end

# Checklist with loose spacing
@List {variant = :check, spacing = :loose} begin
    @li "Task completed"
    @li "Another completed task"
    @li "Final task done"
end

See also

• Table - For tabular data
• Timeline - For chronological lists
• Stack - For custom list layouts

@Modal

A modal dialog component built on the native HTML <dialog> element with enhanced functionality for displaying content that requires user attention while temporarily blocking page interaction.

Props

• id::String: Unique identifier for the modal (optional, auto-generated if not provided)
• size::Union{Symbol,String}: Modal size (:sm, :md, :lg, :xl, :fullscreen) (default: :md)
• persistent::Bool: Prevent closing on backdrop click (default: false)
• show_close::Bool: Show close button in top-right (default: true)

Slots

• Modal content - typically contains ModalHeader, ModalContent, and ModalFooter components

Example

# Basic modal with trigger
@ModalTrigger {target = "example-modal"} begin
    @Button "Open Modal"
end

@Modal {id = "example-modal"} begin
    @ModalHeader "Dialog Title"
    @ModalContent begin
        @Text "Modal content goes here."
    end
    @ModalFooter begin
        @Button {var"@click" = "close()"} "Close"
    end
end

# Persistent modal (no backdrop close)
@Modal {id = "persistent-modal", persistent = true} begin
    @ModalContent "This modal requires explicit close action."
end

# Large modal without close button
@Modal {id = "large-modal", size = :lg, show_close = false} begin
    @ModalContent "Large modal content."
end

Accessibility

ARIA: Uses native <dialog> semantics with automatic focus trapping and keyboard navigation.

Keyboard: Escape key closes modal, Tab cycles through focusable elements, Enter activates buttons.

Focus Management: Automatically focuses first interactive element on open, returns focus to trigger on close.

Screen Reader: Native dialog role and content are properly announced.

See also

• ModalTrigger - Button to open modals
• ModalContent - Modal body content
• ModalHeader - Modal header with title
• ModalFooter - Modal footer with actions
• DrawerModal - Slide-in drawer variant

Note: Requires Alpine.js for enhanced functionality. Browser support: Chrome 37+, Firefox 98+, Safari 15.4+. JavaScript assets are loaded automatically.

@ModalContent

The main content area of a modal dialog, providing proper spacing and scrolling behavior for body content.

Props

• scrollable::Bool: Allow content to scroll if it exceeds modal height (default: true)

Slots

• Modal body content - any components, text, forms, or other elements

Example

@Modal {id = "example"} begin
    @ModalContent begin
        @Text "Your modal content here."
        @Text "Can include multiple paragraphs."
    end
end

# Non-scrollable content
@ModalContent {scrollable = false} begin
    @Text "Fixed height content."
end

See also

• Modal - Parent modal component
• ModalHeader - Modal header section
• ModalFooter - Modal footer section

@ModalFooter

A footer section for modal dialogs containing action buttons with consistent styling and flexible layout options.

Props

• justify::Union{Symbol,String}: Button alignment (:start, :center, :end, :between) (default: :end)

Slots

• Footer content - typically buttons or button groups

Example

@ModalFooter begin
    @Button {variant = :secondary, var"@click" = "close()"} "Cancel"
    @Button {variant = :primary} "Save Changes"
end

# Center-aligned buttons
@ModalFooter {justify = :center} begin
    @Button "Understood"
end

# Space-between layout
@ModalFooter {justify = :between} begin
    @Button {variant = :ghost} "Learn More"
    @div {class = "space-x-3"} begin
        @Button {variant = :secondary} "Cancel"
        @Button {variant = :primary} "Continue"
    end
end

See also

• Modal - Parent modal component
• ModalHeader - Modal header section
• ModalContent - Modal body section
• Button - Action buttons for footer

@ModalHeader

A header section for modal dialogs containing the title and optional subtitle with consistent styling and spacing.

Props

• subtitle::Union{String,Nothing}: Optional subtitle text (default: nothing)

Slots

• Header content - typically plain text for title, or custom elements

Example

@ModalHeader "Confirm Action"

@ModalHeader {subtitle = "This action cannot be undone"} "Delete Item"

# Custom header content
@ModalHeader begin
    @Heading {level = 2} "Custom Header"
    @Badge {variant = :warning} "Beta"
end

See also

• Modal - Parent modal component
• ModalContent - Modal body section
• ModalFooter - Modal footer section

@ModalTrigger

A button component that opens a modal dialog when clicked, inheriting all standard Button functionality with added modal triggering capability.

Props

• target::String: ID of the modal to open (required)
• variant::Union{Symbol,String}: Button variant (default: :secondary)
• size::Union{Symbol,String}: Button size (default: :base)
• All other standard Button props (disabled, loading, etc.)

Slots

• Button content - text, icons, or other elements

Example

@ModalTrigger {target = "my-modal", variant = :primary} "Open Modal"

@ModalTrigger {target = "confirm-dialog", variant = :danger, size = :sm} "Delete Item"

# With icon
@ModalTrigger {target = "settings-modal"} begin
    @Icon {name = "cog"}
    @text " Settings"
end

Accessibility

ARIA: Uses aria-haspopup="dialog" and aria-controls to indicate modal relationship.

Keyboard: Enter and Space activate the trigger, same as standard button behavior.

See also

• Modal - The modal component to trigger
• Button - Base button component with all available props

@Pagination

A page navigation component that provides intuitive controls for navigating through paginated content. Pagination is essential for managing large datasets by breaking them into digestible chunks, improving both performance and user experience. This component intelligently displays page numbers with ellipsis for large ranges, always shows first and last pages, and includes previous/next navigation buttons. It handles edge cases like disabled states at boundaries and provides proper ARIA labels for screen reader users. The responsive design ensures the pagination remains usable on mobile devices.

Props

• current::Int: Current page number (default: 1)
• total::Int: Total number of pages (default: 1)
• siblings::Int: Number of sibling pages to show (default: 1)
• base_url::String: Base URL for page links (default: "#")

Accessibility

ARIA: Uses <nav aria-label="Pagination"> with aria-current="page" and aria-disabled for states.

Keyboard: Tab through pagination controls, Enter activates navigation. Disabled controls are skipped.

Screen Reader: Current page and button states are announced with positional context.

Guidelines: Provide meaningful URLs, consider mobile behavior, include page count context.

@Progress

A modern progress bar component that visually represents the completion status of a task or process. Progress bars provide essential feedback during operations like file uploads, form submissions, or multi-step workflows, helping users understand how much has been completed and how much remains. This component supports various visual styles including solid colors and gradients, optional striped patterns for visual interest, and smooth animations that bring the interface to life. Labels can be added to show exact percentages or descriptive text.

Props

• value::Int: Current progress value (default: 0)
• max::Int: Maximum progress value (default: 100)
• size::Union{Symbol,String}: Progress bar size (:sm, :md, :lg) (default: :md)
• color::Union{Symbol,String}: Progress bar color (:primary, :success, :warning, :danger, :gradient) (default: :primary)
• striped::Bool: Whether to show striped pattern (default: false)
• animated::Bool: Whether to animate the stripes (default: false)
• animated_fill::Bool: Whether to animate the progress fill on load (default: false)
• label::Union{String,Nothing}: Label to display (optional)
• aria_label::Union{String,Nothing}: ARIA label for screen readers (optional)

Interactive Features

When animated_fill=true, this component uses Alpine.js for smooth fill animation on load. To enable interactivity, include Alpine.js in your page:

@script {defer=true, src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"}

Without Alpine.js, the progress bar will display at its final value without animation.

@Radio

A radio button component that enables users to select a single option from a group of mutually exclusive choices. Radio buttons are ideal when you want to present all available options upfront and ensure users can only select one. This component renders a complete radio group with proper ARIA attributes and keyboard navigation support. Each option can include a label, and the entire group maintains visual consistency with other form elements while providing clear feedback about the selected state.

Props

• size::Union{Symbol,String}: Radio size (:sm, :md, :lg) (default: :md)
• color::Union{Symbol,String}: Radio color (:slate, :primary, :success) (default: :primary)
• options::Vector{Tuple{String,String}}: Options as (value, label) tuples
• name::String: Radio group name (required)
• value::Union{String,Nothing}: Selected value (optional)
• required::Bool: Whether radio group is required (default: false)
• disabled::Bool: Whether radio group is disabled (default: false)

@Section

A semantic section component with consistent vertical spacing for page structure. Section provides a standardized way to divide your page into distinct content areas with appropriate padding and optional background colors. It helps maintain visual hierarchy and breathing room between different parts of your page, making it perfect for hero sections, feature showcases, content blocks, and any logical grouping of related information.

Props

• spacing::Union{Symbol,String}: Vertical spacing size (:sm, :md, :lg) (default: :md)
• background::Union{String,Nothing}: Background color class (optional)

Slots

• Section content

Example

# Hero section
@Section {spacing = :lg, background = "bg-gray-50 dark:bg-gray-900"} begin
    @Container begin
        @Heading {level = 1} "Welcome to our site"
        @Text {variant = :lead} "Discover amazing features"
    end
end

# Content section
@Section begin
    @Container begin
        @Grid {cols = 1, md = 2} begin
            @div "Feature 1"
            @div "Feature 2"
        end
    end
end

See also

• Container - For constraining content within sections
• Stack - For organizing section content
• Grid - For section grid layouts

@Select

A dropdown select element that allows users to choose from a predefined list of options. Select components are essential for forms where users need to pick from a constrained set of choices, providing a cleaner interface than radio buttons when dealing with many options. This implementation features a custom-styled dropdown arrow for consistency across browsers, support for placeholder text, and full integration with form validation states. The component maintains accessibility standards while offering a modern appearance.

Props

• size::Union{Symbol,String}: Select size (:xs, :sm, :base, :lg, :xl) (default: :base)
• state::Union{Symbol,String}: Select state (:default, :error, :success) (default: :default)
• options::Vector{Tuple{String,String}}: Options as (value, label) tuples
• placeholder::Union{String,Nothing}: Placeholder option text (optional)
• name::Union{String,Nothing}: Select name attribute (optional)
• value::Union{String,Nothing}: Selected value (optional)
• required::Bool: Whether select is required (default: false)
• disabled::Bool: Whether select is disabled (default: false)
• id::Union{String,Nothing}: Select ID for label association (optional)
• aria_describedby::Union{String,Nothing}: ID of element describing the select (optional)

@SelectDropdown

An enhanced dropdown select component with search functionality, keyboard navigation, and multiple selection support. Features type-ahead search, clear buttons, and full accessibility with Alpine.js integration.

Props

• options::Vector{Tuple{String,String}}: Options as (value, label) tuples
• placeholder::Union{String,Nothing}: Placeholder text (default: "Select...")
• searchable::Bool: Enable search functionality (default: false)
• multiple::Bool: Enable multiple selection (default: false)
• clearable::Bool: Enable clear button to reset selection (default: false)
• max_height::String: Maximum height of dropdown (default: "300px")
• size::Union{Symbol,String}: Component size (:xs, :sm, :base, :lg, :xl) (default: :base)
• state::Union{Symbol,String}: Component state (:default, :error, :success) (default: :default)
• name::Union{String,Nothing}: Form field name (optional)
• value::Union{String,Vector{String},Nothing}: Selected value(s) (optional)
• disabled::Bool: Whether component is disabled (default: false)
• required::Bool: Whether field is required (default: false)
• id::Union{String,Nothing}: Component ID (optional)

Requirements

This component requires Alpine.js and Alpine Anchor for intelligent positioning:

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/anchor@latest/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are automatically loaded via @__once__ for optimal performance.

Accessibility

ARIA Patterns: Uses role="listbox" with proper option roles, aria-expanded state, and aria-selected for selections.

Keyboard Navigation: Space/Enter to open, Arrow keys to navigate, Escape to close, type-ahead search support.

Screen Reader Support: Selection changes, option count, and search functionality are announced. Works with form validation.

Visual Design: High contrast focus indicators and touch-friendly spacing on mobile devices.

@Spinner

A loading spinner component that provides visual feedback during asynchronous operations. Spinners are crucial for maintaining user engagement during loading states, preventing users from thinking the application has frozen or crashed. This simple yet effective component uses smooth rotation animation and comes in multiple sizes and colors to fit various contexts, from small inline loading indicators to full-page loading states. The spinner automatically includes proper ARIA attributes for accessibility.

Props

• size::Union{Symbol,String}: Spinner size (:sm, :md, :lg) (default: :md)
• color::Union{Symbol,String}: Spinner color (:slate, :primary, :white) (default: :primary)

@Stack

A flexible stack component for arranging child elements with consistent spacing in vertical or horizontal layouts. Stack simplifies the common pattern of placing elements in a row or column with uniform gaps between them, eliminating the need for manual margin management. It's particularly useful for creating button groups, form layouts, card arrangements, and any scenario where you need predictable spacing between a series of elements.

Props

• direction::Union{Symbol,String}: Stack direction (:vertical or :horizontal) (default: :vertical)
• gap::Union{Symbol,String,Int}: Gap size using Tailwind spacing scale or preset (:xs, :sm, :base, :lg, :xl) (default: 4)
• align::Union{Symbol,String}: Alignment (:start, :center, :end, :stretch) (default: :stretch)
• justify::Union{Symbol,String}: Justification (:start, :center, :end, :between, :around, :evenly) (default: :start)
• wrap::Bool: Whether items should wrap (default: false)

Slots

• Child elements to be stacked with automatic spacing

Example

# Vertical stack with cards
@Stack {gap = :lg} begin
    @Card "First item"
    @Card "Second item"
    @Card "Third item"
end

# Horizontal button group
@Stack {direction = :horizontal, gap = :sm} begin
    @Button "Save"
    @Button {variant = :secondary} "Cancel"
end

See also

• Grid - For multi-column layouts
• Container - For constraining content width
• Card - Common child component for stacks

@TabPanel

A tab panel component designed to work seamlessly within the Tabs container, automatically handling content visibility based on the active tab selection. Each TabPanel represents a distinct content section that appears when its corresponding tab is selected. The component manages smooth transitions between panels using Alpine.js, ensuring a polished user experience. It maintains proper ARIA relationships with tab buttons for accessibility and supports any type of content, from simple text to complex nested components.

Props

• id::String: The tab ID this panel corresponds to (required)
• class::String: Additional CSS classes (optional)

Slots

• Tab panel content - can contain any elements that should be displayed when this tab is active

Usage

@Tabs {items = [("tab1", "Tab 1"), ("tab2", "Tab 2")]} begin
    @TabPanel {id = "tab1"} begin
        @Text "Content for Tab 1"
    end

    @TabPanel {id = "tab2"} begin
        @Text "Content for Tab 2"
    end
end

Accessibility

ARIA: Uses role="tabpanel" with proper aria-controls/id relationships.

Keyboard: Normal tab order through panel content, Shift+Tab returns to tab button.

Guidelines: Panel content should start with a heading for structure.

See also

• Tabs - Parent tabs container

@Table

A responsive data table component for displaying structured data with extensive customization options. Features striped rows, hover effects, sticky headers, sortable columns, and full accessibility support.

Props

• striped::Bool: Whether to show striped rows (default: false)
• bordered::Bool: Whether to show borders (default: true)
• hover::Bool: Whether to show hover effect on rows (default: true)
• compact::Bool: Whether to use compact spacing (default: false)
• sticky_header::Bool: Whether table header should be sticky (default: false)
• sortable::Bool: Whether to show sortable column indicators (default: false)
• caption::Union{String,Nothing}: Table caption/description (optional)
• overflow::Bool: Whether to apply overflow scrolling (default: true). Set to false when table contains dropdowns or other overlaying elements

Slots

• Table content - should contain standard HTML table elements (thead, tbody, tr, th, td)

Example

# Basic table
@Table begin
    @thead begin
        @tr begin
            @th "Name"
            @th "Email"
            @th "Role"
        end
    end
    @tbody begin
        @tr begin
            @td "John Doe"
            @td "john@example.com"
            @td "Admin"
        end
        @tr begin
            @td "Jane Smith"
            @td "jane@example.com"
            @td "User"
        end
    end
end

# Striped table with sticky header
@Table {striped = true, sticky_header = true, caption = "User list"} begin
    @thead begin
        @tr begin
            @th "ID"
            @th "Username"
            @th "Status"
        end
    end
    @tbody begin
        # Table rows...
    end
end

Accessibility

Semantic Markup: Uses proper <table>, <thead>, <tbody>, <th>, and <td> elements with scope attributes.

Screen Readers: Table structure, captions, and header relationships are announced to assistive technology.

Keyboard Navigation: Tab through any interactive elements within table cells.

Guidelines: Provide meaningful captions, clear column headers, and consider responsive alternatives for mobile.

See also

• List - For simpler list layouts
• Grid - For card-based data display

@Tabs

An interactive tab navigation component powered by Alpine.js that organizes content into switchable panels. Tabs are powerful UI patterns for presenting related content in a compact space while allowing users to quickly switch between different views. This component manages the active tab state, provides smooth transitions between panels, and ensures proper ARIA attributes for accessibility. The tab interface supports keyboard navigation and maintains the selected state across the session. With customizable styling and responsive behavior, tabs adapt well to different screen sizes and content types.

Props

• items::Vector{Tuple{String,String}}: Tab items as (id, label) tuples
• active::String: ID of the active tab (default: first item's ID)
• aria_label::Union{String,Nothing}: ARIA label for the tab list (optional)

Requirements

This component requires Alpine.js for tab switching functionality:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are loaded automatically via @__once__ for optimal performance.

Usage

@Tabs {items = [("tab1", "Tab 1"), ("tab2", "Tab 2")]} begin
    @TabPanel {id = "tab1"} begin
        @Text "Content for Tab 1"
    end

    @TabPanel {id = "tab2"} begin
        @Text "Content for Tab 2"
    end
end

Accessibility

ARIA: Uses role="tab", role="tablist", and aria-controls with proper aria-selected states.

Keyboard: Arrow Left/Right navigate tabs, Home/End jump to first/last, Tab moves to panel content.

Focus Management: Automatic tab switching follows focus with clear visual indicators.

See also

• TabPanel - Tab content panels
• DropdownMenu - Alternative navigation pattern
• Breadcrumb - For navigation hierarchy

@Text

A paragraph text component that provides consistent typography styling for body content throughout your application. Text components form the foundation of readable interfaces, ensuring that body copy maintains appropriate line heights, spacing, and contrast across different contexts. This versatile component supports multiple variants from small supporting text to prominent lead paragraphs, with fine-grained control over size, weight, color, and alignment. It adapts seamlessly to different screen sizes and color schemes while maintaining optimal readability through carefully chosen typography defaults.

Props

• variant::Union{Symbol,String}: Text variant (:body, :lead, :small) (default: :body)
• size::Union{Symbol,String,Nothing}: Override size (:xs, :sm, :base, :lg, :xl) (optional)
• weight::Union{Symbol,String}: Font weight (:normal, :medium, :semibold, :bold) (default: :normal)
• color::Union{String,Nothing}: Text color class (optional)
• align::Union{Symbol,String}: Text alignment (:left, :center, :right, :justify) (default: :left)

Slots

• Paragraph text content

Example

# Basic paragraph
@Text "This is a regular paragraph of text."

# Lead paragraph
@Text {variant = :lead} "This is a larger, emphasized paragraph often used for introductions."

# Small text
@Text {variant = :small, color = "text-gray-600"} "This is smaller supporting text."

# Centered bold text
@Text {align = :center, weight = :bold} "Centered bold statement"

# Custom styled text
@Text {size = :lg, weight = :medium} "Custom sized medium weight text"

See also

• Heading - For headings
• Link - For inline links
• Alert - For notification text

@Textarea

A multi-line text input component designed for longer form content like comments, descriptions, or messages. Textareas expand on the functionality of regular inputs by allowing multiple lines of text and providing resize controls for user convenience. They maintain visual consistency with other form elements while offering additional features like customizable row counts and resize behavior. The component includes the same state management and theming capabilities as other form inputs, ensuring a seamless form experience.

Props

• rows::Int: Number of visible rows (default: 4)
• resize::Union{Symbol,String}: Resize behavior (:none, :vertical, :horizontal, :both) (default: :vertical)
• state::Union{Symbol,String}: Input state (:default, :error, :success) (default: :default)
• placeholder::Union{String,Nothing}: Placeholder text (optional)
• name::Union{String,Nothing}: Textarea name attribute (optional)
• value::Union{String,Nothing}: Textarea value (optional)
• required::Bool: Whether textarea is required (default: false)
• disabled::Bool: Whether textarea is disabled (default: false)
• id::Union{String,Nothing}: Textarea ID for label association (optional)
• aria_describedby::Union{String,Nothing}: ID of element describing the textarea (optional)

@ThemeToggle

A theme toggle button component that enables users to switch between light, dark, and system-based color schemes with a single click. Theme toggles have become essential for modern web applications, respecting user preferences and improving accessibility for users who need specific contrast levels or reduced eye strain. This component provides a smooth cycling through theme options with visual feedback, remembers user preferences across sessions, and integrates with system-level theme settings. The button adapts its appearance to the current theme and provides clear indication of the active mode through both icons and optional text labels.

Props

• id::String: HTML id for the button (default: "theme-toggle")
• variant::Union{Symbol,String}: Button variant style (:default, :ghost, :outline) (default: :default)
• size::Union{Symbol,String}: Button size (:sm, :md, :lg) (default: :md)
• show_label::Bool: Whether to show text label alongside icon (default: true)
• class::String: Additional CSS classes (optional)

Example

@ThemeToggle {}
@ThemeToggle {variant = :ghost, size = :sm, show_label = false}

Requirements

This component requires Alpine.js to be included in your page:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are automatically loaded via @__once__ for optimal performance.

Accessibility

This component implements comprehensive accessibility for theme switching:

ARIA Patterns:

• Uses semantic <button> element with descriptive title attribute
• Button text dynamically updates to reflect current theme state
• Screen readers announce theme changes when selection occurs
• Maintains button semantics while providing theme functionality

Keyboard Navigation:

• Enter/Space: Cycles through theme options (light → dark → system)
• Tab: Moves focus to theme toggle button
• Shift+Tab: Moves focus to previous element
• All theme switching is accessible via keyboard

Screen Reader Support:

• Current theme state is announced through button text
• Theme changes are communicated when they occur
• Button purpose is clear through descriptive labeling
• Icon-only mode includes screen reader text for context

Visual Design:

• Focus indicators are clearly visible with high contrast
• Button variants maintain sufficient color contrast (4.5:1 minimum)
• Theme icons provide visual feedback for current state
• Hover and active states give clear interactive feedback

Theme Persistence:

• Theme preference is stored in localStorage for consistency
• System theme preference is respected and monitored
• Theme changes are applied immediately for visual feedback
• Works across browser sessions and page refreshes

Usage Guidelines:

• Place theme toggle in consistent, discoverable location
• Consider using icon + text for maximum clarity
• Test with all three theme states (light, dark, system)
• Ensure theme toggle itself is visible in all themes

@Timeline

A container component for displaying chronological events in an elegant timeline layout. Timelines are powerful visualization tools for presenting sequences of events, project milestones, or historical progressions in an intuitive, linear format. This component provides the structural foundation for timeline displays, supporting both vertical and horizontal orientations with optional connecting lines between events. It handles the complex positioning and alignment requirements while maintaining a clean, scannable interface that helps users understand temporal relationships and progress at a glance.

Props

• variant::Union{Symbol,String}: Timeline variant (:vertical, :horizontal) (default: :vertical)
• connector::Bool: Whether to show connecting lines between items (default: true)
• alternate::Bool: Whether to alternate items on left/right sides (horizontal only) (default: false)

Slots

• Timeline items - should contain @TimelineItem components

Example

@Timeline begin
    @TimelineItem {icon = "1", icon_bg = "bg-blue-500"} begin
        @TimelineContent {title = "Project Started", subtitle = "January 2024"} begin
            @Text "Initial planning and setup phase."
        end
    end
    @TimelineItem {icon = "2", icon_bg = "bg-green-500"} begin
        @TimelineContent {title = "Development Phase", subtitle = "March 2024"} begin
            @Text "Core features implemented."
        end
    end
    @TimelineItem {icon = "✓", icon_bg = "bg-purple-500", last = true} begin
        @TimelineContent {title = "Launch", subtitle = "June 2024"} begin
            @Text "Product successfully launched!"
        end
    end
end

See also

• TimelineItem - Individual timeline entries
• TimelineContent - Content wrapper for timeline items

@TimelineContent

A content wrapper for timeline items that provides consistent styling and structure for the information associated with each timeline event. This component ensures that timeline content maintains visual coherence whether displaying simple text updates or rich media content. It offers optional card styling for enhanced visual separation, built-in support for titles and timestamps, and flexible content areas that can accommodate various types of information. The wrapper handles responsive behavior and maintains proper alignment with timeline markers, creating a polished presentation that guides users through chronological narratives.

Props

• title::Union{String,Nothing}: Title text (optional)
• subtitle::Union{String,Nothing}: Subtitle or timestamp (optional)
• card::Bool: Whether to wrap content in a card (default: true)

Slots

• Content body - the main content of the timeline entry

Example

@TimelineContent {title = "Milestone Achieved", subtitle = "Q2 2024"} begin
    @Text "Successfully completed the first phase of the project."
    @Stack {direction = :horizontal, gap = :sm} begin
        @Badge {variant = :success} "On Time"
        @Badge {variant = :primary} "Under Budget"
    end
end

# Without card styling
@TimelineContent {card = false} begin
    @Text {variant = :small} "Quick update: Everything is on track."
end

See also

• Timeline - Parent timeline container
• TimelineItem - Timeline entry wrapper
• Card - Related card styling

@TimelineItem

An individual event or milestone in a timeline that represents a specific point in time or achievement. Timeline items are the building blocks of any timeline display, each marking a significant moment with optional visual indicators and connecting lines to adjacent events. This component provides flexible customization through icon markers with customizable backgrounds, automatic connector lines for visual continuity, and proper spacing to maintain timeline flow. Items can represent anything from project phases to historical events, with the visual design emphasizing both the discrete nature of each event and its relationship to the whole sequence.

Props

• icon::Union{String,Nothing}: Content for the timeline marker (optional)
• icon_bg::Union{String,Nothing}: Background color class for the icon (default: "bg-blue-500")
• connector::Bool: Whether to show connector line to next item (default: true)
• last::Bool: Whether this is the last item (disables connector) (default: false)

Slots

• Timeline item content - typically contains @TimelineContent component

Example

@TimelineItem {icon = "🚀"} begin
    @TimelineContent {title = "Launch Day"} begin
        @Text "We're going live!"
    end
end

See also

• Timeline - Parent timeline container
• TimelineContent - Content wrapper component

@Toggle

A versatile toggle component that provides both switch and button variants for binary on/off states. The switch variant offers an iOS-style sliding toggle for settings and preferences, while the button variant creates toggleable buttons perfect for toolbars and multi-select interfaces. Both variants support keyboard navigation, proper ARIA attributes, and can include icons to enhance visual communication.

Props

• variant::Union{Symbol,String}: Toggle variant (:switch, :button) (default: :switch)
• size::Union{Symbol,String}: Component size (:xs, :sm, :base, :lg, :xl) (default: :base)
• color::Union{Symbol,String}: Color scheme (:primary, :success, :danger) (default: :primary)
• label::Union{String,Nothing}: Label text for switch variant (optional)
• name::Union{String,Nothing}: Form field name (optional)
• value::Union{String,Nothing}: Form field value (optional)
• checked::Bool: Whether toggle is checked/active (default: false)
• disabled::Bool: Whether toggle is disabled (default: false)
• required::Bool: Whether field is required (default: false)
• id::Union{String,Nothing}: Component ID (optional)
• aria_describedby::Union{String,Nothing}: ID of describing element (optional)
• show_icons::Bool: Show icon slots for switch variant (default: false)

Slots

For switch variant with show_icons = true:

• icon_on: Icon content to display when toggle is on
• icon_off: Icon content to display when toggle is off

For button variant:

• Default slot: Button content (text, icons, or both)

Examples

# Basic switch toggle
@Toggle {label = "Enable notifications", name = "notifications"}

# Switch with custom icons
@Toggle {label = "Theme", show_icons = true, name = "theme"} begin
    icon_on := @Icon {name = "moon", size = :xs}
    icon_off := @Icon {name = "sun", size = :xs}
end

# Button toggle for toolbar
@Toggle {variant = :button, name = "bold"} begin
    @strong "B"
end

# Icon button toggle
@Toggle {variant = :button, name = "favorite", color = :danger} begin
    @Icon {name = "heart"}
end

Accessibility

This component implements comprehensive accessibility for toggle controls:

ARIA Patterns:

• Switch variant uses role="switch" with aria-checked state
• Button variant uses aria-pressed to indicate toggle state
• Labels are properly associated with controls
• Disabled state is communicated through aria-disabled

Keyboard Navigation:

• Space/Enter: Toggles the state
• Tab: Moves focus to/from the toggle
• All keyboard interactions work identically to native controls

Screen Reader Support:

• State changes are announced immediately
• Labels provide context for the toggle purpose
• Icon-only button toggles should include descriptive text or aria-label

Visual Design:

• Focus indicators are clearly visible with appropriate contrast
• Toggle states are communicated through multiple visual cues
• Color is not the sole indicator of state
• Smooth transitions provide visual feedback for interactions

@Tooltip

A simple tooltip component that displays contextual information on hover or focus with intelligent positioning. Features customizable delays, smooth animations, and automatic positioning using Alpine Anchor with dark and light variants.

Props

• text::String: The tooltip text to display (required)
• placement::Union{Symbol,String}: Tooltip placement (:top, :bottom, :left, :right) (default: :top)
• delay::Int: Show delay in milliseconds (default: 500)
• hide_delay::Int: Hide delay in milliseconds (default: 0)
• offset::Int: Distance from trigger in pixels (default: 8)
• variant::Union{Symbol,String}: Visual style (:dark, :light) (default: :dark)
• size::Union{Symbol,String}: Text size (:sm, :base) (default: :sm)
• max_width::String: Maximum width of tooltip (default: "250px")
• class::String: Additional CSS classes (optional)

Slots

• Trigger element - the element that shows the tooltip on hover

Example

# Icon with tooltip
@Tooltip {text = "Delete this item"} begin
    @Button {variant = :danger, size = :sm} begin
        @Icon {name = "trash"}
    end
end

# Text with tooltip
@Tooltip {text = "Click to learn more about this feature"} begin
    @Link {href = "/help"} "What's this?"
end

# Badge with light tooltip
@Tooltip {text = "Premium features included", variant = :light} begin
    @Badge {variant = :gradient} "PRO"
end

Requirements

This component requires Alpine.js and Alpine Anchor for intelligent positioning:

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/anchor@latest/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are automatically loaded via @__once__ for optimal performance.

Accessibility

ARIA: Uses role="tooltip" with aria-describedby relationship to trigger element.

Keyboard: Escape dismisses, Tab moves focus away. Appears on both hover and focus events.

Focus Management: Non-interactive tooltip keeps focus on trigger element.

See also

• TooltipWrapper - For rich tooltip content
• Alert - For persistent help messages
• Badge - Common tooltip trigger

@TooltipContent

The content component within TooltipWrapper that defines tooltip popup content with rich formatting support. Can contain any HTML content including headings, lists, images, or interactive elements with consistent styling and smooth transitions.

Props

• variant::Union{Symbol,String}: Visual style (:dark, :light) (default: :dark)
• arrow::Bool: Show arrow pointing to trigger (default: true)
• max_width::String: Maximum width (default: "300px")
• class::String: Additional CSS classes (optional)
• attrs...: Additional attributes

Slots

• Tooltip content - can contain any components or rich formatting

Example

@TooltipContent {variant = :light} begin
    @Stack {gap = :sm} begin
        @Heading {level = 5} "Tooltip Title"
        @Text {size = :sm} "This tooltip can contain any content."
        @Stack {direction = :horizontal, gap = :xs} begin
            @Badge "Tag 1"
            @Badge "Tag 2"
        end
    end
end

Accessibility

ARIA: Uses role="tooltip" while preserving rich content structure for assistive technology.

Keyboard: Interactive content is accessible with Tab navigation, Escape dismisses.

Guidelines: Use headings for structure, ensure proper labels, maintain color contrast.

See also

• TooltipWrapper - Parent wrapper component
• TooltipTrigger - Trigger component
• Card - For similar content styling

@TooltipTrigger

The trigger element within TooltipWrapper that activates tooltip display. Acts as a transparent wrapper for any element, handling event bindings and ARIA attributes while maintaining original functionality.

Props

• class::String: Additional CSS classes (optional)
• attrs...: Additional attributes

Slots

• Trigger element - any element that should show the tooltip when interacted with

Example

@TooltipTrigger begin
    @Button {variant = :ghost} "Hover me"
end

Accessibility

ARIA: Maintains semantic relationship with tooltip while preserving original element accessibility.

Keyboard: Enter/Space shows tooltip, Escape dismisses, Tab for normal behavior.

Guidelines: Works with any trigger element type while maintaining original functionality.

See also

• TooltipWrapper - Parent wrapper component
• TooltipContent - Tooltip content component

@TooltipWrapper

A wrapper component for rich, interactive tooltips with custom content. Supports different trigger types (hover, click, focus) and interactive tooltip content with proper positioning and accessibility.

Props

• placement::Union{Symbol,String}: Tooltip placement (default: :top)
• delay::Int: Show delay in milliseconds (default: 500)
• hide_delay::Int: Hide delay in milliseconds (default: 0)
• offset::Int: Distance from trigger in pixels (default: 8)
• trigger::Union{Symbol,String}: Trigger type (:hover, :click, :focus) (default: :hover)
• interactive::Bool: Keep open when hovering tooltip content (default: false)

Slots

• Should contain exactly one @TooltipTrigger and one @TooltipContent component

Example

# Interactive tooltip with rich content
@TooltipWrapper {interactive = true} begin
    @TooltipTrigger begin
        @Badge "PRO"
    end
    @TooltipContent {variant = :light} begin
        @Heading {level = 4, size = :sm} "Pro Feature"
        @Text {size = :sm} "Upgrade to access advanced features"
        @Button {size = :sm, variant = :primary} "Upgrade Now"
    end
end

# Click-triggered tooltip
@TooltipWrapper {trigger = :click} begin
    @TooltipTrigger begin
        @Icon {name = "info-circle"}
    end
    @TooltipContent begin
        @Text "Click anywhere to close"
    end
end

Requirements

This component requires Alpine.js and Alpine Anchor for intelligent positioning:

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/anchor@latest/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Browser Compatibility: Modern browsers with ES6 support Dependencies: Tailwind CSS for styling classes

Note: JavaScript assets are automatically loaded via @__once__ for optimal performance.

Accessibility

ARIA & Focus: Proper tooltip roles and ARIA relationships. Interactive tooltips support keyboard navigation with Escape to dismiss.

Content: Rich content (headings, links, buttons) is announced and navigable by screen readers.

Guidelines: Use interactive tooltips sparingly; ensure content is available via other means for mobile users.

See also

• Tooltip - Simple text tooltips
• TooltipTrigger - Trigger component
• TooltipContent - Content component
• DropdownMenu - Alternative for complex interactions