README

Nue UI is a single Composer package containing Blade components, Livewire integration, Tailwind utilities, browser behavior, and an optional embedded documentation application.

Requirements

Dependency	Supported versions
PHP	8.2–8.x
Laravel / Illuminate	10, 11, 12, 13
Livewire	4.x
Tailwind CSS	4.x

Installation

Install one package:

composer require nuewire/ui

php artisan nue:install

The command updates resources/css/app.css by default. Use another entry file when required:

php artisan nue:install --css=resources/styles/application.css

Create a missing entry file with:

php artisan nue:install --css=resources/styles/application.css --force

The installer is idempotent and will not duplicate existing directives.

Application layout

Add the appearance bootstrap near the top of <head>. Load the package runtime after Livewire's scripts.

<!doctype html>
<html lang="en">
<head>
    @nueAppearance
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @livewireStyles
</head>
<body>
    {{ $slot }}

    @livewireScripts
    @nueScripts
</body>
</html>

Components

Use Nue's short-tag syntax:

<nue:button variant="primary">
    Save changes
</nue:button>

It compiles to standard namespaced Blade syntax:

<x-nue::button variant="primary">
    Save changes
</x-nue::button>

Publish the UI configuration to disable short tags:

php artisan nue:publish --config

'blade_short_tags' => false,

Bundled documentation

The documentation application is included in nuewire/ui; there is no separate nuewire/docs dependency.

Documentation routes are disabled by default. Enable them only in the environments where they are intended to be reachable:

NUE_DOCS_ENABLED=true
NUE_DOCS_PREFIX=docs

php artisan nue:install --docs
npm run build

The documentation is then available at /docs unless NUE_DOCS_PREFIX is changed. Route names continue to use the nue-docs.* prefix for compatibility.

Publish documentation configuration or views only when the application needs to own them:

php artisan nue:publish --docs

Run the documentation integrity audit from the package root:

composer audit-docs

Local path repository

A monorepo or local Laravel application needs only one path repository:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/nuewire/ui",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "nuewire/ui": "dev-main"
    }
}

Remove any root requirement and path repository for nuewire/docs, then run:

composer update nuewire/ui -W

The package declares nuewire/docs as replaced by the matching nuewire/ui version to ease migration from the former split-package structure.

Publishing files

Publish only the files the application intends to maintain:

php artisan nue:publish --config
php artisan nue:publish --views
php artisan nue:publish --components
php artisan nue:publish --assets
php artisan nue:publish --docs

Publish all supported resources:

php artisan nue:publish --all

Use --force only after reviewing the files that will be overwritten.

Appearance

The default appearance is system. Supported values are light, dark, and system.

window.Nue.setAppearance('dark')

'appearance' => [
    'storage_key' => 'nue.appearance',
    'default' => 'system',
],

Background presets

The distributed stylesheet includes decorative background utilities with coordinated light and dark variants:

<section class="bg-nue-aurora min-h-screen">
    <!-- Page content -->
</section>

Available classes are bg-nue-aurora, bg-nue-ocean, bg-nue-sunset, bg-nue-lavender, bg-nue-forest, bg-nue-rose, bg-nue-sand, bg-nue-sky, bg-nue-mint, and bg-nue-graphite. bg-custom-gradient remains an alias for bg-nue-aurora.

Dark variants activate automatically when an ancestor has the dark class. The bundled documentation page at /docs/guides/backgrounds provides live previews and copy-ready CSS.

Modals

From JavaScript or Alpine:

window.Nue.modal('settings').show()
window.Nue.modal('settings').close()
window.Nue.modals().close()

From a Livewire component:

use Nuewire\Ui\Concerns\InteractsWithNueModals;

class AccountSettings extends Component
{
    use InteractsWithNueModals;

    public function openSettings(): void
    {
        $this->modal('settings')->show();
    }
}

Asset mode and Iconify

Scripts are inlined by default. To serve the bundled runtime from public/vendor/nue/nue.js, publish the assets and change the configuration:

'assets' => [
    'inline' => false,
    'script' => 'vendor/nue/nue.js',
],

Iconify is enabled by default and loaded from the configured CDN. Disable it when the application supplies local icons or enforces a restrictive Content Security Policy:

'iconify' => [
    'enabled' => false,
],

License

Nue UI is released under the MIT License.

nuewire / ui

Maintainers

Package info

Statistics

Security