Configuration – Laravel Livewire Basic Components

In order to use and customize the Laravel Livewire Basic Components library, you need to configure it properly.

Step 1: Configure Vite

The Laravel Livewire Basic Components library uses Vite to compile the assets. You need to configure Vite to compile the assets properly.

Install SaSS

This library uses .scss files for styling. You need to install the scss-preprocessor to compile the styles:

1npm install -D sass-embedded

Now simply add the alias @basic-components to your vite.config.js file and import the variables file in your scss preprocessor options. This will automatically load the scss variables file in all your scss files.

 1 
 2import { defineConfig } from 'vite';
 3import laravel from 'laravel-vite-plugin';
 4import path from 'path';
 5 
 6export default defineConfig({
 7    ...
 8    plugins: [...],
 9    resolve: {
10        alias: {
11            '@basic-components': path.resolve(__dirname, 'vendor/maskowlabs/basic-components/resources/assets'),
12        },
13    },
14    css: {
15        preprocessorOptions: {
16            scss: {
17                additionalData: `@import "@basic-components/scss/utilities/variables";`,
18            },
19        },
20    },
21    ...
22});

Overwriting Variables

If you overwrite the package's default scss variables (located at /vendor/maskowlabs/basic-components/resources/assets/scss/utilities/_variables.scss), make sure to import your variables.scss file in the preprocessor options. (Line 16 in the code above)

Step 2: Import styles

You need to import the styles of this package in your main scss file. You can do this by either importing the @basic-components/scss/basic-components.scss file or by importing the individual files.

Option 1: Import all styles

Open your main scss file (e. G. app.scss) and import the basic-components.scss file at the top. This file contains all the styles of this package.

1 
2@import '@basic-components/scss/basic-components';
3 
4// Your custom styles

Option 2: Import individual files

If you don't use all the components of this package, you can import the individual files in your main scss file. This will reduce the size of the compiled css file and improve the performance.

Keep the order of the list, it is the order of basic-components.scss: layouts/monstera uses a variable from layouts/basis, and later files can override earlier ones. The variables are not part of the list, they come from the preprocessor options of Step 1.

 1 
 2// Utilities
 3@import '@basic-components/scss/utilities/fonts';
 4@import '@basic-components/scss/utilities/color-utils';
 5@import '@basic-components/scss/utilities/helper';
 6@import '@basic-components/scss/utilities/bootstrap';
 7@import '@basic-components/scss/utilities/grid';
 8 
 9// Layouts: only needed for the Monstera and Kentia layouts
10@import '@basic-components/scss/layouts/basis';
11@import '@basic-components/scss/layouts/monstera';
12@import '@basic-components/scss/layouts/kentia';
13 
14// Components
15@import '@basic-components/scss/components/heading';
16@import '@basic-components/scss/components/badges';
17@import '@basic-components/scss/components/button';
18@import '@basic-components/scss/components/button-group';
19@import '@basic-components/scss/components/dropdown';
20@import '@basic-components/scss/components/input-fields';
21@import '@basic-components/scss/components/input-field-groups';
22@import '@basic-components/scss/components/inputs-text';
23@import '@basic-components/scss/components/inputs-textarea';
24@import '@basic-components/scss/components/inputs-checks';
25@import '@basic-components/scss/components/inputs-checkboxes';
26@import '@basic-components/scss/components/inputs-radios';
27@import '@basic-components/scss/components/inputs-select';
28@import '@basic-components/scss/components/inputs-tag';
29@import '@basic-components/scss/components/inputs-file';
30@import '@basic-components/scss/components/inputs-selectable-card';
31@import '@basic-components/scss/components/code';
32@import '@basic-components/scss/components/alerts';
33@import '@basic-components/scss/components/nav';
34@import '@basic-components/scss/components/breadcrumb';
35@import '@basic-components/scss/components/page-header';
36@import '@basic-components/scss/components/card';
37@import '@basic-components/scss/components/tabs';
38@import '@basic-components/scss/components/tooltip';
39@import '@basic-components/scss/components/toasts';
40@import '@basic-components/scss/components/pagination';
41@import '@basic-components/scss/components/divider';
42@import '@basic-components/scss/components/modals';
43@import '@basic-components/scss/components/confirm-dialog';
44@import '@basic-components/scss/components/tables';
45@import '@basic-components/scss/components/list';
46@import '@basic-components/scss/components/statistics';
47@import '@basic-components/scss/components/placeloader';
48@import '@basic-components/scss/components/form-group';
49@import '@basic-components/scss/components/section';
50@import '@basic-components/scss/components/form-errors';
51@import '@basic-components/scss/components/speech-to-text';
52@import '@basic-components/scss/components/markdown-editor';
53@import '@basic-components/scss/components/image-editor';
54 
55// Your custom styles

Package updates

If you use option 2 and this package gets updated, you need to manually import the new files in your main scss file.

Step 3: Import scripts

This package contains some javascript files that are required for some components to work properly. You need to import the basic-components.js file in your main javascript file (e. G. app.js).

1 
2import '@basic-components/js/basic-components';
3 
4// Your custom scripts

Step 4: Publish the icons

With the default SVG icon set, <x-icon> reads the Heroicons from resources/assets/vendor/maskowlabs/basic-components/icons. Copy them there once:

1 
2php artisan vendor:publish --tag=basic-components:icons

Skip this step if you set icons.type to font or point icons.svg-path at your own icon set. The other publish tags are listed under Publishing further down.

How it should look like

When you've successfully configured the Laravel Livewire Basic Components library, your files should look like this:

resources/app.scss

1 
2@import '@basic-components/scss/basic-components';
3// Your custom styles

resources/app.js

1 
2import '@basic-components/js/basic-components';
3// Your custom scripts

resources/views/homepage.blade.php

 1 
 2<!DOCTYPE html>
 3<html>
 4    <head>
 5        @‎vite(['resources/app.js', 'resources/app.scss'])
 6    </head>
 7    <body>
 8        <!-- Your content -->
 9    </body>
10</html>

You're done!

You've successfully configured the Laravel Livewire Basic Components library. You can now use the components in your project.

Publishing

Apart from the SVG icons, the package works without publishing anything. Publish only what you want to change, because published files no longer receive package updates.

Tag	Copies	To
`basic-components:config`	The config file	`config/basic-components.php`
`basic-components:icons`	The Heroicons in the styles `solid`, `outline`, `mini` and `micro`	`resources/assets/vendor/maskowlabs/basic-components/icons`
`basic-components:views`	All component views	`resources/views/vendor/basic-components`
`basic-components:assets`	The SCSS and JavaScript sources and the translations (`en`, `de`)	`resources/assets/vendor/maskowlabs/basic-components/scss`, `resources/assets/vendor/maskowlabs/basic-components/js` and `resources/lang/vendor/basic-components`

SVG icons need the published icons

The default icons.svg-path points at the heroicons folder of the published icons. Without them, every <x-icon> throws an exception saying that the icon file does not exist.

Published files are copies

Published views take precedence over the package's views, also after an update, so keep only the files you changed. The copied SCSS and JavaScript are not used automatically: the @basic-components alias from Step 1 still points at the vendor folder.

Translations are published to resources/lang

As soon as resources/lang exists, Laravel loads all translations from there instead of lang. If your app keeps its translations in lang, move the published folder to lang/vendor/basic-components and delete resources/lang.

 1# Config file
 2php artisan vendor:publish --tag=basic-components:config
 3 
 4# Heroicons, required for SVG icons
 5php artisan vendor:publish --tag=basic-components:icons
 6 
 7# Component views
 8php artisan vendor:publish --tag=basic-components:views
 9 
10# SCSS, JavaScript and translations
11php artisan vendor:publish --tag=basic-components:assets

Configuration Reference

Every key of config/basic-components.php with its package default. Icon values are <x-icon> names. With icons.type set to font, use the classes of your icon font instead, e.g. fa-solid fa-spinner.

Key and default	Description
`icons.type` `svg`	`svg` renders the files from `icons.svg-path` inline. `font` renders an empty `<i>` with the icon name as class, for icon fonts like Font Awesome.
`icons.svg-path` `resource_path('assets/vendor/maskowlabs/basic-components/icons/heroicons')`	Folder with one subfolder per style, e.g. `solid/home.svg`. The default is the published Heroicons folder. SVGs are cached forever, so run `php artisan cache:clear` after changing the path or the files.
`icons.svg-default-style` `solid`	Style for names without a `--style` suffix: `home` renders `home--solid`.
`button-default-type` `white`	`type` of `<x-button>` when none is set.
`button-default-size` `md`	`size` of `<x-button>`: `xs`, `sm`, `md`, `lg` or `xl`.
`input-default-size` `md`	`size` of `<x-input>`, `<x-select>`, `<x-input.file>`, `<x-field>` and `<x-image-editor>`: `sm`, `md`, `lg` or `xl`.
`tag-input-default-size` `md`	`size` of `<x-tag-input>`: `sm`, `md`, `lg` or `xl`.
`textarea-default-size` `md`	`size` of `<x-textarea>`: `sm`, `md`, `lg` or `xl`.
`textarea-default-rows` `3`	`rows` of `<x-textarea>` when none is set.
`checkbox-default-size` `md`	`size` of `<x-checkbox>` and `<x-radio>`: `sm`, `md` or `lg`.
`select-default-arrow` `up-down`	`arrow` of `<x-select>`: `up-down` (double chevron), `up` (single chevron that flips while the select is open) or `none`.
`alert-default-type` `warning`	`type` of `<x-alert>`: `primary`, `success`, `warning`, `danger` or `info`.
`alert-default-size` `md`	`size` of `<x-alert>`: `xs`, `sm` or `md`.
`loading-spinner-icon` `arrow-path--mini`	Spinner in the search field of `<x-table.header>`.
`help-icon` `question-mark-circle--mini`	Icon next to a filter label in `<x-table.filter>` that has a `help` text, shown as a tooltip.
`form-errors-icon` `exclamation-triangle--mini`	Default `icon` of `<x-form-errors>`.
`table.sort-icon-asc` `chevron-up--mini`	Ascending sort indicator in a sortable table header.
`table.sort-icon-desc` `chevron-down--mini`	Descending sort indicator in a sortable table header.
`table.search-icon` `magnifying-glass--mini`	Icon in the search field of `<x-table.header>`.
`table.filter-icon` `funnel--mini`	Icon of the filter button of `<x-table.filter>`.
`verifymail_api_key` `null`	verifymail.io key, read from `VERIFYMAIL_API_KEY`. Turns on the disposable address check of `ValidEmailRule`, see Rules.
`markdown.*` Array	Default buttons, markers and icons of the formatting toolbar of `<x-textarea markdown>`, see Markdown Editor.
`speech-to-text.*` Array, `enabled` is `false`	Master switch, OpenAI key, storage, language, limits and routes of the microphone button, see Speech-to-Text.
`confirm-dialog.*` Array	Whether `wire:confirm` opens the styled dialog, plus its default type, types and texts, see Confirm Dialog.

Overriding Nested Arrays

The package merges its config with yours through Laravel's mergeConfigFrom(), which only looks at the top level. Every top-level key you leave out keeps its package default, but a nested array you define, such as icons, table, markdown, speech-to-text or confirm-dialog, replaces the package's array as a whole.

Always copy the complete array

Setting only icons.svg-default-style also removes icons.type and icons.svg-path, and <x-icon> stops rendering SVGs. Keys that a package update adds to a nested array do not reach your copy either, so compare it after updating.

 1// config/basic-components.php
 2 
 3return [
 4    // Top-level keys you leave out keep the package default.
 5    'button-default-type' => 'primary',
 6 
 7    // A nested array replaces the package's array as a whole:
 8    // repeat every key, not only the one you change.
 9    'icons' => [
10        'type' => 'svg',
11        'svg-path' => resource_path('assets/vendor/maskowlabs/basic-components/icons/heroicons'),
12        'svg-default-style' => 'outline',
13    ],
14];

Laravel Boost Ready

This package is Laravel Boost Ready, which means it seamlessly integrates with AI-powered development tools like Laravel Boost to enhance your development experience.

What is Laravel Boost Ready?

Laravel Boost Ready packages automatically provide their functionality to AI agents, making them "smarter" and more capable when working with your codebase. Instead of having to manually explain component APIs and features, the AI automatically knows how to use this package effectively.

Getting Started with Laravel Boost

To enable AI-enhanced development with this package, first install Laravel Boost as a development dependency:

1composer require laravel/boost --dev

Then run the interactive installer:

1php artisan boost:install

Laravel Boost will automatically detect this package and make all its components, features, and best practices available to your AI assistant.

Benefits of Laravel Boost Integration

When Laravel Boost is installed, your AI assistant gains enhanced capabilities including intelligent code generation with correct component syntax, instant access to all documentation and examples, smart troubleshooting with package-specific knowledge, and significantly faster development without manual documentation reference.

Example AI Capabilities

Once Laravel Boost is installed, your AI assistant can help with:

Creating complete forms with validation using the correct input components
Building responsive data tables with sorting, filtering, and pagination
Implementing modal dialogs with proper structure and behavior
Designing dashboard layouts using statistics and card components
Setting up navigation structures with breadcrumbs and menus
Applying consistent styling and following package conventions

Enhanced AI Development

Pro Tip: After installing Laravel Boost, you can ask your AI assistant questions like "Create a user management table with filters" or "Build a dashboard with statistics" and it will automatically use the appropriate components from this package.

Package Recognition

Laravel Boost automatically recognizes this package through its configuration and provides comprehensive information about:

All available components (buttons, forms, tables, modals, etc.)
Component attributes and configuration options
Styling classes and design system guidelines
Integration patterns with Livewire and Laravel
Validation rules and helper functions
Best practices and common usage patterns

Ready to Boost Your Development!

With Laravel Boost installed, you're ready to experience AI-enhanced development with this package. Your AI assistant now has deep knowledge of all components and can help you build better applications faster.