Symfony UX Toolkit

Installation

1

$ composer require --dev symfony/ux-toolkit

The package only registers console commands, so it is needed while you install recipes, not to render them.

Kits and Recipes

A recipe is a pack of files and dependencies: Twig components, Stimulus controllers, and the Composer or npm packages they need to run. button and dialog are recipes.

A kit is a collection of recipes sharing one design system, like Shadcn UI or Bootstrap. The kits shipped with the Toolkit are browsable in the ux-toolkit repository.

Installing a Recipe

Run the ux:install command with the name of the recipe you want:

1

$ php bin/console ux:install dialog

The command asks which kit to take the recipe from, copies its files into your application and lists the dependencies the recipe needs.

The files land where they are meant to be used: Twig templates under templates/, Stimulus controllers under assets/, and if a file already exists, it is not replaced without asking you first, so a recipe you have already customized cannot be overwritten by accident. When Git is installed, a diff between your file and the recipe file is shown before the question, so you can see exactly what would change. When the file is identical to the recipe, it is left as is and no question is asked.

A recipe can depend on other recipes and on packages, and the two are handled differently:

• Other recipes it depends on are copied in the same run: installing dialog from the Shadcn kit also writes button;
• Composer and npm packages are not installed for you: the command prints the composer require, npm install or php bin/console importmap:require command to run yourself.

Choosing a Kit

Four kits are shipped with the Toolkit:

• shadcn, Shadcn UI
• flowbite-4, Flowbite v4
• bootstrap, Bootstrap 5.3
• common, design-system agnostic recipes for common Symfony needs, such as logout links

Pass --kit to skip the question:

1

$ php bin/console ux:install button --kit=shadcn

Browse the recipes of each kit, with a live preview, on ux.symfony.com.

Choosing Where Recipes Are Installed

By default, ux:install writes Twig components to templates/components/ and Stimulus controllers to assets/controllers/. The components and controllers options under ux_toolkit change that. Each one takes a dir and an optional subdirectory. Paths are relative to the project directory.

1
2
3
4
5
6
7
8
9

# config/packages/stimulus.yaml
stimulus:
    controller_paths:
        - '%kernel.project_dir%/assets/js/controllers'

# config/packages/ux_toolkit.yaml
ux_toolkit:
    controllers:
        dir: 'assets/js/controllers'

1
2
3
4
5
6

# config/packages/ux_toolkit.yaml
ux_toolkit:
    components:
        subdirectory: 'ui'
    controllers:
        subdirectory: 'ui'

1
2
3
4
5
6

{
    "copy-files": {
        "templates/components/": "%COMPONENTS_DIR%/",
        "assets/controllers/": "%CONTROLLERS_DIR%/"
    }
}

The Recipe Is Yours, For Worse and For Better

Installing a recipe copies its files into your application, and the Toolkit then steps out of the way. The code is part of your project, like any template you wrote yourself.

The consequence is that there is no upgrade path. Fixes, new options and new features added to a kit never reach a recipe you have already installed, and installing the same recipe today and in six months gives two different versions of it.

Your version control system is what closes that gap. Commit right after installing a recipe, and when you want the newer version, run ux:install again and read the diff: it shows exactly what changed in the kit and what you have changed yourself, and you keep what you want from each side. The command asks before overwriting, so nothing is lost if you would rather not.

In exchange, the recipe really is yours. Adapting one is editing a template: no override mechanism to learn, no configuration to bend, and no limit to the options its author thought of. That is the idea the Toolkit takes from Shadcn UI, and the reason the files are copied rather than shipped in vendor/.