ColorPicker

Demos

How to import

<script setup lang="ts">
    import { ColorPicker } from '@fibrous/semi-ui-vue';
</script>

Basic Use

In portal

<script setup lang="ts">
    import { Button, ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <div>
        <ColorPicker alpha usePopover @change="onChange" />
        <br />
        <div>自定义 trigger</div>
        <ColorPicker alpha usePopover @change="onChange">
            <Button> Trigger </Button>
        </ColorPicker>
    </div>
</template>

Normal display

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha @change="onChange" />
</template>

Eyedropper Color Picker

The eyedropper is enabled by default and supports picking colors from the browser or external software screen. Pass :eyeDropper="false" to turn it off.

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha eyeDropper @change="onChange" />
</template>

Default Value

When converting between various color representation formats, there are theoretical errors between some formats, so the value delivered by the change and update:modelValue events is an object containing color values in three formats: hsva, hex, and rgba.

The defaultValue (uncontrolled) and modelValue (controlled) you pass in should also be objects containing the same three formats.

We provide a static tool function colorStringToValue on the component to convert common color strings to this object, supporting direct passing of strings such as rgb(57,197,187) #39c5bb (the short form #3cb is also accepted) and hsv(176,71,77). A string that cannot be parsed throws an error.

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    const defaultValue = ColorPicker.colorStringToValue('rgb(57,197,187)');

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <div>
        <ColorPicker alpha :defaultValue="defaultValue" @change="onChange" />
    </div>
</template>

Controlled

Bind modelValue with v-model for controlled use. Treat the color value as immutable and replace it as a whole when updating; mutating a field such as hsva.h in place does not sync the text inputs.

<script setup lang="ts">
    import { shallowRef } from 'vue';
    import { ColorPicker } from '@fibrous/semi-ui-vue';

    const value = shallowRef(ColorPicker.colorStringToValue('#39c5bb'));
</script>

<template>
    <div>
        <ColorPicker v-model="value" alpha />
    </div>
</template>

Rendering additional elements at the top and bottom

Use the #topSlot and #bottomSlot slots to render additional elements at the top and bottom

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha @change="onChange">
        <template #topSlot>
            <div>TopSlot</div>
        </template>
        <template #bottomSlot>
            <div>Bottom Slot</div>
        </template>
    </ColorPicker>
</template>

Keyboard and Focus

• With usePopover, the default trigger is a named button, and Enter or Space opens the popup. The popup is a dialog that opens on click by default and closes with Esc. Its name defaults to the built-in text; an aria-label or aria-labelledby passed in popoverProps (ariaLabel, ariaLabelledby in Vue) takes precedence.
• The handles of the color area, the hue slider and the alpha slider can all be operated with the keyboard. The color area has two sliders, saturation and brightness; the hue slider and the alpha slider have one each.
• Arrow keys step by 1, PageUp and PageDown step by 10, and Home and End jump to the ends. In the color area, whichever slider has focus, Left and Right change saturation, while Up, Down, PageUp and PageDown change brightness; Home and End act on the focused slider. Keys pressed with Alt, Ctrl or Meta are not handled, so the browser and assistive technology keep them.
• A focused handle shows the theme focus ring; the color input, the alpha input and the format selector all have accessible names.

API Table

ColorPicker

Props

Events

Slots

Exposes

Attribute placement

class, style and other undeclared attributes land on the picker root element; with usePopover they land on the picker element inside the popup, not on the trigger or the dialog. When the caller passes aria-label or aria-labelledby without a role, the picker root gets role="group".

ColorValue

modelValue, defaultValue and the event payloads are all the same kind of object: