vue3-color-picker-gradient

🎨 Color Picker with Gradient support for Vue 3, inspired by Element-Plus design.

Supports both solid colors and gradient colors with an intuitive trigger button and popup panel.

✨ Features

• 🎯 Element-Plus Style API - Similar to el-color-picker usage
• 🌈 Dual Mode - Solid color (linear) and Gradient color (gradient)
• 📦 v-model Support - Direct color value binding
• 🎪 Popper Dropdown - Auto-positioning popup panel
• 🚫 Disabled State - Support for disabled mode
• 🎨 Gradient Controls - Angle adjustment and multi-point gradients
• 🎭 Click Outside to Close - Auto-close when clicking outside
• 📱 Responsive - Smart positioning on scroll and resize

Live demo

Installation

NPM

$ npm install vue3-color-picker-gradient

ES6

Global Registration

import { createApp } from 'vue'
import ColorPickerGradient from 'vue3-color-picker-gradient'

const app = createApp(App)
app.use(ColorPickerGradient)

Local Registration

import ColorPickerGradient from 'vue3-color-picker-gradient'

export default {
  name: 'App',
  components: {
    ColorPickerGradient,
  },
}

📚 API

Props

| Property | Type | Default | Description | |----------|------|---------|-------------| | modelValue / v-model | String | '' | Binding value (rgba string for solid color, linear-gradient string for gradient) | | type | String | 'linear' | Picker type: 'linear' (solid) or 'gradient' (gradient) | | disabled | Boolean | false | Whether to disable the picker | | showAlpha | Boolean | true | Whether to display alpha slider | | disabledColorDeg | Boolean | false | Whether to disable angle control (gradient mode only) | | colorFormat | String | 'rgba' | Color format | | size | String | 'default' | Picker size: 'large' / 'default' / 'small' | | titleConfig | Object | {text:'颜色选择器',show:true} | Title configuration |

Events

| Event Name | Parameters | Description | |------------|------------|-------------| | change | (value: string) | Triggered when the color value changes | | active-change | (value: string) | Triggered when the active color changes |

📖 Usage Examples

Basic Usage - Solid Color

<template>
  <ColorPickerGradient
    v-model="color"
    type="linear"
    @change="handleColorChange"
  />
</template>

<script>
import { ref } from 'vue'
import ColorPickerGradient from 'vue3-color-picker-gradient'

export default {
  components: { ColorPickerGradient },
  setup() {
    const color = ref('rgba(255, 0, 0, 1)')

    const handleColorChange = (value) => {
      console.log('Color changed:', value)
    }

    return { color, handleColorChange }
  }
}
</script>

Gradient Color

<template>
  <ColorPickerGradient
    v-model="gradient"
    type="gradient"
  />
</template>

<script>
import { ref } from 'vue'
import ColorPickerGradient from 'vue3-color-picker-gradient'

export default {
  components: { ColorPickerGradient },
  setup() {
    const gradient = ref('linear-gradient(90deg, rgba(255,0,0,1) 0%, rgba(0,0,255,1) 100%)')

    return { gradient }
  }
}
</script>

Disabled State

<template>
  <ColorPickerGradient
    v-model="color"
    :disabled="true"
  />
</template>

Disable Angle Control (Gradient Mode)

<template>
  <ColorPickerGradient
    v-model="gradient"
    type="gradient"
    :disabledColorDeg="true"
  />
</template>

Complete Example

<template>
  <div class="demo">
    <h2>Solid Color Picker</h2>
    <ColorPickerGradient
      v-model="solidColor"
      type="linear"
      @change="handleChange"
    />
    <div class="preview" :style="{ background: solidColor }">
      {{ solidColor }}
    </div>

    <h2>Gradient Color Picker</h2>
    <ColorPickerGradient
      v-model="gradientColor"
      type="gradient"
      @change="handleGradientChange"
    />
    <div class="preview" :style="{ background: gradientColor }">
      {{ gradientColor }}
    </div>
  </div>
</template>

<script>
import { ref } from 'vue'
import ColorPickerGradient from 'vue3-color-picker-gradient'

export default {
  components: { ColorPickerGradient },
  setup() {
    const solidColor = ref('rgba(64, 158, 255, 1)')
    const gradientColor = ref('linear-gradient(90deg, rgba(255,255,255,1) 0%, rgba(0,0,0,1) 100%)')

    const handleChange = (value) => {
      console.log('Solid color:', value)
    }

    const handleGradientChange = (value) => {
      console.log('Gradient color:', value)
    }

    return {
      solidColor,
      gradientColor,
      handleChange,
      handleGradientChange
    }
  }
}
</script>

<style scoped>
.demo {
  padding: 20px;
}

.preview {
  width: 200px;
  height: 100px;
  margin-top: 10px;
  border-radius: 4px;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  font-size: 12px;
  text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5);
}
</style>

🔧 Development

Install Dependencies

npm install

Compiles and hot-reloads for development

npm run serve

Compiles and minifies for library

npm run lib

Lints and fixes files

npm run lint

🔄 Migration from Old API

If you're upgrading from the old API, here's a comparison:

Old API (v-model controls visibility):

<ColorPicker
  v-model="isShowColorPicker"
  type="linear"
  @changeColor="changeColor"
  :pColor="pColor"
/>

New API (v-model binds color value):

<ColorPickerGradient
  v-model="color"
  type="linear"
  @change="handleChange"
/>

Key Changes:

• ✅ v-model now binds the color value directly (not visibility)
• ✅ Automatic trigger button with popup panel
• ✅ Simplified event: @change instead of @changeColor
• ✅ Simplified props: direct color string instead of complex objects
• ✅ Auto-close on outside click (no need for closeOnClickBody)

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📄 License

MIT

⭐ Show Your Support

If this project helped you, please give it a ⭐️!

欢迎点个 star 🎉🎉🎉

Customize configuration

See Configuration Reference.