Weave Code
Laravel Headless Ui Laravel Package
schaefersoft/laravel-headless-ui
Accessible, unstyled Headless UI components for Laravel Blade. Build dropdowns, dialogs, tabs, tooltips and more without JS dependencies.
Frequently asked questions about Laravel Headless Ui
- How do I install and set up Laravel HeadlessUI in a Laravel 11 project?
- Run `composer require schaefersoft/laravel-headless-ui` to install. The package auto-discovers its service provider, so no manual registration is needed. Import the CSS via `@import '../../vendor/schaefersoft/laravel-headless-ui/resources/css/hui.css'` (or `layer(base)` for Tailwind). For JS, use the pre-built `hui.js` or the TypeScript source `hui.ts` if your build pipeline supports it.
- Does this package work with Tailwind CSS, and how do I integrate it?
- Yes, Laravel HeadlessUI supports Tailwind CSS via the `layer(base)` directive. Import the CSS with `@import '../../vendor/schaefersoft/laravel-headless-ui/resources/css/hui.css' layer(base)` in your Tailwind config. The package uses data attributes for states, so your utility classes can override styles seamlessly.
- Can I use Laravel HeadlessUI without JavaScript, or does it require Alpine.js/Inertia?
- The package is designed for progressive enhancement—it works without JavaScript. However, you can enhance components with Alpine.js, Inertia.js, or other frameworks for interactivity. The JS bundle is optional and only adds interactivity where needed.
- What Laravel and PHP versions are supported, and will this work with Laravel 14?
- The package supports Laravel 10–13 and PHP 8.2+. While Laravel 14 isn’t officially listed, the MIT license and active releases suggest future compatibility. Monitor the GitHub repo for updates, as breaking changes in Laravel 14 may require adjustments.
- Are the components accessible (WCAG/ARIA compliant), and how can I test them?
- Components claim WCAG/ARIA compliance, but real-world testing is recommended. Use tools like axe-core or Pa11y for automated checks, and manually test with screen readers (NVDA, VoiceOver). The unstyled nature means custom CSS could unintentionally break accessibility, so validate keyboard navigation and focus states.
- How do I migrate from Bootstrap or custom jQuery UI to Laravel HeadlessUI?
- Start with a pilot: replace 1–2 components (e.g., dropdowns or tabs) in a non-critical section. Document your custom styles (e.g., `.hui-*` overrides) and test interactions. Deprecate legacy JS logic incrementally, replacing it with the package’s headless semantics. Use Blade directives like `x-hui::dropdown` for a drop-in replacement.
- What if I need a component not included in this package, like a datepicker?
- The package focuses on core unstyled components (dropdowns, tabs, sliders, etc.). For missing features, check if the package’s architecture (Blade directives + JS) can be extended. Alternatively, build a custom component using the same headless pattern, or explore alternatives like Headless UI (Tailwind-specific) or Alpine.js plugins.
- How does the package handle performance, and should I use the pre-built JS or TypeScript?
- The pre-built `hui.js` is ~5KB gzipped and works out of the box. Use it for simplicity. If your project uses Vite or Webpack with TypeScript, import `hui.ts` for tree-shaking benefits. The TypeScript source adds build-step complexity but enables customization. Test both options to measure impact on your bundle size.
- Are there alternatives to Laravel HeadlessUI for Laravel Blade components?
- Alternatives include Tailwind’s Headless UI (Tailwind-specific), Livewire components (for server-driven interactivity), or Alpine.js plugins. Headless UI is more opinionated (Tailwind-only), while Livewire adds server-side logic. Laravel HeadlessUI stands out for its Blade-centric, unstyled, and framework-agnostic approach.
- How do I contribute or report issues if I find bugs in accessibility or functionality?
- Check the [GitHub Issues](https://github.com/schaefersoft/laravel-headless-ui/issues) tab for existing reports. Open a new issue with clear steps to reproduce, including Laravel/PHP versions. For accessibility bugs, include screen reader logs or axe-core output. Contributions are welcome via pull requests, following the project’s MIT license.
Weaver
How can I help you explore Laravel packages today?