Skip to content
Headless primitivesPreferences

Preferences for Nuxt

Markdown
Loading…

Build the consent preferences dialog with your own markup, keeping the category switches, saving, focus handling and Escape to close.

What it does

Preferences.* gives you the preferences dialog in pieces: when it opens, the list of categories, each category's label and switch state, and the buttons that save. You supply the elements and the classes. Focus handling, Escape to close and the dialog roles come with Preferences.Root, so you do not rebuild them.

Use it only when CookiePreferences cannot produce the markup your design needs, most often when a category row must be your own component. For colours and spacing, restyle CookiePreferences instead.

Build a dialog

Write the dialog as a component, then render it in place of <CookiePreferences /> inside <CookieYesRoot>. Preferences.Root is the overlay: it renders nothing while the dialog is closed, so keep it as the outer element.

app/components/ConsentPreferences.vue
<script setup lang="ts">
import { Preferences } from "#imports";
</script>

<template>
  <Preferences.Root class="overlay">
    <div class="dialog">
      <Preferences.Title class="dialog-title" />
      <Preferences.Close class="dialog-close" />
      <Preferences.Intro class="dialog-text" />

      <Preferences.Categories v-slot="{ category }" class="category-list">
        <Preferences.Category
          v-slot="{ label, description, checked, disabled, toggle }"
          :category="category"
          class="category-row"
        >
          <label class="category">
            <input
              type="checkbox"
              :checked="checked"
              :disabled="disabled"
              @change="toggle(($event.target as HTMLInputElement).checked)"
            />
            <span>{{ label }}</span>
            <small>{{ description }}</small>
          </label>
        </Preferences.Category>
      </Preferences.Categories>

      <div class="dialog-actions">
        <Preferences.RejectAll class="btn" />
        <Preferences.AcceptAll class="btn" />
        <Preferences.Save class="btn btn-primary" />
      </div>
    </div>
  </Preferences.Root>
</template>

Preferences is imported from #imports, Nuxt's own import path: a template sees Preferences.Root and the other pieces only when Preferences is a binding of the component. Categories renders its slot once per category in your categories list, so custom categories appear without any change here. Category gives its slot the resolved text and state for one row; you decide how the row looks.

The slot of <CookieYesRoot> replaces everything it renders by default, so list the other components you still want:

app/app.vue
<template>
  <CookieYesRoot>
    <CookieBanner />
    <ConsentPreferences />
    <RecallButton />
  </CookieYesRoot>
  <NuxtPage />
</template>

The pieces

PieceRendersWhat it does
Preferences.Root<div>The overlay. Opens and closes the dialog, traps focus, closes on Escape. Keep it as the wrapper
Preferences.Title<h2>The dialog heading
Preferences.Intro<p>The dialog text
Preferences.Close<button>Closes without saving
Preferences.Categories<div role="list">Renders its slot once per category, with the slot prop category
Preferences.Category<div>One row. Takes the category prop and gives its slot category, label, description, checked, disabled and toggle(next)
Preferences.AcceptAll<button>Accepts every category and saves
Preferences.RejectAll<button>Rejects every optional category and saves
Preferences.Save<button>Saves the switches as they are
Preferences.Branding<a>The "Powered by" link

Every piece takes class, style and the other attributes of the element it renders, and renders the translated text for the active language; put your own content in its default slot to replace it. The part names for CSS are the same as on CookiePreferences.

Good to know

A switch changes nothing until Save. toggle updates the row; Save, AcceptAll or RejectAll records the choice. Always render at least one of them.

A required category arrives locked. Its checked is true, disabled is true, and toggle does nothing. Show it as text such as "Always active" rather than a switch that does not work.

toggle takes the new value, not the event. Write @change="toggle(($event.target as HTMLInputElement).checked)". A component whose change handler already gives you a boolean, such as a Switch, can take toggle directly.

Use your own button component

Add as-child to Close, AcceptAll, RejectAll or Save and pass one element:

<Preferences.Save as-child>
  <MyButton variant="primary">Save preferences</MyButton>
</Preferences.Save>

Common mistakes

Switches turn on but never off. @change="toggle" passes the event, which counts as true. Use @change="toggle(($event.target as HTMLInputElement).checked)".

Choices are lost when the dialog closes. There is no Save, AcceptAll or RejectAll in your dialog.

A custom category is missing. You listed category ids by hand instead of using Preferences.Categories.

The dialog never opens. Nothing opens it. Render Banner.OpenPreferences, RecallButton, or your own button calling useConsentActions().showPreferences().

Next steps

  • Banner: build the banner the same way
  • OptOut: the CCPA opt-out dialog
  • Translations: the dialog and category text in every language

On this page