The Symfony UX Initiative & Packages ¶

Installing Symfony UX ¶

Before you install any specific UX library, make sure you've installed Webpack Encore.

If you already have it installed, make sure you have an assets/bootstrap.js file (this initializes Stimulus & the UX packages), an assets/controllers.json file (this controls the 3rd party UX packages that you've installed) and .enableStimulusBridge('./assets/controllers.json') in your webpack.config.js file. If these are missing, try upgrading the symfony/webpack-encore-bundle Flex recipe. See Upgrading Flex Recipes.

All Symfony UX Packages ¶

• ux-autocomplete: Transform EntityType, ChoiceType or any <select> element into an Ajax-powered autocomplete field (see demo)
  ux-autocomplete: EntityType、ChoiceType、または任意の要素を Ajax を利用したオートコンプリート フィールドに変換します (デモを参照)
• ux-chartjs: Easy charts with Chart.js (see demo)
  ux-chartjs: Chart.js を使用した簡単なチャート (デモを参照)
• ux-cropperjs: Form Type and tools for cropping images (see demo)
  ux-cropperjs: 画像をトリミングするためのフォーム タイプとツール (デモを参照)
• ux-dropzone: Form Type for stylized "drop zone" for file uploads (see demo)
  ux-dropzone: ファイル アップロード用の定型化された「ドロップ ゾーン」のフォーム タイプ (デモを参照)
• ux-lazy-image: Optimize Image Loading with BlurHash (see demo)
  ux-lazy-image: BlurHash による画像読み込みの最適化 (デモを参照)
• ux-live-component: Build Dynamic Interfaces with Zero JavaScript (see demo)
  ux-live-component: ゼロ JavaScript で動的インターフェイスを構築する (デモを参照)
• ux-notify: Send server-sent native notification with Mercure (see demo)
  ux-notify: サーバーから送信されたネイティブ通知を Mercure で送信します (デモを参照)
• ux-react: Render React component from Twig (see demo)
  ux-react: Twig から React コンポーネントをレンダリングします (デモを参照)
• ux-swup: Integration with Swup (see demo)
  ux-swup: Swup との統合 (デモを参照)
• ux-turbo: Integration with Turbo Drive for a single-page-app experience (see demo)
  ux-turbo: 単一ページのアプリ エクスペリエンスのための Turbo Drive との統合 (デモを参照)
• ux-twig-component: Build Twig Components Backed by a PHP Class (see demo)
  ux-twig-component: PHP クラスに基づく Twig コンポーネントのビルド (デモを参照)
• ux-typed: Integration with Typed (see demo)
  ux-typed: Typed との統合 (デモを参照)
• ux-vue: Render Vue component from Twig (see demo)
  ux-vue: Twig からの Vue コンポーネントのレンダリング (デモを参照)

Stimulus Tools around the World ¶

Because Stimulus is used by developers outside of Symfony, many tools exist beyond the UX packages:

• stimulus-use: Add composable behaviors to your Stimulus controllers, like debouncing, detecting outside clicks and many other things.
  timulus-use: Stimulus コントローラーに構成可能な動作を追加します。これには、バウンス、外部クリックの検出、その他多くの機能が含まれます。
• stimulus-components A large number of pre-made Stimulus controllers, like for Copying to clipboard, Sortable, Popover (similar to tooltips) and much more.
  刺激コンポーネント クリップボードへのコピー、ソート可能、ポップオーバー (ツールチップに類似) など、多数の事前に作成された刺激コントローラー。

How does Symfony UX Work? ¶

When you install a UX PHP package, Symfony Flex will automatically update your package.json file to point to a "virtual package" that lives inside the PHP package. For example:

1
2
3
4
5
6

{
    "devDependencies": {
        "...": "",
        "@symfony/ux-chartjs": "file:vendor/symfony/ux-chartjs/Resources/assets"
    }
}

This gives you a real Node package (e.g. @symfony/ux-chartjs) that, instead of being downloaded, points directly to files that already live in your vendor/ directory.

The Flex recipe will usually also update your assets/controllers.json file to add a new Stimulus controller to your app. For example:

1
2
3
4
5
6
7
8
9
10
11

{
    "controllers": {
        "@symfony/ux-chartjs": {
            "chart": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    },
    "entrypoints": []
}

Finally, your assets/bootstrap.js file - working with the @symfony/stimulus-bridge - package will automatically register:

• All files in assets/controllers/ as Stimulus controllers;
  assets/controllers/ 内のすべてのファイルを Stimulus コントローラーとして。
• And all controllers described in assets/controllers.json as Stimulus controllers.
  また、assets/controllers.json に Stimulus コントローラーとして記述されているすべてのコントローラー。

The end result: you install a package, and you instantly have a Stimulus controller available! In this example, it's called @symfony/ux-chartjs/chart. Well, technically, it will be called symfony--ux-chartjs--chart. However, you can pass the original name into the {{ stimulus_controller() }} function from WebpackEncoreBundle, and it will normalize it:

1
2
3
4

<div {{ stimulus_controller('@symfony/ux-chartjs/chart') }}>

<!-- will render as: -->
<div data-controller="symfony--ux-chartjs--chart">

Lazy Controllers ¶

By default, all of your controllers (i.e. files in assets/controllers/ + controllers in assets/controllers.json) will be downloaded and loaded on every page.

Sometimes you may have a controller that is only used on some pages, or maybe only in your admin area. In that case, you can make the controller "lazy". When a controller is lazy, it is not downloaded on initial page load. Instead, as soon as an element appears on the page matching the controller (e.g. <div data-controller="hello">), the controller - and anything else it imports - will be lazyily-loaded via Ajax.

To make one of your custom controllers lazy, add a special comment on top:

1
2
3
4
5
6

import { Controller } from '@hotwired/stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...
}

To make a third-party controller lazy, in assets/controllers.json, set fetch to lazy.

More Advanced Setup ¶

To learn about more advanced options, read about @symfony/stimulus-bridge, the Node package that is responsible for a lot of the magic.