@smurfox/proxy-ui

ProxyUI

A component library built for Nuxt 4, designed with a clean and consistent API. All components are prefixed with PU.

Features

• 🎨 Built with Tailwind CSS v4
• ✨ Smooth animations powered by motion-v
• 🔷 Icons via @nuxt/icon (Iconify)
• 🔤 Inter font loaded automatically
• 🌙 Dark mode ready
• 📦 TypeScript support out of the box

Requirements

• Nuxt ^4.0.0
• Tailwind CSS ^4.0.0

Installation

npm install @smurfox/proxy-ui

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@smurfox/proxy-ui"],
});

Add Tailwind to your CSS entry file and register the library as a source so Tailwind picks up the component classes:

@import "tailwindcss";
@source "../node_modules/@smurfox/proxy-ui/dist";

The @source path is relative to the CSS file. If your CSS lives deeper (e.g. app/assets/css/main.css), adjust the number of ../ segments so it resolves to your project root's node_modules. Without this directive, Tailwind v4 will not scan the library files and variants like flat/outline will render unstyled.

That's it. All PU components are auto-imported and ready to use.

Theming

ProxyUI is fully themable through CSS variables. There are two layers of tokens — brand colors (used for emphasis: buttons, chips, focus rings, error states) and surface tokens (used for the neutral backgrounds and borders shared by cards, inputs, dropdowns, tables, etc.). Because surface tokens need different values in light and dark mode, they are declared on :root and .dark rather than directly inside @theme.

Brand colors

Surface tokens

The three tokens are layered from back to front: background (the page) → card (raised surfaces) → default (subtle fills inside cards). Components reference them via Tailwind utilities (bg-background, bg-card, bg-default, border-default, …) so overriding a variable retheme the whole library at once.

Setting it up in your project

All tokens — brand colors and surface tokens — ship with sensible defaults in the package. You only need a single @import in your Tailwind entry CSS:

@import "tailwindcss";
@source "../node_modules/@smurfox/proxy-ui/dist";
@custom-variant dark (&:where(.dark, .dark *));

@import "@smurfox/proxy-ui/theme.css";

That brings the @theme registration (so utilities like bg-primary, bg-card, bg-default, border-default get generated) plus the light/dark default values for surface tokens. Components work out of the box.

Apply bg-background to your root layout so the page picks up the token:

<template>
  <div :class="{ dark: isDark }" class="min-h-screen">
    <div class="bg-background min-h-screen">
      <!-- your app -->
    </div>
  </div>
</template>

The @import "@smurfox/proxy-ui/theme.css" must live in the same file as @import "tailwindcss" so Tailwind processes the @theme block inside it. Loading it as a separate stylesheet (a <link>, a Vue <style>, etc.) sets the runtime values but does not register the design tokens, and the bg-primary / bg-card / bg-default / border-default utilities won't be generated.

Customizing the look

All defaults can be overridden after the @import. CSS cascade makes your declarations win — every component picks up the change automatically.

Brand colors are flat values, so override them inside @theme:

@import "@smurfox/proxy-ui/theme.css";

@theme {
  --color-primary: #6366f1;     /* indigo accent */
  --color-success: #16a34a;
  --color-warning: #ea580c;
  --color-danger: #dc2626;
}

Surface tokens switch between light and dark, so override them in :root / .dark:

@import "@smurfox/proxy-ui/theme.css";

:root {
  --color-background: #fafafa;  /* warmer page bg */
  --color-card: #ffffff;
  --color-default: #ececec;
}

.dark {
  --color-background: #050608;  /* deeper page bg */
  --color-card: #0d0f12;
  --color-default: #1c2027;
}

The @custom-variant dark line is what makes the dark: Tailwind variant respond to a .dark class on a parent element (instead of prefers-color-scheme). All ProxyUI components assume this setup.

Components

PUButton

A button component powered by motion-v for smooth press animations.

<PUButton label="Click me" />

Props

Examples

<!-- Variants -->
<PUButton variant="default" label="Default" />
<PUButton variant="secondary" label="Secondary" />
<PUButton variant="outline" label="Outline" />
<PUButton variant="ghost" label="Ghost" />
<PUButton variant="flat" label="Flat" />

<!-- Colors -->
<PUButton color="primary" label="Primary" />
<PUButton color="danger" label="Danger" />
<PUButton color="success" label="Success" />
<PUButton color="warning" label="Warning" />

<!-- Sizes -->
<PUButton size="sm" label="Small" />
<PUButton size="md" label="Medium" />
<PUButton size="lg" label="Large" />

<!-- Icons -->
<PUButton start-icon="lucide:plus" label="New item" />
<PUButton end-icon="lucide:arrow-right" label="Continue" />
<PUButton is-icon-only icon="lucide:settings" />

<!-- States -->
<PUButton disabled label="Disabled" />
<PUButton loading label="Saving..." />

<!-- Custom color (customClass replaces the color scheme entirely) -->
<PUButton
  color="custom"
  custom-class="bg-purple-500 text-white hover:bg-purple-600"
  label="Custom"
/>

<!-- Additive customClass — overrides text color on a ghost button -->
<PUButton variant="ghost" custom-class="font-bold text-amber-500" label="Tweaked" />

<!-- Rotating endIcon via endIconClass (e.g. caret that flips when open) -->
<PUButton
  variant="ghost"
  label="Year"
  end-icon="mdi:chevron-down"
  :end-icon-class="isOpen ? 'rotate-180 transition-transform' : 'transition-transform'"
/>

<!-- Slot -->
<PUButton>
  <span>Custom content</span>
</PUButton>

customClass is now additive: it's merged into the class list through tailwind-merge, so conflicting utilities (text-*, bg-*, font-*, etc.) override the variant/color defaults automatically. Use color="custom" only when you want to fully replace the color scheme rather than override individual properties.

PUInput

A flexible input component with validation and state management.

<PUInput label="Username" placeholder="Enter your name" />

Props

Slots

Examples

<!-- Basic -->
<PUInput label="Email" type="email" placeholder="you@example.com" />

<!-- Select all on focus (great for pre-filled codes the user wants to replace) -->
<PUInput v-model="orderCode" label="Order code" focus />

<!-- With helper text -->
<PUInput label="Password" type="password" description="At least 8 characters" />

<!-- Required field -->
<PUInput label="Full name" required />

<!-- With error -->
<PUInput label="Username" error="This username is already taken" />

<!-- Disabled -->
<PUInput label="Disabled field" disabled value="Read only" />

<!-- With icons -->
<PUInput label="Search" placeholder="Search...">
  <template #startContent>
    <Icon name="lucide:search" />
  </template>
</PUInput>

<!-- Variants -->
<PUInput variant="default" label="Default" />
<PUInput variant="secondary" label="Secondary" />

PUInputOTP

A one-time-code input rendered as a row of single-character cells. Each character animates in with motion-v (spring scale + blur), the focused cell pops and shows a blinking caret, and completing the code gives the whole row a subtle bounce.

Typing advances to the next cell, Backspace clears and walks back, arrows / Home / End navigate, and pasting (or an SMS autofill that lands the whole code in one cell) fills every cell at once.

<PUInputOTP v-model="code" label="Verification code" @complete="verify" />

Props

Events

Exposed methods

Examples

<!-- Basic -->
<PUInputOTP v-model="code" label="Verification code" required />

<!-- Verify as soon as the last cell is filled -->
<PUInputOTP v-model="code" :error="error" @complete="verify" />

<!-- Grouped 123-456 -->
<PUInputOTP v-model="code" :separator-every="3" />

<!-- Custom separator -->
<PUInputOTP v-model="code" :separator-every="2" separator="•" />

<!-- Letters and digits -->
<PUInputOTP v-model="code" type="text" :length="5" />

<!-- Masked -->
<PUInputOTP v-model="pin" type="password" :length="4" />

<!-- Sizes and shapes -->
<PUInputOTP v-model="code" size="lg" rounded="full" variant="secondary" />

<!-- Circular cells -->
<PUInputOTP v-model="code" shape="circle" :length="4" />
<PUInputOTP v-model="code" shape="circle" size="lg" variant="secondary" />

<!-- With placeholder -->
<PUInputOTP v-model="code" :length="4" placeholder="0" />

<!-- With error -->
<PUInputOTP v-model="code" error="That code is expired. Request a new one." />

<!-- Disabled -->
<PUInputOTP model-value="4821" :length="4" disabled />

// Imperative control
const otp = ref()
otp.value?.focus()
otp.value?.clear()

PUTextArea

A multi-line text input. Shares the look and feel of PUInput, with extra props for rows and resize behavior.

<PUTextArea v-model="message" label="Message" placeholder="Write your message" />

Props

Slots

Examples

<!-- Basic -->
<PUTextArea v-model="message" label="Message" placeholder="Write your message" />

<!-- Fixed size, no resize -->
<PUTextArea label="Comment" :rows="6" resize="none" />

<!-- With error -->
<PUTextArea label="Bio" error="Bio is required" required />

<!-- With icon -->
<PUTextArea label="Notes">
  <template #startContent>
    <Icon name="lucide:notebook-pen" />
  </template>
</PUTextArea>

PUCheckbox

An animated checkbox powered by motion-v — the filled box and check mark pop in with a scale animation and shrink away when unchecked. Supports v-model with a boolean value; clicking the box or the label toggles it.

<PUCheckbox v-model="acceptTerms" label="Accept terms and conditions" />

Props

Events

Examples

<!-- Basic -->
<PUCheckbox v-model="newsletter" label="Subscribe to the newsletter" />

<!-- Label on the left -->
<PUCheckbox v-model="darkMode" label="Dark mode" label-position="left" />

<!-- Sizes -->
<PUCheckbox v-model="small" label="Small" size="sm" />
<PUCheckbox v-model="large" label="Large" size="lg" />

<!-- Round, radio-button look -->
<PUCheckbox v-model="enabled" label="Enabled" rounded="full" />

<!-- Without label -->
<PUCheckbox v-model="standalone" />

PUSelect

A custom select with an animated dropdown panel teleported to body. Dark-mode aware, supports v-model, and emits both update:modelValue and change. Only one PUSelect can be open at a time across the page — opening a new one automatically closes any other open select.

<PUSelect
  v-model="role"
  label="Role"
  :options="[
    { label: 'Admin', value: 'admin' },
    { label: 'Editor', value: 'editor' },
    { label: 'Viewer', value: 'viewer' },
  ]"
/>

Props

Events

Slots

Examples

<!-- Basic -->
<PUSelect v-model="country" :options="countries" label="Country" />

<!-- With description -->
<PUSelect
  v-model="plan"
  :options="plans"
  label="Plan"
  description="You can change this later"
/>

<!-- With error -->
<PUSelect v-model="status" :options="statuses" error="Pick a status" required />

<!-- Disabled -->
<PUSelect :options="statuses" disabled label="Locked" />

<!-- Multiple: v-model is an array, picking toggles, dropdown stays open -->
<PUSelect v-model="tags" :options="tagOptions" label="Tags" multiple />

<!-- Custom rendering: options can carry extra fields (e.g. email, avatar) -->
<PUSelect v-model="clientId" label="Client" :options="clients">
  <template #selected="{ option }">
    <div class="flex items-center gap-2 min-w-0">
      <span class="size-6 shrink-0 rounded-full bg-primary/15 text-primary text-xs font-semibold flex items-center justify-center">
        {{ String(option.label).charAt(0) }}
      </span>
      <span class="truncate">{{ option.label }}</span>
    </div>
  </template>
  <template #option="{ option, selected }">
    <div class="flex flex-col min-w-0 leading-tight">
      <span class="text-sm truncate" :class="selected ? 'text-primary' : ''">{{ option.label }}</span>
      <span class="text-xs text-gray-500 truncate">{{ option.email }}</span>
    </div>
  </template>
</PUSelect>

PUAutocomplete

A searchable variant of PUSelect — same look and dropdown behavior, but the trigger is a real <input> that filters the options as you type. Includes a clear (×) button that resets both the search text and the selected value. Like PUSelect, the dropdown is teleported to body and only one autocomplete can be open at a time.

<PUAutocomplete
  v-model="framework"
  label="Framework"
  placeholder="Search a framework"
  :options="[
    { label: 'Nuxt', value: 'nuxt' },
    { label: 'Vue', value: 'vue' },
    { label: 'React', value: 'react' },
  ]"
/>

Filtering is case-insensitive and matches label. When the input text matches the currently-selected option's label exactly, the list is shown unfiltered so the user can browse all options again without clearing first. On close without selection, the input reverts to the selected option's label (or empty if nothing was selected).

The dropdown is keyboard-navigable: the first match is highlighted as you type, so pressing Enter selects it without touching the mouse. ↑ / ↓ move the highlight (and scroll it into view), and Escape closes the dropdown. Reopening highlights the current selection. In multiple mode, Enter toggles the highlighted option and keeps the dropdown open.

Props

Events

Slots

Examples

<!-- Basic -->
<PUAutocomplete v-model="country" :options="countries" label="Country" />

<!-- Secondary variant + required -->
<PUAutocomplete
  v-model="city"
  variant="secondary"
  :options="cities"
  label="City"
  required
/>

<!-- With error -->
<PUAutocomplete
  v-model="status"
  :options="statuses"
  label="Status"
  error="Pick a status"
  required
/>

<!-- Remote search via the `search` event -->
<PUAutocomplete
  v-model="user"
  :options="remoteResults"
  label="User"
  placeholder="Type to search users"
  @search="onSearch"
/>

<!-- Multiple: v-model is an array; type to filter, pick several in a row -->
<PUAutocomplete v-model="countryCodes" :options="countries" label="Countries" multiple />

<!-- Custom rendering: options can carry extra fields (e.g. email) -->
<PUAutocomplete v-model="clientId" label="Client" :options="clients">
  <template #selected="{ option }">
    <div class="flex items-center gap-2 min-w-0">
      <span class="size-6 shrink-0 rounded-full bg-primary/15 text-primary text-xs font-semibold flex items-center justify-center">
        {{ String(option.label).charAt(0) }}
      </span>
      <span class="truncate">{{ option.label }}</span>
    </div>
  </template>
  <template #option="{ option, selected }">
    <div class="flex flex-col min-w-0 leading-tight">
      <span class="text-sm truncate" :class="selected ? 'text-primary' : ''">{{ option.label }}</span>
      <span class="text-xs text-gray-500 truncate">{{ option.email }}</span>
    </div>
  </template>
</PUAutocomplete>

PUDatePicker

A custom date picker that replaces the native <input type="date"> with a calendar popover. The popover is teleported to body (so it escapes any overflow ancestor) and renders a PUCalendar inside, so both components always look and behave the same. It includes a year scroller so the user can jump decades without arrow-clicking month by month. Like PUSelect/PUAutocomplete, only one popover can be open at a time across the page, and the panel re-positions itself on scroll and resize.

<PUDatePicker v-model="birthDate" label="Birth date" required>
  <template #startContent>
    <Icon name="lucide:calendar" />
  </template>
</PUDatePicker>

The modelValue is an ISO date string (YYYY-MM-DD). The trigger shows the date formatted via Intl.DateTimeFormat. All calendar texts (weekday labels, the Clear/Today buttons, the default placeholder and the month names) follow the lang prop — English by default, Spanish with lang="es". Click the month/year label in the popover header to open the year scroller — it auto-scrolls to the current view year. The Clear button clears the value, and the Today button picks today (disabled if today is outside min/max).

Props

Slots

Events

Examples

<!-- Basic -->
<PUDatePicker v-model="startDate" label="Start date" />

<!-- Bounded range (only 2026 dates) -->
<PUDatePicker
  v-model="bookingDate"
  label="Booking"
  min="2026-01-01"
  max="2026-12-31"
/>

<!-- Birthday picker with a wider year range -->
<PUDatePicker
  v-model="birthDate"
  label="Birth date"
  :min-year="1900"
  :max-year="2026"
  required
/>

<!-- Spanish calendar (weekdays, buttons, placeholder and month names) -->
<PUDatePicker v-model="date" label="Fecha" lang="es" />

<!-- English texts but day-first format -->
<PUDatePicker v-model="date" label="Date" locale="en-GB" />

<!-- Linked range — end date can't be before start date -->
<PUDatePicker v-model="startDate" label="Start" />
<PUDatePicker
  v-model="endDate"
  label="End"
  :min="startDate || undefined"
  variant="secondary"
/>

<!-- With validation error -->
<PUDatePicker
  v-model="date"
  label="Birth date"
  error="Please pick a valid date"
  required
/>

<!-- Inline label — label stacked above the value inside the trigger -->
<PUDatePicker v-model="startDate" label="Fecha inicial" inline-label />
<PUDatePicker v-model="endDate" label="Fecha final" inline-label />

Inline label is supported by all form components (PUInput, PUTextArea, PUSelect, PUAutocomplete, PUDatePicker). When inlineLabel is true, the external <label> above the field is hidden and the label renders as a small floating label inside the field — ideal for compact filter rows or dense forms. The required asterisk follows the label automatically.

The popover renders inside a wrapper that mirrors the host's .dark ancestor so all child PUButton/PUCard instances stay in sync with the app's theme — even though they are teleported to body. Dark-mode is captured on open; if the theme is toggled while the popover is open, close and reopen it to refresh.

PUCalendar

The inline calendar from PUDatePicker, without the input trigger — it renders directly in the page (inside a PUCard), so you can build always-visible pickers, sidebars, or booking UIs. Same date API as the date picker: ISO v-model, min/max bounds, year scroller, and the lang/locale pair. Today's date is marked with a thin primary border (hidden while today is the selected day, since the filled style already highlights it).

<PUCalendar v-model="date" />

Props

Events

Examples

<!-- Basic -->
<PUCalendar v-model="date" />

<!-- Bounded range -->
<PUCalendar v-model="date" min="2026-06-01" max="2026-07-31" />

<!-- Spanish -->
<PUCalendar v-model="date" lang="es" />

PUCard

A flexible card component with customizable styling and borders.

<PUCard>
  <h2>Card Title</h2>
  <p>Card content goes here</p>
</PUCard>

Props

Examples

<!-- Basic card -->
<PUCard>
  <p>Simple card with default styling</p>
</PUCard>

<!-- With border -->
<PUCard is-bordered>
  <h3>Bordered Card</h3>
  <p>This card has a border</p>
</PUCard>

<!-- Custom styling -->
<PUCard custom-class="bg-blue-100 p-6 rounded-lg">
  <p>Fully customized card</p>
</PUCard>

<!-- Slot content -->
<PUCard>
  <template #default>
    <div class="flex items-center gap-4">
      <img src="https://raw.githubusercontent.com/Smurfox/proxy-ui/HEAD/avatar.jpg" alt="Avatar" />
      <div>
        <h3>John Doe</h3>
        <p>User profile card</p>
      </div>
    </div>
  </template>
</PUCard>

PUAvatar

An avatar component that displays user images, icons, or initials.

<PUAvatar label="JD" />

Props

Examples

<!-- With initials -->
<PUAvatar label="JD" size="md" />

<!-- With icon -->
<PUAvatar icon="lucide:user" size="lg" />

<!-- With image -->
<PUAvatar image="https://example.com/avatar.jpg" />

<!-- Different sizes -->
<PUAvatar label="A" size="sm" />
<PUAvatar label="A" size="md" />
<PUAvatar label="A" size="lg" />

<!-- Border radius -->
<PUAvatar label="JD" rounded="none" />
<PUAvatar label="JD" rounded="md" />
<PUAvatar label="JD" rounded="full" />

PUChip

A compact component for displaying small pieces of information.

<PUChip label="Tag" />

Props

Examples

<!-- Basic -->
<PUChip label="React" />

<!-- Variants -->
<PUChip variant="default" label="Default" />
<PUChip variant="secondary" label="Secondary" />
<PUChip variant="outline" label="Outline" />
<PUChip variant="flat" label="Flat" />

<!-- Colors -->
<PUChip color="primary" label="Primary" />
<PUChip color="danger" label="Danger" />
<PUChip color="success" label="Success" />

<!-- Sizes -->
<PUChip size="sm" label="Small" />
<PUChip size="md" label="Medium" />
<PUChip size="lg" label="Large" />

<!-- With icons -->
<PUChip start-icon="lucide:check" label="Done" />
<PUChip end-icon="lucide:x" label="Close" />

PUTabs

A tabbed interface component with smooth animations.

<PUTabs
  v-model="activeTab"
  :tabs="[
    { label: 'Tab 1', value: 'tab1' },
    { label: 'Tab 2', value: 'tab2' },
  ]"
/>

Props

TabItem Interface

interface TabItem {
  label: string;
  value: string;
  icon?: string;
  disabled?: boolean;
}

Events

Examples

<template>
  <!-- Basic tabs -->
  <PUTabs
    v-model="activeTab"
    :tabs="[
      { label: 'Dashboard', value: 'dashboard' },
      { label: 'Settings', value: 'settings' },
      { label: 'Profile', value: 'profile' },
    ]"
  />

  <!-- With icons -->
  <PUTabs
    v-model="activeTab"
    :tabs="[
      { label: 'Home', value: 'home', icon: 'lucide:home' },
      { label: 'Bell', value: 'bell', icon: 'lucide:bell' },
      { label: 'User', value: 'user', icon: 'lucide:user' },
    ]"
  />

  <!-- With disabled tabs -->
  <PUTabs
    v-model="activeTab"
    :tabs="[
      { label: 'Active', value: 'active' },
      { label: 'Disabled', value: 'disabled', disabled: true },
    ]"
    :disabled-tabs="['disabled']"
  />

  <!-- Sizes -->
  <PUTabs v-model="activeTab" :tabs="tabs" size="sm" />
  <PUTabs v-model="activeTab" :tabs="tabs" size="lg" />

  <!-- Vertical layout -->
  <PUTabs v-model="activeTab" :tabs="tabs" is-vertical />

  <!-- Custom colors -->
  <PUTabs
    v-model="activeTab"
    :tabs="tabs"
    bg-color="bg-gray-100 dark:bg-gray-800"
    btn-color="bg-blue-500"
    active-text-color="text-blue-600"
  />
</template>

<script setup>
const activeTab = ref("dashboard");
</script>

PUDropdown

A floating panel anchored to an activator element. The menu is teleported to body and positioned with position: fixed relative to the activator, so it escapes any overflow ancestor (scroll containers, modals, etc.). The menu re-positions itself on scroll and resize while open. Opens on click and closes on outside click; only one PUDropdown can be open at a time across the page. Provides a closeDropdown function (via inject) so child items can close the panel after acting.

<PUDropdown>
  <template #activator>
    <PUButton label="Options" end-icon="lucide:chevron-down" />
  </template>
  <template #content>
    <ul class="p-2">
      <li class="px-3 py-2 hover:bg-gray-100 dark:hover:bg-white/10 rounded-lg cursor-pointer">
        Profile
      </li>
      <li class="px-3 py-2 hover:bg-gray-100 dark:hover:bg-white/10 rounded-lg cursor-pointer">
        Settings
      </li>
    </ul>
  </template>
</PUDropdown>

Props

Slots

Provides

<!-- Closing the dropdown from a child item -->
<script setup>
import { inject } from "vue";
const closeDropdown = inject("closeDropdown");
</script>

<template>
  <button @click="handleAction(); closeDropdown?.()">Action</button>
</template>

PULottie

A Lottie animation player powered by vue3-lottie. Renders inside ClientOnly so it is SSR-safe, and shrinks 80px in width and height on screens narrower than 768px.

<script setup>
import animationData from "./my-animation.json";
</script>

<template>
  <PULottie :animation-data="animationData" />
</template>

Props

Examples

<!-- Play once -->
<PULottie :animation-data="data" :loop="false" />

<!-- Custom size -->
<PULottie :animation-data="data" :width="240" :height="240" />

PUTable ships with a bundled empty-state Lottie that uses this component internally. You can disable or override it via the table's showEmptyAnimation and emptyAnimationData props.

PUTable

A responsive data table that renders as a normal <table> on md+ viewports and switches to a stack of cards on mobile. Cells are rendered through per-column scoped slots so you can fully customize their content.

<PUTable :columns="columns" :items="items" />

Props