BladewindUI: Getting Started
BladewindUI

Getting Started

BladewindUI is a collection of UI components built with TailwindCSS, Laravel Blade templates, and vanilla JavaScript. Every component is simple to use and ships with sensible defaults you can override per-project.

Requirements

  • PHP >= 8.0
  • Laravel >= 9.x
  • TailwindCSS >= 4.x

    • Installation Options

    There are three ways to install BladewindUI depending on how much of the library you need.

    Install everything

    Pull in every component at once. This is the easiest way to get started and is ideal for new projects or if you want to explore the full library. 

    composer require bladewindui/ui

    Install a component group

    Components are organised into three groups. Install a group when you only need a logical subset of BladewindUI. See the component groups section below for exactly which components each group contains. 

    composer require bladewindui/forms
    composer require bladewindui/content
    composer require bladewindui/navigation

    Install a single component

    The library also allows users to pick only the components they need. This is ideal for existing projects where you want to introduce BladewindUI gradually, or if you only need one or two components. 

    composer require bladewindui/table
    composer require bladewindui/accordion
    composer require bladewindui/datepicker

    All shared dependencies, such as the Icon, Spinner, and core helper utilities, are automatically installed by Composer when you require any BladewindUI package. You do not need to install or configure these dependencies yourself; Composer’s dependency resolution ensures everything required is available and up to date.

    First-time Setup

    After installing, publish the compiled CSS, JavaScript, and language files to your project's public directory. 

    php artisan vendor:publish --tag=bladewind-public --force

    Add the stylesheet to the <head> of your layout file. Your own CSS should come after the BladewindUI stylesheet so your customisations take effect. 

            
            <link href="{{ asset('vendor/bladewind/css/bladewind-ui.min.css') }}" rel="stylesheet" />

    If your app already has its own Tailwind build

    The stylesheet above ships Tailwind's Preflight, a global reset including *,::before,::after { border: 0 solid }. That is the right thing for a page whose only stylesheet is BladewindUI, and the wrong thing for an app that already compiles its own Tailwind: the document gets reset twice, in an order nobody controls. Use the Preflight-free variant instead. 

            
            <link href="{{ asset('vendor/bladewind/css/bladewind-ui-no-preflight.min.css') }}" rel="stylesheet" />

    The component rules in the two files are identical, because both are built from one shared source, so they cannot drift. The variant only drops the global reset. Tailwind's forms base styles stay in, because the components are built on them.

    Load one or the other, never both. If you are not sure which you need, start with bladewind-ui.min.css; reach for the variant only if adding BladewindUI visibly changes your own components.

    Add the JavaScript anywhere before the closing </body> tag. The @bladewindScripts directive emits the tags for you. 

            
            @bladewindScripts

    That gives you helpers.js, which every component assumes. Components with their own JavaScript take their name as an argument: 

            
            @bladewindScripts('select', 'dropmenu', 'datepicker')

    Recognised names are select, dropmenu, datepicker, table, notification, mask, animations, sortable and tooltip. An unrecognised name is ignored rather than breaking the page, and a nonce set in config('bladewind.script.nonce') is applied to every tag.

    Chart, Filepicker and the image cropper are not in that list on purpose. Those components load their own dependencies when they render, so a page that does not use them never fetches them.

    Writing the tags by hand still works, if you prefer: 

            
            <script src="{{ asset('vendor/bladewind/js/helpers.js') }}"></script>

    Helper functions such as showModal() and hideModal() are available on window, so you can call them from your own scripts and inline handlers without any extra wiring.

    You are ready to use any BladewindUI component in your application.


            
            <x-bladewind::button>Save User</x-bladewind::button>

    You can define your primary, secondary, and dark-mode colours in your project's tailwind.config.js file. More on customising colours here.

    Content Security Policy

    BladewindUI works under a strict script-src without 'unsafe-inline'. No component attaches its behaviour with an inline onclick or similar. Those are bound as delegated listeners instead, which a CSP allows.

    Set your nonce once and every script tag the library emits carries it: 

        
        // config/bladewind.php

    'script' => [
        'nonce' => fn () => request()->attributes->get('csp-nonce'),
    ],

    Individual components also take a nonce attribute if you would rather pass it per component.

    Publishing Components

    The double-colon syntax (x-bladewind::button) serves views directly from the package's vendor directory. To use the dot syntax instead, publish the component views to your own resources/views/components/bladewind directory: 

    php artisan vendor:publish --tag=bladewind-components --force

    You can then call components using the dot syntax:

            
            <x-bladewind.button>Save User</x-bladewind.button>
    If you use the dot syntax, republish the component views after every BladewindUI update.

    Component Groups

    Components are organised into groups. Each group is a Composer metapackage: it contains no code of its own, just a list of dependencies. Installing a group is identical to installing every component in that group individually. Components can also be installed as standalone packages outside any group.

    Standalone Packages

    These components are not bundled into any group. They are pulled in automatically as dependencies by other components that need them, but you can also require them directly.

    Component Composer package Includes
    Breadcrumbs bladewindui/breadcrumbs Breadcrumbs, Breadcrumbs Item
    Stepper bladewindui/stepper Stepper, Stepper Item, Stepper Content
    Sidebar bladewindui/sidebar Sidebar, Sidebar Group, Sidebar Item
    Command Palette bladewindui/command-palette Command Palette, Command Palette Group, Command Palette Item
    Core bladewindui/core Shared helpers, CSS variables, helpers.js
    Icon bladewindui/icon SVG icon wrapper (Heroicons)
    Button bladewindui/button Button, Circle Button
    Modal bladewindui/modal Modal, Modal Icon
    Drawer bladewindui/drawer Drawer
    Alert bladewindui/alert Alert, Notification, Bell
    Spinner bladewindui/spinner Spinner, Shimmer, Processing, Process Complete
    Table bladewindui/table Table, Table Icons
    Data Grid bladewindui/data-grid Data Grid
    Calendar bladewindui/calendar Calendar

    Forms Group: bladewindui/forms

    composer require bladewindui/forms
    Component Composer package Includes
    Input bladewindui/input Input, Error
    Textarea bladewindui/textarea Textarea
    Select bladewindui/select Select, Select Item
    Checkbox bladewindui/checkbox Checkbox
    Radio Button bladewindui/radio Radio Button
    Toggle bladewindui/toggle Toggle
    Datepicker bladewindui/datepicker Datepicker
    Timepicker bladewindui/timepicker Timepicker
    Colorpicker bladewindui/colorpicker Colorpicker
    Filepicker bladewindui/filepicker Filepicker (powered by FilePond)
    Slider bladewindui/slider Slider
    Checkcards bladewindui/checkcards Checkcards, Checkcard
    Number bladewindui/number Number stepper
    Verification Code bladewindui/code Verification Code / OTP input

    Content Group: bladewindui/content

    composer require bladewindui/content
    Component Composer package Includes
    Card bladewindui/card Card, Contact Card
    Avatar bladewindui/avatar Avatar, Avatars
    Accordion bladewindui/accordion Accordion, Accordion Item
    Tag bladewindui/tag Tag, Tags
    Timeline bladewindui/timeline Timeline, Timelines
    Statistic bladewindui/statistic Statistic
    Rating bladewindui/rating Rating
    Horizontal Line Graph bladewindui/horizontal-line-graph Horizontal Line Graph
    Empty State bladewindui/empty-state Empty State
    Centered Content bladewindui/centered-content Centered Content
    Chart bladewindui/chart Chart (line, bar, pie, donut)
    Progress bladewindui/progress Progress Bar, Progress Circle
    List View bladewindui/listview List View, List View Item
    Drawer bladewindui/drawer Drawer

    Navigation Group: bladewindui/navigation

    composer require bladewindui/navigation
    Component Composer package Includes
    Breadcrumbs bladewindui/breadcrumbs Breadcrumbs, Breadcrumbs Item
    Stepper bladewindui/stepper Stepper, Stepper Item, Stepper Content
    Sidebar bladewindui/sidebar Sidebar, Sidebar Group, Sidebar Item
    Command Palette bladewindui/command-palette Command Palette, Command Palette Group, Command Palette Item
    Tab bladewindui/tab Tab, Tab Body, Tab Content, Tab Heading
    Dropmenu bladewindui/dropmenu Dropmenu, Dropmenu Item
    Theme Switcher bladewindui/theme-switcher Theme Switcher (light / dark)

    How Groups Work

    The three group packages (bladewindui/forms, bladewindui/content, bladewindui/navigation) contain no code: they are pure Composer metapackages whose only job is to pull in the right leaf packages. This means:

    • Installing bladewindui/content is identical to installing every content leaf package individually.
    • Uninstalling a group and requiring just one leaf package (e.g. bladewindui/accordion) is clean and leaves nothing behind.
    • Each leaf package registers its own Laravel service provider, so components are auto-discovered whether you install them individually or as part of a group.

    Customising Defaults

    Every attribute in every component has a project-level default you can override once and have it apply everywhere. Publish the config file (available when using the full bladewindui/ui package): 

    php artisan vendor:publish --tag=bladewind-config

    This creates config/bladewind.php in your project. Edit any value there and all component instances will follow suit. No need to set the attribute on every tag. See the full customisation guide for details.

    Updating BladewindUI

    Run composer update to pull in the latest version. 

    composer update

    Then republish the public assets to pick up any CSS or JavaScript changes: 

    php artisan vendor:publish --tag=bladewind-public --force

    If you are using the dot syntax, also republish the component views: 

    php artisan vendor:publish --tag=bladewind-components --force

    To automate both publish steps after every composer update, add the following to your composer.json under scripts: 

            
        "scripts": {
            "post-update-cmd": [
                "@php artisan vendor:publish --tag=laravel-assets --ansi",
                "@php artisan vendor:publish --tag=bladewind-public --force",
                // add this line only if you also publish component views
                "@php artisan vendor:publish --tag=bladewind-components --force"
            ]
        }