DEV Community

Krishnaprasad R (RK)
Krishnaprasad R (RK)

Posted on

Try Bladewell in a Laravel App: Install, Customize, and Update Your First Component

#laravel #php #webdev #ai

In my first post, I introduced Bladewell and explained why I wanted Laravel UI components that work without adopting another JavaScript framework.

This time, let's look at what happens when you actually bring a component into an app.

The useful test for a UI library comes after the demo: can you make it fit your project, and can you still maintain it after you do?

Start with one component

Use an existing Blade application with PHP 8.3+, Laravel 12 or 13, Tailwind CSS 4.1+, and Vite. The datepicker also requires PHP's intl extension.

From your project directory:

composer require --dev bladewell/bladewell
php artisan bladewell:add datepicker
npm run build
Enter fullscreen mode Exit fullscreen mode

The installer brings in the datepicker and its supporting components. You don't need to install the entire catalogue to try one field.

Use it in a Blade view:

<x-widget.datepicker name="start_date" />
Enter fullscreen mode Exit fullscreen mode

Your page should load your application's Vite assets as usual.

Open the files it added

The source lives inside your application. With the default paths, look here:

resources/views/components/widget/datepicker/
resources/js/widget/datepicker/
resources/css/widget/theme.css
Enter fullscreen mode Exit fullscreen mode

The Blade files control the markup, the JavaScript handles interaction, and the theme file contains shared design tokens.

Try a small change first. Adjust a theme value, rebuild your assets, and see how it looks alongside the rest of your app.

For a more specific change, edit the component itself. That is the point of copying the source into your project: customization becomes an ordinary code change you can review and commit.

What happens when an update arrives?

Owning the source also means taking responsibility for your changes.

Bladewell records installed file hashes in bladewell.lock. Commit that file alongside your component changes.

After updating the package, refresh installed components with:

composer update bladewell/bladewell
php artisan bladewell:add --installed
Enter fullscreen mode Exit fullscreen mode

The installer updates eligible unedited files and reports edited files it skips. Shared theme and base CSS are preserved.

To inspect differences:

php artisan bladewell:diff
Enter fullscreen mode Exit fullscreen mode

Review relevant upstream fixes and merge them into your customized files. This doesn't remove maintenance work, but it makes the decisions visible.

Try it in the app you already have

Bladewell uses vanilla JavaScript for interaction. Alpine and Livewire aren't prerequisites, and the widgets also support Livewire 3 and 4.

It is designed for Blade and Tailwind v4 projects. If your pages are React or Vue through Inertia, this isn't the component layer for those pages.

My suggestion is to start with one field on an existing form. Check it against your own layout, validation flow, and keyboard interactions before adopting more components.

Bladewell is free and MIT licensed.

Which UI component takes the most work to customize in your Laravel projects—and what do you usually need to change?

Top comments (0)