Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Bundles
  4. Symfony UX Vue.js
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installation
  • Usage
    • Events
    • Web History mode with Vue Router
  • Backward Compatibility promise

Symfony UX Vue.js

Edit this page

Symfony UX Vue.js

Symfony UX Vue.js is a Symfony bundle integrating Vue.js in Symfony applications. It is part of the Symfony UX initiative.

Vue.js is a JavaScript framework for building user interfaces. Symfony UX Vue.js provides tools to render Vue components from Twig, handling rendering and data transfers.

Symfony UX Vue.js supports Vue.js v3 only.

Installation

Before you start, make sure you have Symfony UX configured in your app. Then install the bundle using Composer and Symfony Flex:

1
$ composer require symfony/ux-vue

Next, in webpack.config.js, enable Vue.js support:

1
2
3
4
5
6
7
// webpack.config.js
// ...

Encore
    // ...
    .enableVueLoader()
;

Install a package to help Vue:

With NPM:

1
2
$ npm install -D vue-loader --force
$ npm run watch

With Yarn:

1
2
$ yarn add vue-loader --dev --force
$ yarn watch

Finally, to load your Vue components, add the following lines to assets/app.js:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// assets/app.js
import { registerVueControllerComponents } from '@symfony/ux-vue';

// Registers Vue.js controller components to allow loading them from Twig
//
// Vue.js controller components are components that are meant to be rendered
// from Twig. These component can then rely on other components that won't be
// called directly from Twig.
//
// By putting only controller components in `vue/controllers`, you ensure that
// internal components won't be automatically included in your JS built file if
// they are not necessary.
registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/));

// If you prefer to lazy-load your Vue.js controller components, in order to keep the JavaScript bundle the smallest as possible,
// and improve performance, you can use the following line instead:
//registerVueControllerComponents(require.context('./vue/controllers', true, /\.vue$/, 'lazy'));

That's it! Create an `assets/vue/controllers/` directory and start creating your Vue components.

Usage

UX Vue.js works by using a system of Vue.js controller components: Vue.js components that are registered using registerVueControllerComponents and that are meant to be rendered from Twig.

When using the registerVueControllerComponents configuration shown previously, all Vue.js components located in the directory assets/vue/controllers are registered as Vue.js controller components.

To make sure those components can be loaded by Webpack Encore, you need to configure it by following the instructions in the related section of the documentation.

You can then render any Vue.js controller component in Twig using the vue_component. For example:

1
2
3
4
5
6
7
8
9
10
// assets/vue/controllers/MyComponent.vue
<template>
    <div>Hello {{ name }}!</div>
</template>

<script setup>
    defineProps({
        name: String
    });
</script>
1
2
{# templates/home.html.twig #}
<div {{ vue_component('MyComponent', { 'name': app.user.fullName }) }}></div>

Events

The event vue:before-mount is called before a component is mounted on the page. This is the event to listen if you need to modifiy the Vue application (e.g.: add plugins, add global directives, states ...):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// assets/app.js
document.addEventListener('vue:before-mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that will be injected to the component
        app, // The Vue application instance
    } = event.detail;

    // Example with Vue Router
    const router = VueRouter.createRouter({
        history: VueRouter.createWebHashHistory(),
        routes: [
            /* ... */
        ],
    });

    app.use(router);
});

Note

When using Vue Router, you can use "hash" or "memory" history mode to prevent your Vue routes from being served through Symfony controllers. If you want to use web history mode, see Symfony UX Vue.js

The event vue:mount is called when a component has been mounted on the page:

1
2
3
4
5
6
7
document.addEventListener('vue:mount', (event) => {
    const {
        componentName, // The Vue component's name
        component, // The resolved Vue component
        props, // The props that are injected to the component
    } = event.detail;
});

The event vue:unmount is called when a component has been unmounted on the page:

1
2
3
4
5
6
document.addEventListener('vue:unmount', (event) => {
    const {
        componentName, // The Vue component's name
        props, // The props that were injected to the component
    } = event.detail;
});

Web History mode with Vue Router

To use "web" history mode with Vue Router, a catch-all route will be needed which should render the same template and Vue component:

This controller will catch any URL that starts with `/survey`. This prefix can then be used for all the Vue routes:

1
2
3
4
5
6
7
8
9
10
const router = VueRouter.createRouter({
    history: VueRouter.createWebHistory(),
    routes: [
        { path: '/survey/list', component: ListSurveys },
        { path: '/survey/create', component: CreateSurvey },
        { path: '/survey/edit/:surveyId', component: EditSurvey },
    ],
});

app.use(router);

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:

    Symfony UX is backed by

    Take the exam at home

    Take the exam at home

    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of avorobiev, a Symfony contributor

    Thanks avorobiev for being a Symfony contributor

    2 commits • 42 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Meilisearch