ColorPicker
Full-featured HSVA colour picker. Includes a gradient canvas, hue/alpha sliders, hex/RGB/HSL/HSV input fields and optional swatches. Composes OrigamColorPickerCanvas, OrigamColorPickerPreview, OrigamColorPickerEdit and OrigamColorPickerSwatches.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<origam-color-picker> — 6 composable regions.- 1.origam-color-picker
- Root element wrapping OrigamPicker. Inherits picker chrome (title, header, actions slots).
- 2.origam-color-picker-canvas
- Gradient canvas (OrigamColorPickerCanvas). Drag to change saturation + value. Hidden when hideCanvas=true.
- 3.origam-color-picker-preview
- Hue and alpha sliders + preview swatch (OrigamColorPickerPreview). Hidden when hideSliders=true.
- 4.origam-color-picker__controls
- Row grouping the preview strip and edit inputs.
- 5.origam-color-picker-edit
- Input fields + mode switcher (OrigamColorPickerEdit). Hidden when hideInputs=true.
- 6.origam-color-picker-swatches
- Predefined swatch grid (OrigamColorPickerSwatches). Visible only when showSwatches=true.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- canvasHeightstring | number150
- Height of the gradient canvas in pixels or a CSS length.
- canvasWidthstring | number
- Width of the gradient canvas. Defaults to 100% of the picker width.
- hideCanvasbooleanfalse
- Hides the gradient canvas section entirely.
- hideSlidersbooleanfalse
- Hides the hue and alpha slider strip.
- hideInputsbooleanfalse
- Hides the text input fields (HEX / RGB / HSL / HSV).
- showSwatchesbooleanfalse
- Shows the swatch grid below the inputs.
- swatchesMaxHeightstring | number
- Maximum height of the swatch grid. Adds a scrollbar when the swatch list overflows.
- modelValueRecord<string, unknown> | string | undefined | null
- Currently selected colour. Accepts a hex string, RGB/HSL/HSV object, or null. Use v-model for two-way binding.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border to the picker panel.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Border-radius token applied to the picker panel.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- Box-shadow elevation.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- landscapeboolean
- hideHeaderboolean
- sideTDirectionBoth
- swipeableboolean
- snapPointsReadonlyArray<TSheetSnapPoint>
- defaultSnapTSheetSnapId
- openboolean
- disabledbooleanfalse
- Disables all interaction. Canvas drag, slider drag and text inputs become non-interactive.
- persistentboolean
- handleLabelstring
- tagstring
- color
- Accent intent colour (e.g. active slider thumb colour).
- bgColorTColor
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- locationTAnchor
- positionTPosition
- topnumber | string
- bottomnumber | string
- leftnumber | string
- rightnumber | string
- activeboolean | IStateEffectConfig
- activeClassstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
- titlestring
- fontSizeTFontSize
- fontWeightTFontWeight
- letterSpacingTLetterSpacing
- colorHsv
- Internal HSVA colour representation forwarded to sub-components. Not typically set by consumers — use modelValue instead.
- dotSizestring | number
- Size of the drag cursor on the canvas.
- ariaLabelstring
- hideAlphaboolean
- mode
- Active colour input mode. Accepted: 'hex' | 'rgb' | 'hsl' | 'hsv' | 'rgba' | 'hsla' | 'hsva'.
- modes
- Allowed colour input modes shown in the mode switcher.
- swatchesArray<Array<TColorType>>
- Grid of swatches as a 2-D array of colour values. Each inner array is one row.
API
Slots
Emplacements de contenu exposés par ce composant.
- #title
- Title area at the top of the picker panel (forwarded from OrigamPicker).
- #header
- Header area below the title (forwarded from OrigamPicker).
- #default
- Replaces the built-in canvas + controls + swatches layout. Use when you need a fully custom inner structure.
- #actions
- Action buttons at the bottom of the picker panel (forwarded from OrigamPicker). Ideal for Cancel / Apply buttons.
API
Emits
Événements émis par ce composant.
- @update:modelValueany
- Fired when the selected colour changes. Payload matches the format of modelValue.
- @update:modeTColorModes
- Fired when the user switches the active input mode.
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward filtered props to OrigamPicker or sub-components.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- Ref<boolean>
- True once the style sheet has been injected.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- Picker panel background colour.
- Picker panel corner radius.
- Minimum width of the picker panel.
- Canvas corner radius.
- Size of the drag cursor circle on the canvas.
- Width of the current colour preview swatch.
- Height of the current colour preview swatch.
- Size of each swatch tile.
- Height of the hue slider track.
- Height of the alpha slider track.
Inclusion
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | Action |
|---|---|
| Tab | Moves focus between canvas, sliders, input fields and mode switcher. |
| Arrow keys (canvas) | Moves the canvas cursor by 1% increments in saturation/value. Allows precise colour selection without a mouse. |
| Arrow keys (sliders) | Adjusts the hue or alpha slider value by 1 step. |
Notes
- The canvas carries an aria-label describing the gradient region. The drag cursor position is announced via aria-valuemin/valuemax/valuenow attributes.
- Each text input has a visible label matching the mode (HEX, R, G, B, H, S, L…). Screen readers read the label and current value together.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- dimensionvar(--origam-space---2)
- Gap between edit input fields.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic colour picker
With swatches
With action buttons
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.
ColorPickerCanvas
Gradient canvas where the user drags a cursor to pick saturation and brightness.
ColorPickerPreview
Hue and alpha sliders with a colour preview swatch.
ColorPickerEdit
Inline input fields for HEX / RGB / HSL / HSV editing with mode switcher.
ColorPickerSwatches
Grid of predefined colour swatches for quick selection.