Skip to content

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:

php artisan vendor:publish --tag=aura-ui-config --force

Default Configuration

Here is the full default configuration with all available options:

<?php
// config/aura-ui.php

return [
    /*
    |--------------------------------------------------------------------------
    | Component Prefix
    |--------------------------------------------------------------------------
    |
    | All Aura UI components are prefixed with this value.
    | Usage: <x-aura::button>, <x-aura::input>, etc.
    |
    */
    'prefix' => 'aura',

    /*
    |--------------------------------------------------------------------------
    | Dark Mode
    |--------------------------------------------------------------------------
    |
    | How dark mode is detected. Options:
    | - 'class': Dark mode via .dark class on <html> (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:

<x-aura::button>Click me</x-aura::button>
<x-aura::card>Content</x-aura::card>

Customizing the Prefix

If aura conflicts with another package or you prefer a different namespace, change the prefix:

// config/aura-ui.php
'prefix' => 'ui',

After changing the prefix, all components use the new namespace:

<x-ui::button>Click me</x-ui::button>
<x-ui::card>Content</x-ui::card>

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:

php artisan view:clear

Dark Mode Detection

The dark_mode option controls how Aura UI components detect dark mode:

Class Strategy (Default)

'dark_mode' => 'class',

Components respond to the .dark class on the <html> element. This gives you full control over when dark mode is active, typically toggled via Alpine.js or JavaScript.

<html class="dark">
    <!-- All Aura UI components render in dark mode -->
</html>

This is the recommended approach. See the 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 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.).

'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 composer require blade-ui-kit/blade-heroicons

Installing the Icon Package

Aura UI does not bundle icons. Install your preferred icon package separately:

composer require blade-ui-kit/blade-heroicons

Using Icons in Components

The <x-aura::icon> component renders icons from the configured set:

<!-- Uses the default icon set from config -->
<x-aura::icon name="check" class="w-5 h-5" />

<!-- Outline variant (default) -->
<x-aura::icon name="o-arrow-right" class="w-4 h-4" />

<!-- Solid variant -->
<x-aura::icon name="s-heart" class="w-4 h-4 text-red-500" />

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.

'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 below).

Customizing the Path

Change the URL where the playground is accessible:

'playground' => [
    'enabled' => true,
    'path' => 'dev/components',     // Now at /dev/components
    'middleware' => ['web'],
],

Adding Authentication

Restrict playground access to authenticated users or specific roles:

'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:

// 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
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:

# 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:

# 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:

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:

php artisan config:cache

Remember to re-cache after any changes to config/aura-ui.php:

php artisan config:clear
php artisan config:cache

Next Steps

  • Theming -- Customize colors, fonts, and the Vibrant Depth design
  • Dark Mode -- Set up light/dark theme switching
  • Upgrading -- Keep Aura UI up to date