Upgrade guide
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
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:
php artisan vendor:publish --tag=tallcraftui-css --force
Your resources/css/app.css should contain:
@import 'tailwindcss';@import './tallcraftui.css';@plugin '@tailwindcss/forms';@custom-variant dark (&:where(.dark, .dark *));
- The
@custom-variant darkline 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 inapp.cssis no longer needed, but it's harmless to keep. - Defining
--color-primaryand--color-secondaryin your own@themeis now optional. Your values always override the defaults (#6d28d9and#a21caf). - If you still have a
tailwind.config.jsentry 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:
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:
<x-select wire:model.live="country" :options="$countries" />
Livewire 4 wire:model changes
These come from Livewire itself and apply to TallCraftUI inputs too:
.blurand.changenow also delay syncing the value in the browser. Usewire:model.live.blurfor the Livewire 3 behavior.wire:modelignoresinputevents bubbling up from child elements. Use.deepto 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.mimesare accepted (jpg, jpeg, png, gif, webp, avif by default), up totallcraftui.upload.max_size(2 MB by default). SVG files are rejected. - Only disks listed in
tallcraftui.upload.disksare accepted (publicby default). - The
folderprop must be a plain path such asmarkdownorposts/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:
protected string $markdownImageFolder = 'posts/images';
WithTcTable
-
The trait's
updated()hook is nowupdatedWithTcTable(), so it runs alongside your component's ownupdated(). If you aliased the trait method to avoid a conflict (for exampleuse 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:
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:
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'andAlpine.start()fromresources/js/app.js. - Components have no styles
- Make sure
app.cssimports./tallcraftui.css, republish it with--force, and rebuild your assets withnpm run devornpm run build. - The dark mode toggle does nothing
- Add
@custom-variant dark (&:where(.dark, .dark *));toapp.css. - Primary-colored components look violet
- That's the new default. Define
--color-primaryand--color-secondaryin 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.
npx @tailwindcss/upgrade
Install TallCraftUI 2.0
composer require developermithu/tallcraftui:^2.0php artisan install:tallcraftui
Update the configuration file
Remove the old config/tallcraftui.php, publish the new one and review it for new options:
rm config/tallcraftui.phpphp artisan vendor:publish --tag=tallcraftui-configphp 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:
<!-- 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" ... />