Get started

Differences between GOV.UK Vue and GOV.UK Frontend

GOV.UK Frontend is the framework behind the GOV.UK Design System.

GOV.UK Vue aims to follow the behaviour of GOV.UK Frontend - for example, in almost all cases:

• GOV.UK Vue props have the same names and defaults as GOV.UK Frontend Nunjucks macros options
• The HTML output of the Vue components is the same as the Nunjucks macros (except data attributes)

GOV.UK Vue also doesn't provide any components that aren't in GOV.UK Frontend.

If you've used GOV.UK Frontend before you should find it very easy to start using GOV.UK Vue. There are some general differences which you should be aware of, listed below. There are also a few differences in individual components; these are highlighted on the documentation pages for those components.

html Nunjucks options replaced with slots

Many Nunjucks templates let you specify the content of a component either with a simple text string or with HTML. They use a macro option for this; for example, the back link component has text and html options to set the content of the link.

In GOV.UK Vue, these HTML options are replaced with slots. Generally the main content of a component can be set with a text prop or by using the default slot.

<gv-back-link href="https://example.com">Back, set via a slot</gv-back-link>

<gv-back-link href="https://example.com" text="Back, set via a prop" />

Many components have multiple slots. You can mix props and slots, but slots will always override props if both have been set for the same part of the component.

Dynamic slot content can have unintended effects, because slots aren't reactive. If you want to pass dynamic or conditional content to a component, use props rather than slots.

Enter the name of the event

<gv-input 
  label="What is the name of the event?" 
  error-message="This prop value will not be shown"
>
  <template #error-message>
    Enter the name of the event
  </template>
</gv-input>

value replaced with v-model

Nunjucks templates for form inputs, for example select and textarea, let you specify the initial value of the input with the value option.

GOV.UK Vue uses standard v-model binding with form inputs, so these components don't have a value prop.

items replaced with nested components

Some Nunjucks templates, for example tabs and tables, let you pass an array of items to show in the component.

In GOV.UK Vue you should use the appropriate child component, usually in the default slot. For example, the GvTabs container takes a list of GvTabs in the default slot:

<gv-tabs title="Cases opened">
  <gv-tab label="Past day">
    <h2 class="govuk-heading-l">Past day</h2>
    <gv-inset-text>No cases opened in the past day</gv-inset-text>
  </gv-tab>
  <gv-tab label="Past week">
    <h2 class="govuk-heading-l">Past week</h2>
    <gv-inset-text>No cases opened in the past week</gv-inset-text>
  </gv-tab>
</gv-tabs>

If you want to display data from an array, you can use v-for to loop over it.

Dates and amounts

Date	Amount
First 6 weeks	£109.80 per week
Next 33 weeks	£109.80 per week
Total estimated pay	£4,282.20

<script setup lang="ts">
  const data = [
    { date: 'First 6 weeks', amount: '£109.80 per week'},
    { date: 'Next 33 weeks', amount: '£109.80 per week'},
    { date: 'Total estimated pay', amount: '£4,282.20'},
  ]
</script>

<template>
  <gv-table caption="Dates and amounts">
    <gv-table-head>
      <gv-table-row>
        <gv-table-header>Date</gv-table-header>
        <gv-table-header>Amount</gv-table-header>
      </gv-table-row>
    </gv-table-head>
    <gv-table-body>
      <gv-table-row v-for="row in data" :key="row.date">
        <gv-table-header scope="row">{{ row.date }}</gv-table-header>
        <gv-table-cell>{{ row.amount }}</gv-table-cell>
      </gv-table-row>
    </gv-table-body>
  </gv-table>
</template>

GOV.UK Frontend JavaScript is not used

GOV.UK Frontend's JavaScript is based on vanilla JavaScript and so often contains code which directly modifies the DOM.

In GOV.UK Vue, DOM state is handled by Vue wherever possible. All of the functionality provided by GOV.UK Frontend's JavaScript has been preserved, but mostly rewritten.

There are some exceptions, usually when a component has to modify the DOM outside of itself. For example, the skip link code uses code taken from skip-link.mjs in GOV.UK Frontend to focus on the skip link target.

The Nunjucks macros use data- attributes to pass information to the JavaScript. These attributes aren't necessary in GOV.UK Vue, so they're not added to any components. This means that you can safely use GOV.UK Vue together with GOV.UK Frontend's JavaScript if you want to. Because the GOV.UK Frontend JavaScript only interacts with components that have the required data- attributes, it won't interfere with GOV.UK Vue components.