# Aura UI — Full Documentation > Aura UI is a "Vibrant Depth" UI component library for Laravel 12 + Livewire 3/4 + Alpine.js + Tailwind CSS 4. It ships 70+ accessible Blade components (free + Pro), a Filament v4/v5 theme system, dark mode, and CSS-variable theming. Components are used as Blade tags, e.g. , , . Free package: bluestarsystem/aura-ui (MIT). Pro package: bluestarsystem/aura-ui-pro. Filament theme: bluestarsystem/aura-filament. --- --- title: Introduction description: Get started with Aura UI, a beautiful Blade component library for Laravel. --- [TOC] ## What is Aura UI? Aura UI is a comprehensive Blade component library for Laravel applications. It provides a carefully crafted set of UI components that follow the **Vibrant Depth** design language -- combining gradients, soft glows, glass morphism effects, and micro-animations to create interfaces that feel modern and alive. Built on top of Laravel 12, Tailwind CSS 4, and Alpine.js 3, Aura UI offers both anonymous Blade components and Livewire-powered interactive components. Every component is fully accessible, supports dark mode out of the box, and integrates seamlessly with Livewire's `wire:model` directive. ```html Welcome to Aura UI Beautiful components for your Laravel application. Get Started ``` ## Key Features ### 45+ Components From basic primitives like buttons and inputs to advanced interactive components like data tables, command palettes, and kanban boards. Every component you need to build a complete application. ### Vibrant Depth Design A unique design language that goes beyond flat design. Subtle gradients, layered shadows, glass morphism panels, and purposeful micro-animations create depth and visual hierarchy without feeling heavy. ### Dark Mode Built In Every component ships with full dark mode support. Toggle between light and dark themes using a simple Alpine.js data attribute. No extra configuration needed. ### Livewire Integration All form components support `wire:model` out of the box. Pro components include dedicated Livewire traits for data tables, filters, bulk actions, inline editing, and form handling. ### Accessible by Default Components follow WAI-ARIA guidelines. Proper roles, keyboard navigation, focus management, and screen reader support are built into every component. ### Tailwind CSS 4 Native Built specifically for Tailwind CSS 4. Uses CSS custom properties for theming, `@theme` configuration for design tokens, and leverages Tailwind's newest features. ## Requirements | Dependency | Version | |------------|---------| | PHP | 8.3+ | | Laravel | 12.0+ | | Tailwind CSS | 4.0+ | | Alpine.js | 3.0+ | | Livewire | 3.6+ (optional, required for Pro interactive components) | ## Quick Start ### 1. Install the package ```bash composer require bluestarsystem/aura-ui ``` ### 2. Run the installer ```bash php artisan aura:install ``` This publishes the configuration file and CSS assets to your project. ### 3. Import the CSS Add the Aura UI stylesheet to your `resources/css/app.css`: ```css @import 'tailwindcss'; @import './vendor/aura-ui/aura.css'; ``` ### 4. Use components in your Blade templates ```html Click me Your changes have been saved. ``` That's it. You're ready to build. ## Free vs Pro Aura UI is available in two editions. The **Free** package provides a solid foundation of essential components, while **Pro** adds advanced interactive components and Livewire integration traits. ### Free Package (MIT License) 26 components organized into six categories: | Category | Components | |----------|------------| | **Primitives** | Button, Icon, Spinner, Skeleton | | **Feedback** | Alert, Badge, Empty State, Progress, Tooltip | | **Layout** | Card, Card.Title, Card.Description, Modal | | **Navigation** | Breadcrumbs, Dropdown, Dropdown.Item, Dropdown.Separator, Pagination | | **Data Display** | Avatar, Avatar.Group, Description List, Description List.Item, Stats Card | | **Form Layout** | Form, Form.Section, Form.Actions, Input, Select, Textarea, Checkbox, Radio, Radio Group, Toggle | ### Pro Package (Proprietary License) 20 additional components plus 5 Livewire traits: | Category | Components | |----------|------------| | **Advanced Forms** | Autocomplete, Color Picker, Date Picker, Time Picker, File Upload, OTP Input, Slider, Tags Input | | **Navigation** | Sidebar, Sidebar.Brand, Sidebar.Section, Sidebar.Item, Sidebar.SubItem, Tabs, Tabs.Tab, Steps, Steps.Step, Command Palette | | **Interactive** | Accordion, Calendar, Chart, Confirmation Dialog, Editor, Kanban, Toasts, Tree | | Livewire Trait | Purpose | |----------------|---------| | `WithAuraDataTable` | Sortable, searchable, paginated data tables | | `WithAuraFilters` | Filter UI with text, select, date range, and boolean filters | | `WithAuraBulkActions` | Checkbox selection and bulk operations | | `WithAuraForm` | Form state management, validation, and submission | | `WithAuraInlineEdit` | Click-to-edit cells in tables | ### Choosing Your Edition - **Free** is perfect for personal projects, prototypes, and applications that need a clean component foundation. - **Pro** is ideal for admin panels, dashboards, SaaS applications, and any project that needs advanced data management components. Pro requires Free as a dependency -- both packages use the same `` prefix, so upgrading is seamless. ## Project Structure After installation, Aura UI integrates into your Laravel project like this: ``` your-project/ ├── config/ │ └── aura-ui.php # Configuration file ├── resources/ │ └── css/ │ ├── app.css # Your app CSS (imports Aura CSS) │ └── vendor/ │ ├── aura-ui/ │ │ ├── aura.css # Main entry point (Free) │ │ ├── compat/ # Legacy variable compatibility │ │ ├── base/ # Dark mode, keyframes, glass │ │ └── components/ # Residual component CSS │ └── aura-ui-pro/ │ └── aura-pro.css # Pro entry point ├── vendor/ │ └── bluestarsystem/ │ ├── aura-ui/ # Free package │ └── aura-ui-pro/ # Pro package (if installed) ``` You only need to import the entry points (`aura.css` and `aura-pro.css`) -- they handle all internal imports automatically. ## Next Steps - [Installation](/docs/installation) -- Detailed installation instructions for Free and Pro - [Configuration](/docs/configuration) -- Customize component behavior and defaults - [Theming](/docs/theming) -- Adapt the Vibrant Depth design to your brand - [Dark Mode](/docs/dark-mode) -- Set up light/dark theme switching - [Upgrading](/docs/upgrading) -- Keep your installation up to date --- --- title: Installation description: Install and configure Aura UI in your Laravel project. --- [TOC] ## Requirements Before installing Aura UI, make sure your environment meets the following requirements: | Dependency | Minimum Version | Notes | |------------|----------------|-------| | PHP | 8.3+ | Required for both Free and Pro | | Laravel | 12.0+ | Built for Laravel 12 | | Tailwind CSS | 4.0+ | Uses CSS-first configuration | | Alpine.js | 3.0+ | Required for interactive components | | Livewire | 3.6+ | Optional; required for Pro traits | | Node.js | 18.0+ | For Vite asset compilation | ## Installing the Free Package ### Step 1: Require via Composer ```bash composer require bluestarsystem/aura-ui ``` The package auto-discovers its service provider. No manual registration is needed. ### Step 2: Run the Installer ```bash php artisan aura:install ``` This command publishes: - `config/aura-ui.php` -- the configuration file - `resources/css/vendor/aura-ui/aura.css` -- the component stylesheet ### Step 3: Import the CSS Open your `resources/css/app.css` and add the Aura UI import after Tailwind: ```css @import 'tailwindcss'; @import './vendor/aura-ui/aura.css'; ``` ### Step 4: Configure Tailwind Source Detection Tailwind CSS 4 needs to know where to scan for class names. Add a `@source` directive in your `resources/css/app.css` to include the Aura UI vendor views: ```css @import 'tailwindcss'; @source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php'; @import './vendor/aura-ui/aura.css'; ``` This ensures Tailwind generates CSS for all utility classes used inside Aura UI components. ### Step 5: Verify Installation Create a test Blade view to confirm everything works: ```html {{-- resources/views/test.blade.php --}} Aura UI is working! Installation successful. ``` Run `npm run dev` (or `npm run build`) and visit the page. If you see a styled button and alert, the Free package is installed correctly. ## Installing the Pro Package The Pro package is distributed through a private Satis repository at `packages.elju.it`. You need a valid license and authentication token to install it. ### Step 1: Add the Satis Repository Add the Aura UI Pro repository to your project's `composer.json`: ```json { "repositories": [ { "type": "composer", "url": "https://packages.elju.it" } ] } ``` Or via the command line: ```bash composer config repositories.aura-ui-pro composer https://packages.elju.it ``` ### Step 2: Configure Authentication Authenticate with your Aura UI license key using Composer's Bearer token authentication: ```bash composer config bearer.packages.elju.it AURA-XXXX-XXXX-XXXX-XXXX ``` Replace `AURA-XXXX-XXXX-XXXX-XXXX` with the license key from your [Aura UI account dashboard](https://aura-ui.com/dashboard). This creates an `auth.json` file in your project root: ```json { "bearer": { "packages.elju.it": "AURA-XXXX-XXXX-XXXX-XXXX" } } ``` > **Important:** Add `auth.json` to your `.gitignore` file to avoid committing credentials to version control. ```bash echo "auth.json" >> .gitignore ``` ### Step 3: Require the Pro Package ```bash composer require bluestarsystem/aura-ui-pro ``` This will also install the Free package as a dependency if it's not already present. ### Step 4: Run the Pro Installer ```bash php artisan aura-pro:install ``` This publishes: - `resources/css/vendor/aura-ui-pro/aura-pro.css` -- the Pro component stylesheet ### Step 5: Import the Pro CSS Update your `resources/css/app.css` to include both Free and Pro styles: ```css @import 'tailwindcss'; @source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php'; @source '../../vendor/bluestarsystem/aura-ui-pro/resources/views/**/*.blade.php'; @import './vendor/aura-ui/aura.css'; @import './vendor/aura-ui-pro/aura-pro.css'; ``` The order matters: Tailwind first, then `@source` directives, then Aura UI Free, then Aura UI Pro. ### Step 6: Verify Pro Installation Test a Pro-exclusive component: ```html {{-- resources/views/test-pro.blade.php --}}

Tab content goes here.

Settings content.

 ``` ## CSS Setup ### Complete app.css Example Here is a complete `resources/css/app.css` for a project using both Free and Pro: ```css /* Tailwind CSS 4 */ @import 'tailwindcss'; /* Source detection for Tailwind class scanning */ @source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php'; @source '../../vendor/bluestarsystem/aura-ui-pro/resources/views/**/*.blade.php'; /* Aura UI component styles */ @import './vendor/aura-ui/aura.css'; @import './vendor/aura-ui-pro/aura-pro.css'; /* Your custom styles and @theme overrides go here */ ``` The `aura.css` entry point already defines `@custom-variant dark`, `@theme` design tokens, and imports all internal CSS files (dark mode overrides, keyframe animations, glass morphism utilities, and residual component styles). See the [Theming](/docs/theming) guide for the full CSS architecture breakdown. ### Font Setup Aura UI's Vibrant Depth design uses two font families. Include them in your layout: ```html {{-- resources/views/layouts/app.blade.php --}} @vite(['resources/css/app.css', 'resources/js/app.js']) ``` ## Vite Configuration ### Refresh Paths To enable hot-reloading for Aura UI components during development, add the vendor view paths to your Vite configuration: ```js // vite.config.js import { defineConfig } from 'vite'; import laravel from 'laravel-vite-plugin'; export default defineConfig({ plugins: [ laravel({ input: [ 'resources/css/app.css', 'resources/js/app.js', ], refresh: [ 'resources/views/**', 'vendor/bluestarsystem/aura-ui/resources/views/**', 'vendor/bluestarsystem/aura-ui-pro/resources/views/**', ], }), ], }); ``` This ensures that changes to published or vendor component views trigger a page refresh during development. ## Alpine.js Setup Aura UI uses Alpine.js for client-side interactivity (dropdowns, modals, tooltips, dark mode toggling, etc.). Make sure Alpine.js is loaded in your application. ### Option A: Via NPM (Recommended) ```bash npm install alpinejs ``` ```js // resources/js/app.js import Alpine from 'alpinejs'; window.Alpine = Alpine; Alpine.start(); ``` ### Option B: Via CDN ```html {{-- In your layout --}} ``` > **Tip:** If you use Livewire 3, Alpine.js is already bundled and injected automatically. You do not need to install it separately. However, if you need to register custom Alpine data or plugins, import Alpine via NPM and disable Livewire's auto-injection by setting `'inject_assets' => false` in `config/livewire.php`. ### Livewire Integration If you are using Livewire 3, Aura UI form components work with `wire:model` natively: ```html Italy United States Germany ``` ## Troubleshooting ### Components render without styles Make sure you have: 1. Imported `aura.css` (and `aura-pro.css` for Pro) in your `resources/css/app.css` 2. Added the `@source` directives pointing to the vendor Blade views 3. Run `npm run build` or `npm run dev` to recompile assets ### "Component not found" error Verify the package is installed: ```bash composer show bluestarsystem/aura-ui ``` Check that the service provider is auto-discovered: ```bash php artisan vendor:publish --list | grep aura ``` If auto-discovery is disabled, manually register the provider in `bootstrap/providers.php`: ```php return [ // ... BlueStarSystem\AuraUI\AuraUIServiceProvider::class, BlueStarSystem\AuraUIPro\AuraUIProServiceProvider::class, // if Pro is installed ]; ``` ### Pro package authentication fails Double-check your license key. You can also configure authentication globally: ```bash composer config --global bearer.packages.elju.it AURA-XXXX-XXXX-XXXX-XXXX ``` Make sure your license is active in your [Aura UI dashboard](https://aura-ui.com/dashboard). ### Dark mode classes are not generated Aura UI's `aura.css` includes `@custom-variant dark (&:is(.dark *));` which overrides Tailwind 4's default dark mode to use the `.dark` class strategy. Make sure the `@source` directives include the Aura UI view paths so Tailwind can scan those files and detect `dark:` variant usage. ### Styles appear but look wrong Clear the Vite cache and rebuild: ```bash rm -rf node_modules/.vite npm run build ``` Also clear the Laravel view cache: ```bash php artisan view:clear php artisan cache:clear ``` ## Next Steps - [Configuration](/docs/configuration) -- Customize component prefix, icons, and behavior - [Theming](/docs/theming) -- Adapt Aura UI's design to match your brand - [Dark Mode](/docs/dark-mode) -- Set up theme switching --- --- title: CLI (aura:add) description: Copy Aura component source into your project and own the code, shadcn-style. --- [TOC] # Aura CLI — own the code Aura ships an additive CLI alongside the Composer package. Keep the package for managed upgrades, or copy any component's source into your project and own it. ## Setup (once) ```bash php artisan aura:init ``` This publishes the Aura CSS to `resources/css/vendor/aura-ui/` and prepares `resources/views/components/aura/`. Add the stylesheet after Tailwind: ```css @import "tailwindcss"; @import "vendor/aura-ui/aura.css"; ``` ## Add components ```bash php artisan aura:add button ``` The component and its dependencies are copied into `resources/views/components/aura/`. Internal references are rewritten to the local dot namespace, so use them as: ```blade Click ``` ### Options - `--force` — overwrite existing files - `--dry-run` — preview without writing - `--no-deps` — skip dependencies - `--path=` — custom destination directory ## Pro components Pro components require the Pro package (your license is checked at install time): ```bash composer require bluestarsystem/aura-ui-pro php artisan aura:add scheduler ``` --- --- title: Configuration description: Configure Aura UI component behavior, prefix, icons, and defaults. --- [TOC] ## Configuration File After running `php artisan aura:install`, a configuration file is published to `config/aura-ui.php`. This file controls the global behavior of all Aura UI components. To re-publish the configuration at any time: ```bash php artisan vendor:publish --tag=aura-ui-config --force ``` ## Default Configuration Here is the full default configuration with all available options: ```php , , etc. | */ 'prefix' => 'aura', /* |-------------------------------------------------------------------------- | Dark Mode |-------------------------------------------------------------------------- | | How dark mode is detected. Options: | - 'class': Dark mode via .dark class on (Tailwind default) | - 'media': Dark mode via prefers-color-scheme media query | */ 'dark_mode' => 'class', /* |-------------------------------------------------------------------------- | Default Icon Set |-------------------------------------------------------------------------- | | The icon set used by Aura components. | Requires blade-ui-kit/blade-heroicons or compatible package. | */ 'icons' => 'heroicon', /* |-------------------------------------------------------------------------- | Playground |-------------------------------------------------------------------------- | | Enable the component playground route at /aura/playground. | */ 'playground' => [ 'enabled' => true, 'path' => 'aura/playground', 'middleware' => ['web'], ], ]; ``` ## Component Prefix The `prefix` option defines the Blade component namespace. By default, all components use the `aura` prefix: ```html Click me Content ``` ### Customizing the Prefix If `aura` conflicts with another package or you prefer a different namespace, change the prefix: ```php // config/aura-ui.php 'prefix' => 'ui', ``` After changing the prefix, all components use the new namespace: ```html Click me Content ``` > **Note:** If you have both Free and Pro installed, both packages share the same prefix. Changing it in the config applies to all Aura UI components. You need to update all component references in your Blade templates after changing the prefix. ### Cache Clearing After changing the prefix, clear the view cache: ```bash php artisan view:clear ``` ## Dark Mode Detection The `dark_mode` option controls how Aura UI components detect dark mode: ### Class Strategy (Default) ```php 'dark_mode' => 'class', ``` Components respond to the `.dark` class on the `` element. This gives you full control over when dark mode is active, typically toggled via Alpine.js or JavaScript. ```html ``` This is the recommended approach. See the [Dark Mode](/docs/dark-mode) guide for setup details. ### About the Media Strategy > **Note:** Aura UI's CSS uses `@custom-variant dark (&:is(.dark *));` which is always class-based. The `class` strategy is the only fully supported approach. If you want dark mode to follow the system preference automatically, use the Alpine.js `setSystem()` method described in the [Dark Mode](/docs/dark-mode) guide -- it listens to `prefers-color-scheme` changes and toggles the `.dark` class accordingly. ## Default Icon Set The `icons` option specifies which Blade icon package Aura UI uses internally for component icons (alert close buttons, dropdown arrows, pagination chevrons, etc.). ```php 'icons' => 'heroicon', ``` ### Supported Icon Sets Aura UI works with any Blade icon package that follows the `blade-ui-kit` naming convention: | Value | Package | Install Command | |-------|---------|-----------------| | `heroicon` | [Blade Heroicons](https://github.com/blade-ui-kit/blade-heroicons) | `composer require blade-ui-kit/blade-heroicons` | ### Installing the Icon Package Aura UI does not bundle icons. Install your preferred icon package separately: ```bash composer require blade-ui-kit/blade-heroicons ``` ### Using Icons in Components The `` component renders icons from the configured set: ```html ``` ## Playground The playground is an interactive route that displays all available Aura UI components with their variants and props. It is useful during development for previewing and testing components. ```php 'playground' => [ 'enabled' => true, 'path' => 'aura/playground', 'middleware' => ['web'], ], ``` ### Enabling/Disabling The playground route is registered when `playground.enabled` is `true` in the config. In production, disable it by setting `'enabled' => false` or by using an environment variable (see [Environment-Based Configuration](#environment-based-configuration) below). ### Customizing the Path Change the URL where the playground is accessible: ```php 'playground' => [ 'enabled' => true, 'path' => 'dev/components', // Now at /dev/components 'middleware' => ['web'], ], ``` ### Adding Authentication Restrict playground access to authenticated users or specific roles: ```php 'playground' => [ 'enabled' => true, 'path' => 'aura/playground', 'middleware' => ['web', 'auth', 'can:access-playground'], ], ``` ## Environment-Based Configuration You can use environment variables to control Aura UI settings per environment: ```php // config/aura-ui.php return [ 'prefix' => env('AURA_PREFIX', 'aura'), 'dark_mode' => env('AURA_DARK_MODE', 'class'), 'icons' => env('AURA_ICONS', 'heroicon'), 'playground' => [ 'enabled' => env('AURA_PLAYGROUND', true), 'path' => 'aura/playground', 'middleware' => ['web'], ], ]; ``` ```env # .env AURA_PREFIX=aura AURA_DARK_MODE=class AURA_ICONS=heroicon AURA_PLAYGROUND=true ``` ## Publishing Views If you need to customize the Blade templates of individual components, you can publish them: ```bash # Publish all Free component views php artisan vendor:publish --tag=aura-ui-views # Publish all Pro component views (if Pro is installed) php artisan vendor:publish --tag=aura-ui-pro-views ``` Published views are placed in `resources/views/vendor/aura/`. Blade resolves published views before vendor views, so your customized versions take priority. ``` resources/ └── views/ └── vendor/ └── aura/ └── components/ ├── button.blade.php # Your customized button ├── card.blade.php # Your customized card └── ... ``` > **Tip:** Only publish the specific views you want to customize. Keeping the rest in the vendor directory ensures you receive updates when upgrading the package. ### Publishing a Single View Laravel does not support publishing individual vendor views via artisan. Instead, manually copy the file you want to customize: ```bash # Example: customize the button component mkdir -p resources/views/vendor/aura/components cp vendor/bluestarsystem/aura-ui/resources/views/components/button.blade.php \ resources/views/vendor/aura/components/button.blade.php ``` Edit the copied file as needed. The original vendor file remains untouched. ## Publishing CSS To customize the base stylesheet: ```bash php artisan vendor:publish --tag=aura-ui-css --force ``` This re-publishes `resources/css/vendor/aura-ui/aura.css`. You can edit this file to override default component styles, modify CSS custom properties, or add custom animations. > **Warning:** Re-publishing with `--force` overwrites your changes. Back up your customizations before re-publishing. ## Configuration Caching Aura UI's configuration is compatible with Laravel's config cache: ```bash php artisan config:cache ``` Remember to re-cache after any changes to `config/aura-ui.php`: ```bash php artisan config:clear php artisan config:cache ``` ## Next Steps - [Theming](/docs/theming) -- Customize colors, fonts, and the Vibrant Depth design - [Dark Mode](/docs/dark-mode) -- Set up light/dark theme switching - [Upgrading](/docs/upgrading) -- Keep Aura UI up to date --- --- title: Theming description: Customize the Aura UI design system to match your brand identity. --- [TOC] ## Vibrant Depth Design Language Aura UI follows a design language called **Vibrant Depth**. It moves beyond flat design by introducing layered visual cues that create a sense of depth and hierarchy: - **Gradients** -- Subtle color transitions on primary elements (buttons, badges, active states) - **Glow effects** -- Soft colored shadows that make interactive elements feel elevated - **Glass morphism** -- Translucent panels with backdrop blur for overlays, modals, and dropdowns - **Micro-animations** -- Purposeful transitions on hover, focus, and state changes - **Layered shadows** -- Multiple shadow layers that create realistic depth These effects are implemented through Tailwind CSS 4 `@theme` tokens and CSS custom properties, making them fully customizable. ## CSS Architecture Aura UI's styles are organized into several CSS files, all imported from the main entry point `aura.css`: | File | Purpose | |------|---------| | `aura.css` | Entry point: `@custom-variant dark`, `@theme` design tokens, imports | | `compat/variables-compat.css` | Legacy `--aura-*` variable mapping (maps to `@theme` tokens) | | `base/dark-mode.css` | Dark mode variable overrides under `.dark` | | `base/keyframes.css` | Keyframe animations and `@utility` animation classes | | `base/glass.css` | Glass morphism `@utility` classes | | `components/residual.css` | Component CSS that cannot be expressed as Tailwind utilities (pseudo-elements, sibling selectors, SVG backgrounds) | For Pro, `aura-pro.css` imports `components/sidebar-residual.css` (sidebar transitions, accordion chevrons, toast progress bars, etc.). You only need to import the entry points in your `app.css` -- the internal files are loaded automatically. ## Design Tokens (@theme) Aura UI defines its design tokens inside a Tailwind CSS 4 `@theme` block. These tokens are available as Tailwind utilities (e.g., `bg-aura-primary-500`, `text-aura-surface-900`) and as CSS custom properties. ### Color Scales Colors use a numeric scale (50--950) following Tailwind conventions: ```css /* In aura.css — these are the defaults */ @theme { /* PRIMARY (Deep Blue / Indigo) */ --color-aura-primary-50: #eef6ff; --color-aura-primary-100: #dbeafe; --color-aura-primary-200: #bfdbfe; --color-aura-primary-300: #93c5fd; --color-aura-primary-400: #60a5fa; --color-aura-primary-500: #6366f1; --color-aura-primary-600: #4f46e5; --color-aura-primary-700: #4338ca; --color-aura-primary-800: #3730a3; --color-aura-primary-900: #312e81; --color-aura-primary-950: #1e1b4b; /* SECONDARY (Teal/Cyan) */ --color-aura-secondary-50: #ecfeff; --color-aura-secondary-500: #06b6d4; --color-aura-secondary-600: #0891b2; /* ... full 50-900 scale */ /* SURFACES (Light mode — warm whites to dark grays) */ --color-aura-surface-0: #ffffff; --color-aura-surface-50: #f8fafc; --color-aura-surface-100: #f1f5f9; --color-aura-surface-200: #e2e8f0; --color-aura-surface-300: #cbd5e1; --color-aura-surface-400: #94a3b8; --color-aura-surface-500: #64748b; --color-aura-surface-600: #475569; --color-aura-surface-700: #334155; --color-aura-surface-800: #1e293b; --color-aura-surface-900: #0f172a; } ``` Feedback colors follow the same pattern: | Scale | Default Base Color | |-------|-------------------| | `--color-aura-success-{50-700}` | Emerald | | `--color-aura-warning-{50-700}` | Amber | | `--color-aura-danger-{50-700}` | Red/Coral | | `--color-aura-info-{50-700}` | Sky | ### Usage in Tailwind Classes Since these are registered via `@theme`, they generate Tailwind utilities automatically: ```html
Primary background
Card surface
Subtle border
``` ### Usage as CSS Custom Properties You can also reference them directly in CSS: ```css .my-element { background: var(--color-aura-primary-500); color: var(--color-aura-surface-0); } ``` ## Customizing Colors ### Overriding the Primary Palette To change the primary color to your brand, override the `@theme` tokens **after** importing `aura.css`: ```css /* resources/css/app.css */ @import 'tailwindcss'; @source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php'; @import './vendor/aura-ui/aura.css'; /* Override primary palette */ @theme { --color-aura-primary-50: #eff6ff; --color-aura-primary-100: #dbeafe; --color-aura-primary-200: #bfdbfe; --color-aura-primary-300: #93c5fd; --color-aura-primary-400: #60a5fa; --color-aura-primary-500: #3b82f6; --color-aura-primary-600: #2563eb; --color-aura-primary-700: #1d4ed8; --color-aura-primary-800: #1e40af; --color-aura-primary-900: #1e3a8a; --color-aura-primary-950: #172554; } ``` This changes every primary-colored component across the entire library. ### Examples of Brand Color Palettes ```css /* Ocean theme (Teal) */ @theme { --color-aura-primary-500: #14b8a6; --color-aura-primary-600: #0d9488; --color-aura-primary-700: #0f766e; /* ... override the full 50-950 scale for best results */ } /* Sunset theme (Orange/Rose) */ @theme { --color-aura-primary-500: #f97316; --color-aura-primary-600: #ea580c; --color-aura-primary-700: #c2410c; } /* Forest theme (Green) */ @theme { --color-aura-primary-500: #22c55e; --color-aura-primary-600: #16a34a; --color-aura-primary-700: #15803d; } ``` > **Tip:** For the best visual consistency, override the full 50--950 scale. Use a tool like [UI Colors](https://uicolors.app/) to generate a complete palette from a base color. ### Customizing Feedback Colors Override the semantic colors used by alerts, badges, and form validation: ```css @theme { --color-aura-success-500: #22c55e; --color-aura-success-600: #16a34a; --color-aura-warning-500: #eab308; --color-aura-warning-600: #ca8a04; --color-aura-danger-500: #e11d48; --color-aura-danger-600: #be123c; --color-aura-info-500: #3b82f6; --color-aura-info-600: #2563eb; } ``` ## Font Customization Aura UI defines two font families as `@theme` tokens: | Token | Default | Purpose | |-------|---------|---------| | `--font-aura-sans` | Inter | Body text, UI elements | | `--font-aura-mono` | JetBrains Mono | Code blocks, monospace | ### Changing Fonts Override the font tokens in your `@theme` block: ```css @theme { --font-aura-sans: 'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif; --font-aura-mono: 'Fira Code', ui-monospace, monospace; } ``` ### Loading Fonts Include font files via a CDN in your layout: ```html ``` Or self-host them for better performance: ```css /* resources/css/fonts.css */ @font-face { font-family: 'Inter'; src: url('/fonts/inter-variable.woff2') format('woff2'); font-weight: 100 900; font-display: swap; } @font-face { font-family: 'JetBrains Mono'; src: url('/fonts/jetbrains-mono-variable.woff2') format('woff2'); font-weight: 100 800; font-display: swap; } ``` ## Border Radius Aura UI uses namespaced border radius tokens. Override them to change the feel of all components: ```css @theme { --radius-aura-xs: 4px; --radius-aura-sm: 6px; --radius-aura-md: 8px; --radius-aura-lg: 12px; --radius-aura-xl: 16px; --radius-aura-2xl: 24px; --radius-aura-full: 9999px; } ``` ### Examples ```css /* Sharp / minimal design */ @theme { --radius-aura-xs: 0px; --radius-aura-sm: 2px; --radius-aura-md: 4px; --radius-aura-lg: 6px; --radius-aura-xl: 8px; --radius-aura-2xl: 12px; } /* Soft / pill design */ @theme { --radius-aura-xs: 8px; --radius-aura-sm: 10px; --radius-aura-md: 14px; --radius-aura-lg: 20px; --radius-aura-xl: 28px; --radius-aura-2xl: 9999px; } ``` ## Shadows Aura UI uses layered shadows with namespaced tokens to create the Vibrant Depth effect: ```css @theme { --shadow-aura-xs: 0 1px 2px rgba(0, 0, 0, 0.04); --shadow-aura-sm: 0 1px 2px rgba(0, 0, 0, 0.06), 0 1px 3px rgba(0, 0, 0, 0.1); --shadow-aura-md: 0 4px 6px rgba(0, 0, 0, 0.04), 0 2px 4px rgba(0, 0, 0, 0.06), 0 0 0 1px rgba(0, 0, 0, 0.02); --shadow-aura-lg: 0 10px 15px rgba(0, 0, 0, 0.08), 0 4px 6px rgba(0, 0, 0, 0.04), 0 0 0 1px rgba(0, 0, 0, 0.02); --shadow-aura-xl: 0 20px 25px rgba(0, 0, 0, 0.1), 0 8px 10px rgba(0, 0, 0, 0.04); --shadow-aura-2xl: 0 25px 50px rgba(0, 0, 0, 0.15); } ``` ### Glow Effects The glow effect on interactive elements is controlled via the compatibility layer in `variables-compat.css`. The glow intensity and per-color glow shadows are defined as CSS custom properties: ```css :root { /* Global glow intensity (0 to 1) */ --aura-glow-intensity: 0.15; /* Per-color glow shadows */ --aura-glow-primary: 0 0 0 3px rgba(99, 102, 241, var(--aura-glow-intensity)), 0 0 15px rgba(99, 102, 241, calc(var(--aura-glow-intensity) * 0.5)); --aura-glow-success: 0 0 0 3px rgba(16, 185, 129, var(--aura-glow-intensity)), 0 0 15px rgba(16, 185, 129, calc(var(--aura-glow-intensity) * 0.5)); /* ... same pattern for danger, warning, info, secondary */ } ``` To make glows stronger or subtler, override `--aura-glow-intensity`: ```css :root { /* Stronger glow */ --aura-glow-intensity: 0.3; /* No glow */ --aura-glow-intensity: 0; } ``` In dark mode, glow intensity is automatically increased to `0.25` for better visibility. ### Disabling Glow Effects ```css :root { --aura-glow-intensity: 0; } .dark { --aura-glow-intensity: 0; } ``` ## Glass Morphism Glass morphism effects are provided as `@utility` classes that you can apply to any element. They are defined in `base/glass.css`: | Utility Class | Effect | |---------------|--------| | `aura-glass` | Standard glass: 70% white bg, 12px blur, saturate 1.5 | | `aura-glass-subtle` | Lighter glass: 50% white bg, 8px blur, saturate 1.2 | | `aura-glass-strong` | Dense glass: 85% white bg, 20px blur, saturate 1.8 | | `aura-glass-overlay` | Dark overlay: 40% dark bg, 4px blur | All glass utilities automatically adapt in dark mode (switching to dark backgrounds with low-opacity white borders). ### Usage ```html
Frosted glass panel
Lighter glass effect
``` ### Customizing Glass Since glass effects are defined as `@utility` rules with hardcoded values, customize them by overriding the utility in your `app.css`: ```css /* After importing aura.css */ @utility aura-glass { background: rgba(255, 255, 255, 0.6); backdrop-filter: blur(16px) saturate(1.8); -webkit-backdrop-filter: blur(16px) saturate(1.8); border: 1px solid rgba(255, 255, 255, 0.3); } ``` ### Disabling Glass Morphism For a fully opaque design: ```css @utility aura-glass { background: white; backdrop-filter: none; -webkit-backdrop-filter: none; border: 1px solid var(--color-aura-surface-200); } .dark .aura-glass { background: var(--color-aura-surface-0); border-color: rgba(255, 255, 255, 0.08); } ``` ## Animations Aura UI components include micro-animations for hover, focus, and state transitions. Animation durations are controlled via `@theme` tokens: ```css @theme { --animate-duration-fast: 100ms; --animate-duration-normal: 150ms; --animate-duration-slow: 250ms; } ``` Easing curves are also defined as tokens: ```css @theme { --ease-aura-out: cubic-bezier(0.16, 1, 0.3, 1); --ease-aura-spring: cubic-bezier(0.34, 1.56, 0.64, 1); --ease-aura-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55); } ``` ### Animation Utility Classes Aura UI provides `@utility` animation classes in `base/keyframes.css`: | Utility | Effect | |---------|--------| | `aura-animate-spin` | Continuous rotation (spinner) | | `aura-animate-shimmer` | Shimmer effect (skeleton loading) | | `aura-animate-fade-in` | Fade in | | `aura-animate-slide-up` | Slide up with fade | | `aura-animate-scale-in` | Scale in with spring easing | | `aura-animate-shake` | Shake (validation error) | | `aura-transition` | Standard transition preset (150ms) | | `aura-transition-fast` | Fast transition preset (100ms) | | `aura-transition-slow` | Slow transition preset (250ms) | ### Customizing Animation Speed ```css @theme { /* Faster animations */ --animate-duration-fast: 50ms; --animate-duration-normal: 100ms; --animate-duration-slow: 150ms; /* Or slower, more dramatic */ --animate-duration-fast: 150ms; --animate-duration-normal: 250ms; --animate-duration-slow: 400ms; } ``` ### Disabling Animations Aura UI respects the `prefers-reduced-motion` media query automatically. To disable animations globally: ```css @theme { --animate-duration-fast: 0ms; --animate-duration-normal: 0ms; --animate-duration-slow: 0ms; } ``` ## Legacy Compatibility Layer The `compat/variables-compat.css` file maps `@theme` tokens to legacy `--aura-*` CSS custom properties. This layer exists for backward compatibility and is also used by the Pro package's sidebar and other components internally. Key mappings include: | Legacy Variable | Maps To | |----------------|---------| | `--aura-primary-500` | `var(--color-aura-primary-500)` | | `--aura-surface-0` | `var(--color-aura-surface-0)` | | `--aura-text-primary` | `var(--color-aura-surface-900)` | | `--aura-text-muted` | `var(--color-aura-surface-400)` | | `--aura-border-default` | `var(--color-aura-surface-300)` | | `--aura-border-focus` | `var(--color-aura-primary-500)` | | `--aura-radius-md` | `var(--radius-aura-md)` | | `--aura-shadow-md` | `var(--shadow-aura-md)` | | `--aura-gradient-primary` | `linear-gradient(135deg, primary-500, primary-700)` | You can use either the `@theme` tokens or the legacy `--aura-*` variables in your custom CSS. The `@theme` tokens are preferred because they generate Tailwind utility classes. ## Creating Custom Theme Presets You can create reusable theme presets as separate CSS files and swap them dynamically. ### Defining a Preset ```css /* resources/css/themes/corporate.css */ @theme { --color-aura-primary-500: #2563eb; --color-aura-primary-600: #1d4ed8; --color-aura-primary-700: #1e40af; } :root { --aura-glow-intensity: 0.08; } @theme { --animate-duration-fast: 75ms; --animate-duration-normal: 100ms; --animate-duration-slow: 200ms; } ``` ```css /* resources/css/themes/playful.css */ @theme { --color-aura-primary-500: #d946ef; --color-aura-primary-600: #c026d3; --color-aura-primary-700: #a21caf; } :root { --aura-glow-intensity: 0.25; } ``` ### Using a Preset Import the preset after the Aura UI base styles: ```css /* resources/css/app.css */ @import 'tailwindcss'; @source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php'; @import './vendor/aura-ui/aura.css'; @import './themes/corporate.css'; ``` ### Dynamic Theme Switching You can switch themes at runtime by toggling a class on the `` element: ```html ``` ```css .theme-corporate { --color-aura-primary-500: #2563eb; --color-aura-primary-600: #1d4ed8; --color-aura-primary-700: #1e40af; } .theme-playful { --color-aura-primary-500: #d946ef; --color-aura-primary-600: #c026d3; --color-aura-primary-700: #a21caf; } ``` ```html Corporate Playful ``` > **Note:** For dynamic switching via CSS classes, use plain `:root` / `.theme-*` selectors (not `@theme`) because `@theme` values are resolved at build time. ## Component-Level Overrides If you need to customize a specific component without affecting others, use Tailwind utility classes directly: ```html Custom Button Custom Card ``` For broader component-level customization, publish the individual Blade view and edit the template directly. See [Configuration](/docs/configuration#publishing-views) for details. ## Next Steps - [Dark Mode](/docs/dark-mode) -- Set up light/dark theme switching - [Configuration](/docs/configuration) -- Other configuration options - [Upgrading](/docs/upgrading) -- Keep Aura UI updated --- --- title: Dark Mode description: Set up and customize dark mode for your Aura UI application. --- [TOC] ## Overview Every Aura UI component ships with full dark mode support. When dark mode is active, components automatically switch to dark-optimized colors, shadows, and contrast levels. No additional configuration per component is required. Dark mode in Aura UI relies on three things: 1. **`@custom-variant dark`** -- Aura UI's `aura.css` includes `@custom-variant dark (&:is(.dark *));` which overrides Tailwind 4's default dark mode to use the `.dark` class on `` instead of `prefers-color-scheme` 2. **Alpine.js** -- Manages the toggle state and persists the user's preference 3. **CSS custom properties** -- The `base/dark-mode.css` file overrides surface, accent, shadow, and glow tokens under `.dark` ## Setup ### Step 1: Add Alpine.js Data to the HTML Tag In your root layout file (e.g., `resources/views/layouts/app.blade.php`), add the `darkMode` Alpine.js data component to the `` tag: ```html {{ config('app.name') }} @vite(['resources/css/app.css', 'resources/js/app.js']) {{ $slot }} ``` The key part is `x-data="darkMode"` and `x-bind:class="{ 'dark': dark }"`. When `dark` is `true`, the `.dark` class is added to ``, and all Aura UI components switch to their dark variants. ### Step 2: Register the Alpine.js Component Create the `darkMode` Alpine data component in your JavaScript: ```js // resources/js/app.js import Alpine from 'alpinejs'; document.addEventListener('alpine:init', () => { Alpine.data('darkMode', () => ({ dark: false, init() { // Check localStorage first, then system preference const stored = localStorage.getItem('darkMode'); if (stored !== null) { this.dark = stored === 'true'; } else { this.dark = window.matchMedia('(prefers-color-scheme: dark)').matches; } // Watch for system preference changes (when no manual override) window.matchMedia('(prefers-color-scheme: dark)') .addEventListener('change', (e) => { if (localStorage.getItem('darkMode') === null) { this.dark = e.matches; } }); }, toggle() { this.dark = !this.dark; localStorage.setItem('darkMode', this.dark); }, setLight() { this.dark = false; localStorage.setItem('darkMode', 'false'); }, setDark() { this.dark = true; localStorage.setItem('darkMode', 'true'); }, setSystem() { localStorage.removeItem('darkMode'); this.dark = window.matchMedia('(prefers-color-scheme: dark)').matches; }, })); }); window.Alpine = Alpine; Alpine.start(); ``` This component: - Reads the saved preference from `localStorage` on page load - Falls back to the system `prefers-color-scheme` if no manual preference exists - Listens for system theme changes in real time - Provides `toggle()`, `setLight()`, `setDark()`, and `setSystem()` methods ### Step 3: Prevent Flash of Incorrect Theme To avoid a flash of the wrong theme on page load (FOIT), add an inline script in the `` **before** any CSS or JavaScript loads: ```html {{-- Prevent dark mode flash --}} @vite(['resources/css/app.css', 'resources/js/app.js']) ``` This synchronous script runs before the page renders, adding the `.dark` class immediately if needed. ## Toggle Button ### Simple Toggle A minimal dark mode toggle button with sun and moon icons: ```html ``` ### Three-Way Toggle (Light / Dark / System) A more complete toggle that also allows users to defer to their system preference: ```html
``` ### Using Aura UI Dropdown You can also use the built-in dropdown component for a cleaner implementation: ```html Light Dark System ``` ## Tailwind dark: Variant Aura UI components use Tailwind's `dark:` variant internally. When you build your own views, use the same pattern: ```html

Dashboard

Welcome back.

``` ### Common Dark Mode Patterns ```html {{-- Surfaces --}}
...
...
{{-- Text --}}

Primary text

Muted text

{{-- Borders --}}
...
{{-- Hover states --}} {{-- Inputs --}} ``` ## Automatic Dark Mode Support All Aura UI components handle dark mode internally. You do not need to add `dark:` classes to Aura UI components -- they adapt automatically: ```html {{-- These components look correct in both light and dark mode --}} User Profile Manage your account settings. Save Changes Cancel Your profile was updated successfully. ``` All of the above render correctly in both themes without any extra classes. ## Using with Livewire If you use Livewire, the dark mode state persists across Livewire navigations because it is stored in `localStorage` and applied via the inline `` script. No special Livewire configuration is needed. However, if you use Livewire's `wire:navigate` for SPA-like navigation, make sure the flash-prevention script is in the persistent layout: ```html {{-- resources/views/components/layouts/app.blade.php --}} @vite(['resources/css/app.css', 'resources/js/app.js']) {{ $slot }} ``` ## Configuration The dark mode detection strategy is configured in `config/aura-ui.php`: ```php 'dark_mode' => 'class', ``` | Value | Behavior | |-------|----------| | `class` | Dark mode when `.dark` class is on `` (default, user-toggled) | > **Note:** Aura UI's CSS uses `@custom-variant dark (&:is(.dark *));` which is always class-based. The dark mode is controlled by toggling the `.dark` class on the `` element as described in the setup above. ## Overriding Dark Colors Aura UI's dark mode overrides are defined in `base/dark-mode.css`. The surface scale is inverted (light values become dark), accent colors glow brighter, shadows become deeper, and glow intensity increases. To customize how components look in dark mode, override the CSS custom properties under the `.dark` selector: ```css /* resources/css/app.css — after importing aura.css */ .dark { /* Override surfaces */ --color-aura-surface-0: #0c1222; --color-aura-surface-50: #162032; --color-aura-surface-100: #1e3050; /* Override accent brightness */ --color-aura-primary-500: #a5b4fc; /* Override glow intensity */ --aura-glow-intensity: 0.35; /* Override shadow depth */ --shadow-aura-md: 0 4px 6px rgba(0, 0, 0, 0.3), 0 2px 4px rgba(0, 0, 0, 0.2); } ``` See the [Theming](/docs/theming) guide for the full list of design tokens and the CSS architecture breakdown. ## Next Steps - [Theming](/docs/theming) -- Customize colors, fonts, and design tokens - [Configuration](/docs/configuration) -- Configure dark mode strategy and other options - [Installation](/docs/installation) -- Full setup instructions --- --- title: Upgrading description: Upgrade Aura UI to the latest version and handle breaking changes. --- [TOC] > Looking for the release history? See the [Changelog](/changelog). ## Versioning Policy Aura UI follows [Semantic Versioning](https://semver.org/) (SemVer): | Version Change | Meaning | Example | |----------------|---------|---------| | **Major** (X.0.0) | Breaking changes that require code updates | 1.0.0 to 2.0.0 | | **Minor** (0.X.0) | New features, backward-compatible | 1.0.0 to 1.1.0 | | **Patch** (0.0.X) | Bug fixes, backward-compatible | 1.0.0 to 1.0.1 | Within a major version, you can update freely without worrying about breaking changes. Minor releases may add new components, props, or CSS classes, but never remove or rename existing ones. ## Upgrading the Free Package ### Standard Update To update to the latest version within your current major version constraint: ```bash composer update bluestarsystem/aura-ui ``` ### Re-Publish Assets After updating, re-publish the CSS assets to pick up any style changes or new component styles: ```bash php artisan vendor:publish --tag=aura-ui-css --force ``` > **Note:** The `--force` flag overwrites the published `resources/css/vendor/aura-ui/aura.css`. If you have customized this file directly, back it up before re-publishing. A better approach is to override styles in your own `app.css` rather than modifying the published file. ### Re-Publish Configuration (Optional) If a new version introduces new configuration options, you may want to re-publish the config file: ```bash php artisan vendor:publish --tag=aura-ui-config --force ``` Compare the new config with your existing one to merge any new options while preserving your customizations. ### Clear Caches After updating, clear the relevant caches: ```bash php artisan view:clear php artisan cache:clear php artisan config:clear ``` ### Rebuild Frontend Assets Recompile your CSS and JavaScript to pick up any new Tailwind classes from updated component views: ```bash npm run build ``` ### Complete Upgrade Checklist ```bash # 1. Update the package composer update bluestarsystem/aura-ui # 2. Re-publish CSS assets php artisan vendor:publish --tag=aura-ui-css --force # 3. Clear caches php artisan view:clear php artisan cache:clear # 4. Rebuild frontend npm run build # 5. Run your test suite php artisan test ``` ## Upgrading the Pro Package The Pro package follows the same upgrade flow, but pulls updates from the private Satis repository. ### Standard Update ```bash composer update bluestarsystem/aura-ui-pro ``` This also updates the Free package if a new compatible version is available. ### Re-Publish Pro Assets ```bash php artisan vendor:publish --tag=aura-ui-pro-css --force ``` ### Complete Pro Upgrade Checklist ```bash # 1. Update both packages composer update bluestarsystem/aura-ui bluestarsystem/aura-ui-pro # 2. Re-publish CSS assets php artisan vendor:publish --tag=aura-ui-css --force php artisan vendor:publish --tag=aura-ui-pro-css --force # 3. Clear caches php artisan view:clear php artisan cache:clear # 4. Rebuild frontend npm run build # 5. Run tests php artisan test ``` ### Authentication Issues If Composer fails to pull the Pro update, verify your authentication: ```bash # Check if auth.json exists and has valid credentials cat auth.json # Or test authentication directly composer show bluestarsystem/aura-ui-pro --all ``` If your license key has expired or changed, update it: ```bash composer config bearer.packages.elju.it AURA-XXXX-XXXX-XXXX-XXXX ``` Or edit `auth.json` directly: ```json { "bearer": { "packages.elju.it": "AURA-XXXX-XXXX-XXXX-XXXX" } } ``` ## Upgrading to a New Major Version Major version upgrades may contain breaking changes. Always read the upgrade guide for the specific major version before proceeding. ### General Major Upgrade Steps 1. **Read the changelog** for the new major version. Each major release includes a detailed list of breaking changes and migration steps. 2. **Update your `composer.json` constraint**: ```json { "require": { "bluestarsystem/aura-ui": "^2.0" } } ``` 3. **Run the update**: ```bash composer update bluestarsystem/aura-ui ``` 4. **Follow the migration guide** for the specific version. Common changes in major releases include: - Renamed components or props - Changed default values - Removed deprecated features - New required dependencies - CSS custom property changes 5. **Re-publish all assets**: ```bash php artisan vendor:publish --tag=aura-ui-config --force php artisan vendor:publish --tag=aura-ui-css --force ``` 6. **Update published views** if you have any. Compare your customized views (in `resources/views/vendor/aura/`) with the new vendor views. The easiest approach is to delete your published views and re-customize from the updated originals. 7. **Rebuild and test**: ```bash npm run build php artisan test ``` ## Handling Published Views If you have published and customized Blade component views, upgrading requires extra care because vendor updates do not touch published views. ### Checking for Outdated Published Views After upgrading, compare your published views with the new vendor views: ```bash # List your published views ls resources/views/vendor/aura/components/ # Compare a specific view diff resources/views/vendor/aura/components/button.blade.php \ vendor/bluestarsystem/aura-ui/resources/views/components/button.blade.php ``` ### Updating Published Views For each published view that has changed in the vendor package: 1. Review the diff to understand what changed 2. Apply the vendor changes to your published view, preserving your customizations 3. Or delete the published view to revert to the new vendor version, then re-apply your customizations ```bash # Option A: Delete and re-customize rm resources/views/vendor/aura/components/button.blade.php # Then copy and customize again from vendor # Option B: Manually merge changes # Edit the published view to incorporate vendor changes ``` > **Tip:** Keep published views to a minimum. Prefer CSS overrides and Tailwind utility classes for visual customization, and only publish views when you need to change the HTML structure. ## Breaking Changes Policy Aura UI follows these rules regarding breaking changes: ### What Constitutes a Breaking Change - Removing a component - Removing or renaming a component prop - Changing the default value of a prop in a way that alters existing behavior - Removing a CSS custom property - Changing the HTML structure of a component in a way that breaks existing CSS overrides - Dropping support for a PHP, Laravel, or Tailwind CSS version ### What Is NOT a Breaking Change - Adding new components - Adding new optional props with sensible defaults - Adding new CSS custom properties - Adding new CSS classes to component markup - Bug fixes that correct behavior to match documentation - Performance improvements - Internal refactoring that does not affect the public API ### Deprecation Process Features scheduled for removal in the next major version are deprecated first: 1. The feature is marked as deprecated in a minor release 2. A deprecation notice is logged or documented 3. The deprecated feature continues to work for the remainder of the current major version 4. The feature is removed in the next major version ## Changelog Each release includes a detailed changelog documenting all changes. Check the changelog before upgrading to understand what is new, changed, or fixed. ### Viewing the Changelog The changelog is available in the package repository: ```bash # View the changelog cat vendor/bluestarsystem/aura-ui/CHANGELOG.md ``` ### Changelog Format The changelog follows the [Keep a Changelog](https://keepachangelog.com/) format: ```markdown ## [2.0.1] - 2026-02-15 ### Added - New `StatsCard` component for dashboard metrics - `loading` prop on Button component for loading states ### Changed - Improved dark mode contrast on Input component borders ### Fixed - Modal closing animation stuttering on Safari - Tooltip positioning when near viewport edge ``` ## Pinning a Specific Version If you need to stay on a specific version (e.g., to avoid an issue in a newer release): ```json { "require": { "bluestarsystem/aura-ui": "2.0.0" } } ``` Or pin to a specific minor version: ```json { "require": { "bluestarsystem/aura-ui": "~2.0.0" } } ``` | Constraint | Meaning | |------------|---------| | `^2.0` | >= 2.0.0, < 3.0.0 (recommended) | | `~2.0.0` | >= 2.0.0, < 2.1.0 | | `2.0.0` | Exactly 2.0.0 | ## Rollback If an upgrade causes issues, you can roll back to the previous version: ```bash # Check what version you had before git diff composer.lock | grep aura-ui # Restore the previous composer.lock git checkout composer.lock # Re-install the previous versions composer install # Re-publish the previous assets php artisan vendor:publish --tag=aura-ui-css --force # Rebuild frontend npm run build ``` If you did not commit your `composer.lock` before upgrading, you can manually require the previous version: ```bash composer require bluestarsystem/aura-ui:2.0.0 php artisan vendor:publish --tag=aura-ui-css --force npm run build ``` ## Automated Updates For projects that want to stay on the latest version automatically, consider adding the update check to your CI/CD pipeline: ```bash # In your CI pipeline composer outdated bluestarsystem/aura-ui bluestarsystem/aura-ui-pro ``` This shows available updates without installing them, letting you decide when to upgrade. ## Getting Help If you encounter issues during an upgrade: 1. Check the [changelog](#changelog) for known issues 2. Clear all caches and rebuild assets 3. Verify your published views are compatible with the new version 4. Open an issue on the package repository with your Laravel version, PHP version, and the specific error ## Next Steps - [Getting Started](/docs/getting-started) -- Overview of Aura UI - [Installation](/docs/installation) -- Fresh installation instructions - [Configuration](/docs/configuration) -- Configuration options --- --- title: Accordion description: Collapsible content panels for organizing information into expandable sections. --- [TOC] > **Pro Component** — This component requires an Aura UI Pro license. ## Overview The Accordion component provides collapsible content panels that allow users to show and hide sections of related content. Built with Alpine.js for smooth animations, it supports single or multiple open panels, custom icons, and default open states. ## Basic Usage :::example Content for section one goes here. Content for section two goes here. ::: ```html Content for section one goes here. Content for section two goes here. ``` ## Props ### Accordion | Prop | Type | Default | Description | |------|------|---------|-------------| | `multiple` | `bool` | `false` | Allow multiple panels to be open simultaneously. | ### Accordion Item | Prop | Type | Default | Description | |------|------|---------|-------------| | `title` | `string` | `''` | The heading text displayed in the trigger button. | | `open` | `bool` | `false` | Whether the panel is open by default. | | `icon` | `string\|null` | `null` | Optional icon name displayed before the title. | ## Examples ### FAQ Section :::example We accept Visa, Mastercard, American Express, and PayPal. All transactions are processed securely through Stripe. Standard shipping takes 5-7 business days. Express shipping is available for 2-3 business day delivery. We offer a 30-day money-back guarantee on all products. Items must be in original condition with packaging intact. ::: ```html We accept Visa, Mastercard, American Express, and PayPal. All transactions are processed securely through Stripe. Standard shipping takes 5-7 business days. Express shipping is available for 2-3 business day delivery. We offer a 30-day money-back guarantee on all products. Items must be in original condition with packaging intact. ``` ### Multiple Open Panels :::example
::: ```html
``` ### With Icons and Default Open :::example View and manage your account details, profile picture, and personal information. Configure two-factor authentication, password policies, and active sessions. Manage your subscription plan, payment methods, and view billing history. Control which notifications you receive via email, SMS, or push notifications. ::: ```html View and manage your account details, profile picture, and personal information. Configure two-factor authentication, password policies, and active sessions. Manage your subscription plan, payment methods, and view billing history. Control which notifications you receive via email, SMS, or push notifications. ``` ### Nested Content with Rich HTML :::example
Weight 1.2 kg
Dimensions 30 x 20 x 10 cm
Material Recycled aluminum
::: ```html
Weight 1.2 kg
Dimensions 30 x 20 x 10 cm
Material Recycled aluminum
``` ## Slots | Slot | Component | Description | |------|-----------|-------------| | default | `accordion` | Contains `accordion.item` children. | | default | `accordion.item` | The collapsible content of each panel. | ## Accessibility - Each accordion header is a ` ::: ```html
Controlled externally.
``` ## Accessibility - The component renders with `role="alert"`, which announces content to screen readers. - The dismiss button includes `aria-label="Chiudi"` for assistive technology. - Color is not the only indicator of variant -- each variant also has a distinct default icon. - Dismissible alerts use `x-transition` for smooth show/hide animations. - Focus management: after dismissal, focus returns to the natural tab order. --- --- title: Autocomplete description: Searchable input field with dropdown suggestions, supporting both static options and Livewire server-side search. --- [TOC] > **Pro Component** — This component requires an Aura UI Pro license. ## Overview The Autocomplete component provides a text input with a dynamic dropdown of filtered suggestions. It supports both static option arrays and server-side search via Livewire integration. As the user types, matching results appear in a dropdown, allowing quick selection. Built with Alpine.js for instant client-side filtering and optional debounced server-side requests. ## Basic Usage :::example ::: ```html ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `label` | `string` | `''` | Label text displayed above the input. | | `name` | `string` | `''` | The input name attribute, also used for `wire:model`. | | `options` | `array` | `[]` | Array of options. Each item can be a string or `['value' => ..., 'label' => ...]`. | | `placeholder` | `string` | `''` | Placeholder text shown when the input is empty. | | `minChars` | `int` | `1` | Minimum characters required before showing suggestions. | | `error` | `string\|null` | `null` | Validation error message to display below the input. | ## Examples ### Simple String Options :::example ::: ```html ``` ### Key-Value Options :::example ::: ```html ``` ### Livewire Server-Side Search For large datasets, use Livewire to fetch results from the server. Bind the input with `wire:model.live.debounce.300ms` and update the options dynamically. ```html ``` ```php // In your Livewire component class use Livewire\Component; class OrderForm extends Component { public string $customerSearch = ''; public array $customerResults = []; public ?int $customer_id = null; public function updatedCustomerSearch(string $value): void { if (strlen($value) < 3) { $this->customerResults = []; return; } $this->customerResults = Customer::query() ->where('name', 'like', "%{$value}%") ->orWhere('email', 'like', "%{$value}%") ->limit(10) ->get() ->map(fn ($c) => ['value' => $c->id, 'label' => "{$c->name} ({$c->email})"]) ->toArray(); } } ``` ### Tag Suggestions :::example ::: ```html ``` ### With Validation Error :::example ::: ```html ``` ## Slots | Slot | Description | |------|-------------| | default | Not used. Options are passed via the `options` prop. | The dropdown list is rendered automatically based on the `options` prop. Each option displays the `label` (or string value) and submits the corresponding `value` when selected. ## Accessibility - The input has `role="combobox"` with `aria-autocomplete="list"`. - The dropdown list uses `role="listbox"` with each option as `role="option"`. - `aria-expanded` indicates whether the dropdown is visible. - `aria-activedescendant` tracks the currently highlighted option. - **Arrow Up/Down** navigate through the suggestion list. - **Enter** selects the highlighted option. - **Escape** closes the dropdown without selecting. - The component associates the label with the input via `for`/`id` attributes. --- --- title: Avatar description: Visual representation of a user or entity with image, initials, or icon fallback. --- [TOC] ## Overview The Avatar component displays a user's profile image, auto-generated initials, or a fallback icon. It supports multiple sizes, rounded styles, a status indicator (online, offline, busy), and automatic color assignment based on the user's name. Use avatars for: - User profile pictures - Comment/message author indicators - Team member lists - Navigation bars and sidebars ## Basic Usage :::example ::: ```html ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `src` | `string\|null` | `null` | Image URL. When set, renders an `` tag | | `name` | `string\|null` | `null` | Full name for auto-generating initials and color | | `initials` | `string\|null` | `null` | Explicit initials (overrides auto-generation from `name`) | | `alt` | `string` | `''` | Alt text for the image | | `size` | `string` | `'md'` | Size: `xs`, `sm`, `md`, `lg`, `xl` | | `color` | `string\|null` | `null` | Background color for initials avatar. Auto-assigned from `name` when `null` | | `status` | `string\|null` | `null` | Status indicator: `online`, `offline`, `busy` | | `rounded` | `string` | `'full'` | Border radius: `full` (circle), `lg`, `md`, `sm`, `none` | Available auto-colors: `primary`, `success`, `warning`, `danger`, `info`, `purple`, `pink`, `teal`, `orange`, `indigo`. ## Variants/Examples ### Image Avatar with Status :::example ::: ```html ``` ### Initials from Name The component auto-generates initials from the `name` prop. For two-word names it takes the first letter of each word; for single names it takes the first two letters. :::example ::: ```html {{-- Renders "JD" with a consistent background color --}} ``` ### Explicit Initials and Color :::example ::: ```html ``` ### Fallback Icon (No Image or Name) When neither `src` nor `name`/`initials` is provided, a generic user icon is displayed. :::example ::: ```html ``` ### Different Sizes :::example ::: ```html ``` ### Rounded Variants :::example ::: ```html {{-- Circle (default) --}} {{-- Large border radius --}} {{-- Square --}} ``` ## Sub-components ### Avatar Group Use `` to stack multiple avatars with overlapping layout. :::example ::: ```html ``` ## Slots The Avatar component does not use named slots. All content is driven by props. ## Accessibility - When `src` is set, the `` tag includes `alt` text (falls back to `name` if `alt` is empty). - Initials are rendered as a `` which is visible to screen readers. - The status indicator is purely visual (a colored dot). For screen reader support, add `aria-label` via attributes: :::example ::: ```html ``` - Color assignments are deterministic per name, providing a consistent visual identity. --- --- title: Badge description: Small status indicators and labels for categorization, counts, and states. --- [TOC] ## Overview The Badge component renders small inline labels used to highlight statuses, categories, counts, or tags. Badges support multiple color variants, sizes, outline and gradient styles, optional dot indicators, icons, and a removable close button. Use badges for: - Status indicators (Active, Pending, Archived) - Category or tag labels - Notification counts - Feature flags or markers ## Basic Usage :::example Active ::: ```html Active ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `variant` | `string` | `'primary'` | Color variant: `primary`, `secondary`, `success`, `warning`, `danger`, `info` | | `size` | `string` | `'md'` | Size: `sm`, `md`, `lg` | | `dot` | `bool` | `false` | Show a small dot indicator before the text | | `icon` | `string\|null` | `null` | Icon name displayed before the text | | `removable` | `bool` | `false` | Show a remove/close button after the text | | `outline` | `bool` | `false` | Outline style (transparent background, colored border) | | `gradient` | `bool` | `false` | Gradient background style | | `rounded` | `bool` | `false` | Fully rounded pill shape | ## Variants/Examples ### Color Variants :::example Primary Secondary Success Warning Danger Info ::: ```html Primary Secondary Success Warning Danger Info ``` ### With Dot Indicator :::example Online Offline ::: ```html Online Offline ``` ### With Icon :::example Pending Verified ::: ```html Pending Verified ``` ### Outline Style :::example Draft Expired ::: ```html Draft Expired ``` ### Gradient Style :::example Premium New ::: ```html Premium New ``` ### Removable Badge (Tag Pattern) :::example Laravel Tailwind Alpine.js ::: ```html Laravel Tailwind Alpine.js ``` ### Size Comparison :::example Small Medium Large ::: ```html Small Medium Large ``` ## Slots | Slot | Description | |------|-------------| | Default | The badge text content | ## Events When `removable` is set to `true`, a remove button is rendered. You can handle the click event with Alpine.js or Livewire: ```html {{-- Alpine.js --}} Laravel {{-- Livewire --}} Laravel ``` ## Accessibility - Badges render as `` elements, which are inline and visible to screen readers. - The removable button includes `aria-label="Remove"` for assistive technology. - Color is supplemented by text content, so information is not conveyed by color alone. - When using badges as interactive elements, ensure they have appropriate ARIA roles. - Dot indicators are purely decorative; their meaning should be conveyed through the badge text. --- --- title: Brand description: A brand identity component that combines a logo image and application name into a navigable link. --- [TOC] ## Overview The `` component renders a clickable brand identity element combining an optional logo image, an application name, or custom slot content. It is designed for use in navbars, sidebars, and page headers where a consistent brand mark is needed. Use brand for: - Navbar brand links - Sidebar logo and app name - Footer brand identity - Login/auth page headers ## Basic Usage :::example ::: ```html ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `logo` | `string\|null` | `null` | URL of the logo image. When provided, renders an `` element | | `name` | `string\|null` | `null` | Application name displayed next to the logo | | `href` | `string` | `'/'` | Link destination URL | | `size` | `string` | `'md'` | Size variant: `sm`, `md`, `lg` | Size dimensions: - `sm` -> logo `h-6 w-6`, text `text-sm` - `md` -> logo `h-8 w-8`, text `text-base` - `lg` -> logo `h-10 w-10`, text `text-xl` ## Slots | Slot | Description | |------|-------------| | Default | Custom content rendered when neither `logo` nor `name` is provided | ## Variants / Examples ### Logo Only :::example ::: ```html ``` ### Name Only :::example ::: ```html ``` ### Logo and Name :::example ::: ```html ``` ### Size Variants :::example
::: ```html
``` ### Custom Slot Content :::example
My App
::: ```html
My App
``` ### Icon as Logo :::example
StarApp
::: ```html
StarApp
``` ### In a Navbar :::example
Acme Inc
::: ```html {{-- nav items... --}} ``` ## Accessibility - The component renders as an `` tag, making it keyboard-focusable and navigable. - When a `logo` is provided, the `` tag includes `alt` text derived from the `name` prop. - The link applies `no-underline` styling to keep the brand element visually clean. --- --- title: Breadcrumbs description: Navigation aid showing the current page location within a hierarchical structure. --- [TOC] ## Overview The Breadcrumbs component renders a navigation trail that helps users understand their current location within the application hierarchy. Each item can be a link or plain text (for the current/last item). The component supports different separator styles and optional icons per item. Use breadcrumbs for: - Multi-level page hierarchies - Admin panel navigation - Content management paths - E-commerce category navigation ## Basic Usage :::example ::: ```html ``` ## Props | Prop | Type | Default | Description | |------|------|---------|-------------| | `items` | `array` | `[]` | Array of breadcrumb items. Each item: `['label' => string, 'href' => string\|null, 'icon' => string\|null]` | | `separator` | `string` | `'chevron'` | Separator style: `chevron` (>), `slash` (/), `dot` (.) | ### Item Structure Each item in the `items` array accepts: | Key | Type | Required | Description | |-----|------|----------|-------------| | `label` | `string` | Yes | Display text for the breadcrumb | | `href` | `string` | No | URL. Omit for the current page (last item) | | `icon` | `string` | No | Icon name displayed before the label | ## Variants/Examples ### With Laravel Routes :::example ::: ```html ``` ### Slash Separator :::example ::: ```html ``` ### Dot Separator :::example ::: ```html ``` ### With Icons :::example ::: ```html ``` ### Dynamic from Controller ```php // In your controller or Livewire component: $breadcrumbs = [ ['label' => 'Products', 'href' => route('products.index')], ['label' => $category->name, 'href' => route('categories.show', $category)], ['label' => $product->name], ]; ``` ```html ``` ## Slots The Breadcrumbs component does not use slots. All content is driven by the `items` prop. ## Accessibility - The component renders inside a `