Nuxt Headless UI

Headless UI integration for Nuxt. Completely unstyled, fully accessible UI components, designed to integrate beautifully with Tailwind CSS.

Headless UI documentation for Vue: https://headlessui.com/vue/menu

Features

Automatic dynamic imports (no global components)
Fully type safe
Configurable component prefix (defaults to Headless)

Quick Setup

Add nuxt-headlessui dependency to your project

# Using pnpm
pnpm add -D nuxt-headlessui

# Using yarn
yarn add --dev nuxt-headlessui

# Using npm
npm install --save-dev nuxt-headlessui

Add nuxt-headlessui to the modules section of nuxt.config.ts

{
    modules: [
        'nuxt-headlessui'
    ],

    // Optionally change the default prefix.
    headlessui: {
        prefix: 'Headless'
    }
}

That's it! You can now use Headless UI in your Nuxt app ✨

After completing setup, simply use the headless components in your components and pages and style them with your favourite CSS framework. You don't have to import the components. Here is an example of a Listbox (Select), which uses heroicons and Tailwind CSS:

<template>
  <div class="container mx-auto">
    <div class="w-72">
      <HeadlessListbox v-model="selectedPerson">
        <div class="relative mt-1">
          <HeadlessListboxButton
            class="relative w-full cursor-default rounded-lg bg-white py-2 pl-3 pr-10 text-left shadow-md focus:outline-none focus-visible:border-indigo-500 focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-opacity-75 focus-visible:ring-offset-2 focus-visible:ring-offset-orange-300 sm:text-sm"
          >
            <span class="block truncate">{{ selectedPerson.name }}</span>
            <span
              class="pointer-events-none absolute inset-y-0 right-0 flex items-center pr-2"
            >
              <ChevronUpDownIcon
                class="h-5 w-5 text-gray-400"
                aria-hidden="true"
              />
            </span>
          </HeadlessListboxButton>

          <transition
            leave-active-class="transition duration-100 ease-in"
            leave-from-class="opacity-100"
            leave-to-class="opacity-0"
          >
            <HeadlessListboxOptions
              class="absolute mt-1 max-h-60 w-full overflow-auto rounded-md bg-white py-1 text-base shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none sm:text-sm"
            >
              <HeadlessListboxOption
                v-for="person in people"
                v-slot="{ active, selected }"
                :key="person.name"
                :value="person"
                as="template"
              >
                <li
                  :class="[
                    active ? 'bg-amber-100 text-amber-900' : 'text-gray-900',
                    'relative cursor-default select-none py-2 pl-10 pr-4',
                  ]"
                >
                  <span
                    :class="[
                      selected ? 'font-medium' : 'font-normal',
                      'block truncate',
                    ]"
                  >{{ person.name }}</span>
                  <span
                    v-if="selected"
                    class="absolute inset-y-0 left-0 flex items-center pl-3 text-amber-600"
                  >
                    <CheckIcon class="h-5 w-5" aria-hidden="true" />
                  </span>
                </li>
              </HeadlessListboxOption>
            </HeadlessListboxOptions>
          </transition>
        </div>
      </HeadlessListbox>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { CheckIcon, ChevronUpDownIcon } from '@heroicons/vue/20/solid'

const people = [
  { name: 'Wade Cooper' },
  { name: 'Arlene Mccoy' },
  { name: 'Devon Webb' },
  { name: 'Tom Cook' },
  { name: 'Tanya Fox' },
  { name: 'Hellen Schmidt' }
]
const selectedPerson = ref(people[0])
</script>

If you are using Tailwind CSS, you can use the @headlessui/tailwindcss plugin to get modifiers like ui-open:* and ui-active:*.

Note about client-only components

Some headless components, such as Portal, Popover, or Dialog are client-only components. They will lead to errors when rendered on the server. You need to wrap them with ClientOnly. See https://github.com/tailwindlabs/headlessui/issues/1496.

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

headlessui

Nuxt Headless UI

Features

Quick Setup

Usage

Note about client-only components

Development