Vue Color Pickers

Common errors

• ReferenceError: TouchEvent is not defined

  cause This error occurs in environments where the `TouchEvent` global object is not present, such as some older browser versions or during server-side rendering (SSR) if not properly handled.
  fix This issue was specifically fixed in `vue-color` v3.0.2. Ensure you are using version 3.0.2 or later. For SSR, ensure that any client-side-only components, like color pickers, are loaded dynamically or rendered conditionally on the client-side (e.g., using `<client-only>` in Nuxt).

• Failed to resolve component: ComponentName

  cause This typically means the component was not correctly imported or registered in your Vue application, or you are trying to use a default import for a named export.
  fix Verify that you are using named imports for all components (e.g., `import { ChromePicker } from 'vue-color'`) and that the component is either globally registered or locally imported and registered in the `<script setup>` block or `components` option of your Vue component.

• Error: Cannot find module 'vue-color/style.css'

  cause The path to the stylesheet is incorrect, or the build system is not configured to handle CSS imports.
  fix Ensure the import statement `import 'vue-color/style.css'` is exactly as specified. If using a custom build setup, verify that your bundler (e.g., Webpack, Vite) has appropriate loaders configured to process CSS files.

Warnings

• breaking Version 3.0.0 was a complete rewrite, introducing full TypeScript support and migrating exclusively to Vue 3. This means that applications using Vue 2.x (prior to 2.7) are not compatible with `vue-color` v3 and should remain on previous major versions or migrate to Vue 2.7+ for partial compatibility.
  Fix: For Vue 2.x projects, either upgrade to Vue 2.7 or use `vue-color` v2.x. For Vue 3 projects, ensure you are on a compatible Vue version and use the v3 API as documented.
• breaking With the v3 rewrite, CommonJS `require()` syntax is no longer officially supported for importing components. The library is designed for ESM imports.
  Fix: Always use `import { ComponentName } from 'vue-color'` for components and `import 'vue-color/style.css'` for styles in your project.
• gotcha The `v-model` prop accepts various color formats (hex, rgb, hsl, object) and attempts to preserve the input format. However, mixing formats or expecting a specific output format without explicit conversion can lead to unexpected behavior in downstream components.
  Fix: If strict format consistency is required, normalize the color value using a library like `tinycolor2` (which `vue-color` uses internally) or implement custom formatting logic when handling the `v-model` output.
• gotcha For Vue 2.7 projects, `vue-color` v3 supports compatibility. However, specific usage patterns might differ slightly from a pure Vue 3 setup, especially regarding reactivity primitives like `ref` and `defineModel` (which is Vue 3 only).
  Fix: Refer to the `vue-color` documentation section 'Use with Vue 2.7' for specific guidance on setting up and using the components in Vue 2.7 environments. You might need to use `data()` and `props` with `emit` instead of `defineModel`.

Install

• npm install vue-color npm
• yarn add vue-color yarn
• pnpm add vue-color pnpm

Imports

• ChromePicker
  wrong:

  const ChromePicker = require('vue-color')

  correct:

  import { ChromePicker } from 'vue-color'

  For Vue 3, always use named imports with ESM syntax. CommonJS `require` is not officially supported and will likely lead to errors due to the library's ESM structure and TypeScript rewrite since v3.
• style.css

  import 'vue-color/style.css'

  Global styles are necessary for the pickers to render correctly. This import should be placed in your main application entry file (e.g., `main.ts` or `main.js`).
• SliderPicker
  wrong:

  import SliderPicker from 'vue-color'

  correct:

  import { SliderPicker } from 'vue-color'

  All color picker components are exported as named exports, not default exports. Attempting a default import will result in `undefined` or a runtime error.

Quickstart

Demonstrates how to import the global styles and use the `ChromePicker` component with `v-model` in a Vue 3 Composition API setup to display and update a color value.

import { createApp } from 'vue';
import App from './App.vue';
import 'vue-color/style.css';

createApp(App).mount('#app');

// In App.vue
<template>
  <div style="padding: 20px;">
    <h1>Pick a Color</h1>
    <ChromePicker v-model="color" />
    <p style="margin-top: 20px;">Selected Color: {{ color }}</p>
  </div>
</template>

<script setup lang="ts">
import { ChromePicker } from 'vue-color';
import { ref } from 'vue';

const color = ref('#68CCCA');
</script>