MazColorPicker
MazColorPicker is a color field with a swatch button that opens a picker panel (saturation, hue, opacity, eye dropper, swatches). It reads any CSS color and emits hex, rgb, hsl or oklch. It can also be rendered inline.
Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started
Basic usage
Bind the color with v-model. The field is a MazInput: the user can type a color or open the panel with the swatch button.
Selected: #3b82f6
<script lang="ts" setup>
import MazColorPicker from 'maz-ui/components/MazColorPicker'
import { ref } from 'vue'
const color = ref('#3b82f6')
</script>
<template>
<MazColorPicker v-model="color" label="Brand color" />
</template>v-model accepts any CSS color: hex, rgb(), hsl(), oklch(), oklab() or a named color. When the user clears the field, the model is undefined. Every other attribute (label, top-label, size, hint, error, assistive-text, block, rounded-size...) is forwarded to the MazInput.
Formats
The format prop sets the format of the emitted color: hex (default), rgb, hsl or oklch. The incoming value can be in any format, it is converted on the next change.
<script lang="ts" setup>
import MazColorPicker from 'maz-ui/components/MazColorPicker'
import { ref } from 'vue'
const formatHex = ref('#8b5cf6')
const formatRgb = ref('#8b5cf6')
const formatHsl = ref('#8b5cf6')
const formatOklch = ref('#8b5cf6')
</script>
<template>
<MazColorPicker v-model="formatHex" format="hex" label="hex" />
<MazColorPicker v-model="formatRgb" format="rgb" label="rgb" />
<MazColorPicker v-model="formatHsl" format="hsl" label="hsl" />
<MazColorPicker v-model="formatOklch" format="oklch" label="oklch" />
</template>Opacity
The opacity slider is shown by default (alpha). The alpha channel is kept in the emitted value: #rrggbbaa in hex, rgb(r g b / a), hsl(h s l / a)... Set :alpha="false" to hide the slider and always emit an opaque color.
<script lang="ts" setup>
import MazColorPicker from 'maz-ui/components/MazColorPicker'
import { ref } from 'vue'
const alphaOn = ref('#3b82f680')
const alphaOff = ref('#3b82f6')
</script>
<template>
<MazColorPicker v-model="alphaOn" label="With opacity" />
<MazColorPicker v-model="alphaOff" :alpha="false" label="Without opacity" />
</template>Swatches
Pass preset colors with swatches, in any CSS format. They are shown under the sliders and selecting one emits it in the format of the component.
<script lang="ts" setup>
import MazColorPicker from 'maz-ui/components/MazColorPicker'
import { ref } from 'vue'
const swatchColor = ref('#3b82f6')
const brandSwatches = ['#3b82f6', '#8b5cf6', '#ec4899', '#10b981', '#f59e0b', '#ef4444', 'oklch(0.3 0.02 260)', 'white']
</script>
<template>
<MazColorPicker v-model="swatchColor" :swatches="brandSwatches" label="Brand palette" />
</template>Eye dropper
In the browsers that support the EyeDropper API, a button lets the user pick a color anywhere on the screen. It is hidden in the other browsers. Set :eye-dropper="false" to remove it.
Inline panel
With inline, the panel is rendered in the page instead of a popover. The text field sits under the sliders and the swatches.
<script lang="ts" setup>
import MazColorPicker from 'maz-ui/components/MazColorPicker'
import { ref } from 'vue'
const inlineColor = ref('#ec4899')
</script>
<template>
<MazColorPicker v-model="inlineColor" inline :swatches="['#3b82f6', '#ec4899', '#10b981']" />
</template>States and sizes
disabled blocks the field and the panel. error, hint and assistive-text come from the MazInput, like size.
<template>
<MazColorPicker v-model="color" disabled label="Disabled" />
<MazColorPicker v-model="color" error assistive-text="This color is not allowed" label="Error" />
<MazColorPicker v-model="color" size="sm" label="Small" />
<MazColorPicker v-model="color" size="lg" label="Large" />
</template>Events
update:model-value: the new color in theformatof the component, orundefinedwhen the field is cleared.openandclose: the popover opens or closes.
Use position to place the popover (bottom-start by default).
Keyboard and accessibility
- The swatch button has an accessible name,
aria-haspopup="dialog"andaria-expanded. The panel is a dialog. - The saturation and brightness area is focusable:
ArrowLeftandArrowRightchange the saturation,ArrowDownandArrowUpthe brightness. HoldShiftfor steps of 10%. - The hue and opacity sliders are native range inputs, with a text value (
aria-valuetext) and their own labels. - Every swatch is a button named with its color. The typed value is only applied when it is a valid CSS color, and the field is restored to the current color on blur.
Translations
The texts of the panel come from the colorPicker keys of @maz-ui/translations. Override some of them for one instance with the translations prop. {saturation}, {brightness} and {color} are replaced in areaValue and selectSwatch.
<template>
<MazColorPicker
v-model="color"
:translations="{
openPicker: 'Choisir une couleur',
hue: 'Teinte',
alpha: 'Opacité',
}"
/>
</template>Theming
Pick a color for your theme, then apply it as a preset. The Theme Editor of this documentation uses MazColorPicker to edit every color of a preset, with the format of your choice.
Props
| Name | Description | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| model-value | v-model The color, in any CSS format: hex, rgb(), hsl(), oklch(), oklab() or a named color. The component emits it in the format you choose. | string | No | - | - |
| format | Format of the emitted color | MazColorPickerFormat | No | "hex" | 'hex' | 'rgb' | 'hsl' | 'oklch' |
| alpha | Show the opacity slider and keep the alpha channel (#rrggbbaa, rgb(r g b / a)...) | boolean | No | true | - |
| swatches | Preset colors shown under the sliders, in any CSS format | string[] | No | - | - |
| eye-dropper | Show the button that picks a color on the screen, in the browsers that support the EyeDropper API | boolean | No | true | - |
| inline | Render the picker in the page instead of a popover | boolean | No | false | - |
| disabled | Disable the component | boolean | No | false | - |
| position | Position of the popover | MazPopoverPosition | No | "bottom-start" | - |
| id | Id of the text field (auto-generated if not provided) | string | No | - | - |
| translations | Translations of the component | { openPicker?: string | undefined; area?: string | undefined; areaValue?: string | undefined; hue?: string | undefined; alpha?: string | undefined; eyeDropper?: string | undefined; swatches?: string | undefined; selectSwatch?: string | u... | No | - | - |
Events
| Event name | Payload | Description |
|---|---|---|
| update:model-value | value: string | undefined | Emitted when the color changes, in the format of the component |
| open | - | Emitted when the popover opens |
| close | - | Emitted when the popover closes |
| update:modelValue | value: string | undefined |