Skip to content
TallCraftUI

Upgrade guide

Upgrading from 2.x to 3.0 takes about 30 minutes for most apps. 3.0 keeps every component tag, prop, variant attribute and config key from 2.x. The breaking changes are the platform requirements, a few wire:model behaviors and the hardened Markdown upload endpoint.

Requirements

2.x 3.0
PHP 8.1+ 8.2+
Laravel 10, 11, 12 12, 13
Livewire 3 4
Tailwind CSS 4 4.1+
Alpine.js bundled with Livewire bundled with Livewire

2.x stays available for Livewire 3 apps and receives bug fixes only.

1 Upgrade to Livewire 4 first

Follow the official Livewire 4 upgrade guide and make sure your app works before upgrading TallCraftUI.

2 Update the package

Terminal
composer require developermithu/tallcraftui:^3.0

While 3.0 is in beta, use developermithu/tallcraftui:^3.0@beta.

3 Update your CSS

Republish the stylesheet. It now registers the component source path itself and ships default primary and secondary colors:

Terminal
php artisan vendor:publish --tag=tallcraftui-css --force

Your resources/css/app.css should contain:

resources/css/app.css
@import 'tailwindcss';
@import './tallcraftui.css';
@plugin '@tailwindcss/forms';
@custom-variant dark (&:where(.dark, .dark *));
  • The @custom-variant dark line enables class-based dark mode, which <x-theme-toggle /> needs. Leave it out if dark mode should follow the operating system only.
  • The @source '../../vendor/developermithu/tallcraftui/src/**/*.php'; line in app.css is no longer needed, but it's harmless to keep.
  • Defining --color-primary and --color-secondary in your own @theme is now optional. Your values always override the defaults (#6d28d9 and #a21caf).
  • If you still have a tailwind.config.js entry for TallCraftUI, you can remove it. The installer no longer edits that file.

Alternatively, re-run the installer. It only adds lines that are missing:

Terminal
php artisan install:tallcraftui

4 Review behavior changes

Select and Color Picker follow wire:model modifiers

In 2.x, <x-select> and <x-color-picker> sent every change to the server immediately, whatever modifier you used. They now behave like any other wire:model input: the value syncs on the next request. Add .live if you need immediate updates:

Blade
<x-select wire:model.live="country" :options="$countries" />

Livewire 4 wire:model changes

These come from Livewire itself and apply to TallCraftUI inputs too:

  • .blur and .change now also delay syncing the value in the browser. Use wire:model.live.blur for the Livewire 3 behavior.
  • wire:model ignores input events bubbling up from child elements. Use .deep to restore the Livewire 3 behavior on your own wrappers.

Markdown image uploads

The upload endpoint used by <x-markdown> is stricter:

  • Only the formats in tallcraftui.upload.mimes are accepted (jpg, jpeg, png, gif, webp, avif by default), up to tallcraftui.upload.max_size (2 MB by default). SVG files are rejected.
  • Only disks listed in tallcraftui.upload.disks are accepted (public by default).
  • The folder prop must be a plain path such as markdown or posts/images.
  • The CSRF token is sent as a header instead of a query string parameter.

If you published the config, you don't need to change it: new keys are filled in automatically. To customize them, add the upload section to config/tallcraftui.php. Set TALLCRAFTUI_UPLOAD_ENABLED=false to remove the upload route entirely.

Markdown image cleanup

HasMarkdownImages now only deletes images inside the model's markdown folder, so user-written markdown can't delete other files on the disk. If your <x-markdown> uses a folder other than markdown, set it on the model:

PHP
protected string $markdownImageFolder = 'posts/images';

WithTcTable

  • The trait's updated() hook is now updatedWithTcTable(), so it runs alongside your component's own updated(). If you aliased the trait method to avoid a conflict (for example use WithTcTable { updated as tcUpdated; }), remove the alias.
  • Define tcSortableColumns() to whitelist the columns users can sort by. See deprecations.

Clickable table rows

<x-tr href="..."> no longer navigates when you click a button, link or form control inside the row. Add wire:navigate to the row to navigate with Livewire; Ctrl/Cmd-click opens the link in a new tab. javascript: URLs are ignored.

Toast helpers

The global functions getPositionStyle, getPositionClasses, getAnimationClasses, getProgressBarColor and getProgressBarStyle were removed from window. window.toast() and the tallcraftui-toast event are unchanged.

Class merging

TallCraftUI now depends on gehrisandro/tailwind-merge-php directly instead of gehrisandro/tailwind-merge-laravel, which blocked installs on Laravel 13 apps using Guzzle 8. The twMerge, twMergeFor and withoutTwMergeClasses attribute macros work as before, and a published config/tailwind-merge.php is still used.

If your own views use the @twMerge Blade directive or the global twMerge() helper, require the Laravel package yourself:

Terminal
composer require gehrisandro/tailwind-merge-laravel

5 Deprecations

Sorting a WithTcTable component without a whitelist triggers an E_USER_DEPRECATED notice, which Laravel writes to your deprecations log channel. The whitelist will be required in 4.0. Add it to each table component:

PHP
public function tcSortableColumns(): array
{
return ['name', 'email', 'created_at', 'author.name'];
}

Sort columns outside the list are ignored.

Troubleshooting

"Detected multiple instances of Alpine running" or components don't respond
Livewire 4 already includes Alpine and the plugins TallCraftUI uses. Remove import Alpine from 'alpinejs' and Alpine.start() from resources/js/app.js.
Components have no styles
Make sure app.css imports ./tallcraftui.css, republish it with --force, and rebuild your assets with npm run dev or npm run build.
The dark mode toggle does nothing
Add @custom-variant dark (&:where(.dark, .dark *)); to app.css.
Primary-colored components look violet
That's the new default. Define --color-primary and --color-secondary in your own @theme.

Upgrading from 1.x to 2.0

TallCraftUI 2.0 requires Tailwind CSS 4, Laravel 10 or later and Livewire 3. The 1.x documentation is still online.

Upgrade Tailwind CSS

If you're on an older Tailwind version, upgrade it first. See the official Tailwind CSS upgrade guide.

Terminal
npx @tailwindcss/upgrade

Install TallCraftUI 2.0

Terminal
composer require developermithu/tallcraftui:^2.0
php artisan install:tallcraftui

Update the configuration file

Remove the old config/tallcraftui.php, publish the new one and review it for new options:

Terminal
rm config/tallcraftui.php
php artisan vendor:publish --tag=tallcraftui-config
php artisan view:clear

Rename select to native-select

The 1.x <x-select> was renamed to <x-native-select>, to make room for a new <x-select> with search, multiple selection and custom styling. Update every old select:

Blade
<!-- Before (1.x) -->
<x-select wire:model="country" ... />
 
<!-- After (2.0) -->
<x-native-select wire:model="country" ... />
 
<!-- The new select (optional, different API) -->
<x-select wire:model="user_id" ... />