Vue 3 Swatch Picker

1.2.4 · active · verified Sun Apr 19

vue3-swatches is a dedicated color swatch picker component designed for Vue 3 applications. It is a complete re-implementation, not a fork, of the popular vue-swatches library, adapted specifically for the Vue 3 composition API and ecosystem. The current stable version is 1.2.4. As a direct port, its features, API, and visual design closely mirror its Vue 2 predecessor. While no explicit release cadence is stated, updates are likely tied to significant changes in the original vue-swatches or general Vue 3 ecosystem evolution. Key differentiators include its robust feature set inherited from vue-swatches, ease of integration as a component or global plugin, and built-in support for custom triggers and integration with frameworks like Nuxt 3. Its primary advantage is providing a well-tested and familiar swatch picker solution for Vue 3 developers who might have previously used vue-swatches.

Common errors

```
[Vue warn]: Failed to resolve component: VSwatches
```
cause The VSwatches component was not properly imported or globally registered within your Vue application.

fix Ensure you have either `import { VSwatches } from 'vue3-swatches'` in your script setup or `app.use(VSwatches)` in your main.js/ts file for global registration.
```
Module not found: Error: Can't resolve 'vue3-swatches/dist/style.css' in '...'
```
cause The CSS file for styling the swatches component is missing or the import path is incorrect, preventing the bundler from locating it.

fix Add `import 'vue3-swatches/dist/style.css'` to your main entry file or the component where `VSwatches` is used. Verify the path is correct relative to your project structure.
```
TypeError: VSwatches is not a constructor (when using app.use()) or TypeError: Cannot read properties of undefined (reading 'install')
```
cause Attempting to use a named import for `VSwatches` when globally registering it as a plugin with `app.use()`, which expects the default export.

fix When using `app.use()`, ensure you are importing the default export: `import VSwatches from 'vue3-swatches'` (without curly braces).
```
[Vue warn]: hydration completed but contains mismatches. (in Nuxt environments)
```
cause Nuxt server-side rendering (SSR) hydration issues, often related to improper component registration or client-only rendering mismatches when not using the dedicated Nuxt module.

fix For Nuxt 3, ensure you are using the provided module by adding `'vue3-swatches/nuxt'` to your `modules` array in `nuxt.config.ts`.

Warnings

breaking Migrating from the original `vue-swatches` (Vue 2) to `vue3-swatches` (Vue 3) requires updating imports and ensuring API compatibility with Vue 3's composition API and lifecycle hooks. While the API aims to be consistent, underlying Vue version differences necessitate code changes.
Fix: Refactor imports, component registration, and prop usages to align with Vue 3 conventions and the specific API of `vue3-swatches`.
gotcha The component's styles are not automatically bundled with the component import. Failing to import `'vue3-swatches/dist/style.css'` will result in an unstyled or incorrectly styled component.
Fix: Add `import 'vue3-swatches/dist/style.css'` to your main entry file (e.g., `main.ts`/`main.js`) or the component where `VSwatches` is used.
gotcha For Nuxt 3 integration, `vue3-swatches` provides a specific module. Attempting to import and register the `VSwatches` component directly in a Nuxt application without using the module might lead to hydration issues or incorrect functionality, especially in SSR environments.
Fix: Configure `'vue3-swatches/nuxt'` in your `modules` array within `nuxt.config.ts` for proper Nuxt 3 integration.

Install

npm install vue3-swatches npm
yarn add vue3-swatches yarn
pnpm add vue3-swatches pnpm

Imports

VSwatches (local component)
wrong:
```
import VSwatches from 'vue3-swatches'
```
correct:
```
import { VSwatches } from 'vue3-swatches'
```
This is for local component registration within Vue SFCs using named imports.
VSwatches (global plugin)
wrong:
```
import { VSwatches } from 'vue3-swatches'
```
correct:
```
import VSwatches from 'vue3-swatches'
```
When registering as a global Vue plugin via `app.use()`, the default export is expected.
CSS Styles
```
import 'vue3-swatches/dist/style.css'
```
The component's styling is provided via a separate CSS file and must be explicitly imported in your entry file or relevant component.
Nuxt Module
wrong:
```
import { VSwatches } from 'vue3-swatches'
```
correct:
```
modules: ['vue3-swatches/nuxt']
```
For Nuxt 3 integration, utilize the provided module in `nuxt.config.ts` for proper setup and SSR compatibility.

Quickstart

Demonstrates local component import and basic usage with a `v-model` binding in a Vue 3 setup script. Also shows the required CSS import.

import { ref } from 'vue';
import { VSwatches } from 'vue3-swatches';
import 'vue3-swatches/dist/style.css';

const color = ref("#1FBC9C");

// In a Vue SFC <template> section:
// <VSwatches v-model="color" />

// Example with custom trigger (for demonstration, not runnable JS):
/*
<template>
  <VSwatches v-model="color">
    <template #trigger>
      <input :value="color" readonly />
    </template>
  </VSwatches>
</template>
*/

view raw JSON →