Frequently asked questions

The most common problems with short answers; the linked pages have the details.

Installation

Components appear but are unstyled

Tailwind isn't scanning the package's Blade files. Your CSS file (resources/css/acun-ui.css in the theme) must contain the line @source '../../vendor/acunsoft/acun-ui-free/resources/views';. npm run dev must be running, or you must have built with npm run build. See CSS, JavaScript and build.

A chart, map, or date picker stays empty

ApexCharts, Leaflet and flatpickr aren't dependencies of the package. Install them in your application and register them with Alpine using registerChart, registerMap and registerDateRangePicker; in the theme, this code is in resources/js/app.js. You also need to load leaflet/dist/leaflet.css for the map and flatpickr/dist/flatpickr.min.css for the date picker. See Dependencies.

The console shows the "[Acun UI PRO] JavaScript is not loaded" error

A component on the page needs the PRO JavaScript, but the PRO JS isn't loaded. Add import '@acunsoft/acun-ui-pro'; to your Vite entry (resources/js/acun-ui.js in the theme) and rebuild. If you don't use Vite, add @acunUiScripts to the layout. The details are below, in the Advanced section.

Does it work with Livewire 3?

No. The package requires Livewire 4. It works with Laravel 12 and 13, Tailwind CSS 4, and PHP 8.2 or later. See Dependencies.

No. Acun UI doesn't install any authentication package (Sanctum, Fortify, Breeze, Jetstream…) and doesn't add routes of its own. It only provides the look of the sign-in, registration, password reset and two-factor authentication screens. You set up authentication yourself, with the method that suits your project; components such as the user menu likewise show only the values you pass (e.g. :name="auth()->user()->name"). See Layouts.

Will I lose my changes when I update the package?

Don't edit the files under vendor/; they're overwritten on update. Components you copied into your application and your @theme values are kept. But copied components don't receive the fixes in the new version; after updating, compare your copies with the version in the package.

Appearance

The theme flashes white for a moment when moving between pages

Build the page with the theme's layouts (layouts.admin.vertical, horizontal, blank). These layouts use the package's layout components, which apply the dark mode preference before the first paint. If you write your own layout, add <acun:layout.head> inside <head>. See Layouts.

I want to change how a component looks

Start with the props and the class attribute; the classes you pass are merged with the component's classes. For global values such as color and corners, use the @theme variables. If you need to change the markup, copy the component into your application's resources/views/components/ui/ folder with the same name. See Customization.

Components

The menu doesn't check permissions; unknown fields such as can are ignored. A section heading with no items below it and a group with no children left are hidden. If the item appears but doesn't go anywhere, the route in route isn't defined or the url isn't safe, so the link becomes #. See Menu.

Sorting doesn't work on a list page

If the column isn't in sortableFields(), the sort request is ignored. By default, only defaultSortField() is sortable. See List pages.

The unsaved-changes warning doesn't appear

Check that the form is wrapped in acun:form dirty-check and that the PRO JavaScript is loaded. If it isn't loaded, you'll see an error starting with [Acun UI PRO] in the browser console. The warning dialog is acun:form-guard-dialog; when PRO is installed, the package's layouts add it automatically. See Form modal.

License

Which license fits me?

Look at two questions: how many projects will you use the theme in, and will end users pay? The comparison table is on the License page.

Can I use the free packages in a commercial project?

Yes. @acunsoft/acun-ui-core and acunsoft/acun-ui-free are MIT-licensed; you only need to keep the copyright notice in the source files. PRO components come with a theme and are used under the theme's license. See License.

Advanced

The PRO JavaScript check

These components need the PRO JavaScript: acun:combobox, acun:file-upload, acun:form-modal, acun:form dirty-check, and a DataTable with in-browser actions, a fixed header or fixed columns. If one of them is on the page and the PRO JS isn't loaded, an error is written to the console. The error describes the fix and lists the components that won't work. There are two ways to fix it:

With Vite: Add import '@acunsoft/acun-ui-pro'; to your Vite entry and build (npm run build, or npm run dev during development). If the line is already there, the build is out of date; rebuild.
Without Vite: Add @acunUiScripts to your layout.

The check looks at the window.AcunUI.pro flag. Once the PRO JS loads, window.AcunUI.pro = { version, loaded: true, … }. Type AcunUI.pro in the console to see whether it's loaded and which version arrived. If you import only individual modules (e.g. ui/combobox.js), the flag isn't set; import the PRO entry (@acunsoft/acun-ui-pro) instead.

If the error occurs on the first page load, the dropdown and file upload fields stay dimmed and can't be clicked. The rest of the page works.

If the error says "The JavaScript file could not be loaded", @acunUiScripts is on the page but the file didn't arrive. Check the browser's network tab. If you published the file to the public/ folder, update it with php artisan vendor:publish --tag=acun-ui-pro-assets --force.

Importing with Vite and also using @acunUiScripts doesn't break anything: the file sees that the PRO JS is already loaded and does nothing. Still, it's an unnecessary request, so remove one of them. The "The JavaScript was loaded twice" warning, on the other hand, appears when two separate copies of the PRO entry run at the same time, e.g. two separate Vite entries that import the same entry. Remove one of the copies.

The old name window.AcunUiPro returns the same object but writes a warning to the console; use AcunUI.pro.