color picker

A swatch button that opens a panel to pick a color, with optional alpha and presets.

PreviousNext
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-preview',
  imports: [ZardColorPickerComponent],
  template: `
    <z-color-picker class="mx-auto" zShowValue [(value)]="color" />
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerPreviewComponent {
  readonly color = signal<string | null>('#2563eb');
}

Installation

Copy
npx zard-cli@latest add color-picker

Usage

import { ZardColorPickerComponent } from '@/shared/components/color-picker/color-picker.component';
Copy
<z-color-picker [(value)]="color" />
Copy

Examples

Basic

Without zShowValue the trigger is a square swatch. Pair it with a <label> through zId.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-basic',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field zOrientation="horizontal" class="mx-auto w-fit">
      <z-color-picker zId="color-picker-basic" [(value)]="color" />
      <label z-field-label for="color-picker-basic">Accent color</label>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerBasicComponent {
  readonly color = signal<string | null>('#16a34a');
}

Formats

zFormat decides the string you get back — and the one typed in the text field.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-formats',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field-group class="mx-auto w-60">
      <div z-field>
        <label z-field-label for="color-picker-format-hex">Hex</label>
        <z-color-picker zId="color-picker-format-hex" zShowValue [(value)]="hex" />
      </div>

      <div z-field>
        <label z-field-label for="color-picker-format-rgb">RGB</label>
        <z-color-picker zId="color-picker-format-rgb" zFormat="rgb" zShowValue [(value)]="rgb" />
      </div>

      <div z-field>
        <label z-field-label for="color-picker-format-hsl">HSL</label>
        <z-color-picker zId="color-picker-format-hsl" zFormat="hsl" zShowValue [(value)]="hsl" />
      </div>

      <div z-field>
        <label z-field-label for="color-picker-format-oklch">OKLCH</label>
        <z-color-picker zId="color-picker-format-oklch" zFormat="oklch" zShowValue [(value)]="oklch" />
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerFormatsComponent {
  readonly hex = signal<string | null>('#7c3aed');
  readonly rgb = signal<string | null>('rgb(234, 88, 12)');
  readonly hsl = signal<string | null>('hsl(199, 89%, 48%)');
  readonly oklch = signal<string | null>('oklch(0.723 0.219 149.579)');
}

Alpha

zAlpha adds an alpha slider; the value only carries alpha while the color is not opaque.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-alpha',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field class="mx-auto w-60">
      <label z-field-label for="color-picker-alpha">Overlay</label>
      <z-color-picker zId="color-picker-alpha" zFormat="rgb" zAlpha zShowValue [(value)]="color" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerAlphaComponent {
  readonly color = signal<string | null>('rgba(15, 23, 42, 0.6)');
}

Presets

Pass zPresets to offer a palette under the panel. The matching swatch is marked as pressed.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-presets',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field class="mx-auto w-60">
      <label z-field-label for="color-picker-presets">Label color</label>
      <z-color-picker zId="color-picker-presets" zShowValue [zPresets]="presets" [(value)]="color" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerPresetsComponent {
  protected readonly presets = [
    '#0f172a',
    '#dc2626',
    '#ea580c',
    '#f59e0b',
    '#16a34a',
    '#0d9488',
    '#2563eb',
    '#7c3aed',
    '#db2777',
  ];

  readonly color = signal<string | null>(null);
}

Events

zColorChange fires on every frame of a drag; zColorCommit only once the change settles, so it is the one to save from.

Live: —
Saved: —

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-events',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field class="mx-auto w-60">
      <label z-field-label for="color-picker-events">Theme color</label>
      <z-color-picker
        zId="color-picker-events"
        zShowValue
        zPlaceholder="No color yet"
        (zColorChange)="live.set($event)"
        (zColorCommit)="saved.set($event)"
      />
      <p z-field-description class="font-mono">
        Live: {{ live() ?? '—' }}
        <br />
        Saved: {{ saved() ?? '—' }}
      </p>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerEventsComponent {
  readonly live = signal<string | null>(null);
  readonly saved = signal<string | null>(null);
}

Form

Works with formControlName / ngModel, including the disabled state of the control.

Used for buttons and links.

Form value: { "brand": "#2563eb", "logo": "#0f172a" }

import { JsonPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule } from '@angular/forms';

import { ZardFieldImports } from '@/shared/components/field/field.imports';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-form',
  imports: [ZardColorPickerComponent, ZardFieldImports, ReactiveFormsModule, JsonPipe],
  template: `
    <form [formGroup]="form">
      <div z-field-group class="mx-auto w-60">
        <div z-field>
          <label z-field-label for="color-picker-form-brand">Brand color</label>
          <z-color-picker
            zId="color-picker-form-brand"
            formControlName="brand"
            zShowValue
            [zPresets]="['#0f172a', '#2563eb', '#16a34a', '#f59e0b', '#dc2626']"
          />
          <p z-field-description>Used for buttons and links.</p>
        </div>

        <div z-field data-disabled="true">
          <label z-field-label for="color-picker-form-locked">Logo color (locked)</label>
          <z-color-picker zId="color-picker-form-locked" formControlName="logo" zShowValue />
        </div>

        <p class="text-muted-foreground text-sm">Form value: {{ form.getRawValue() | json }}</p>
      </div>
    </form>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerFormComponent {
  private readonly fb = inject(FormBuilder);

  protected readonly form = this.fb.group({
    brand: ['#2563eb'],
    logo: [{ value: '#0f172a', disabled: true }],
  });
}

Sizes

zSize follows the button scale, so the picker lines up with the inputs around it.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardInputComponent } from '@/shared/components/input/input.component';

import { ZardColorPickerComponent } from '../color-picker.component';

@Component({
  selector: 'z-demo-color-picker-sizes',
  imports: [ZardColorPickerComponent, ZardInputComponent],
  template: `
    <div class="mx-auto flex w-fit flex-col gap-4">
      <div class="flex items-center gap-2">
        <z-color-picker zSize="sm" [(value)]="color" />
        <z-color-picker [(value)]="color" />
        <z-color-picker zSize="lg" [(value)]="color" />
      </div>

      <div class="flex items-center gap-2">
        <input z-input aria-label="Name" placeholder="Name" class="w-40" />
        <z-color-picker zShowValue class="w-36" [(value)]="color" />
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerSizesComponent {
  readonly color = signal<string | null>('#db2777');
}

RTL

To enable RTL support in zard/ui, see the RTL configuration guide.
// You will notice this example is rendered inside a wrapper that sets the dir and data-lang attributes, and
// reads its text from a translations helper. This is because this site is not RTL by default.
// In your application you won't need either: set dir="rtl" on <html> (or use the CDK Dir directive on a subtree)
// and write the text of your own language. See the RTL guide: https://zardui.com/docs/rtl

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardColorPickerComponent } from '@/shared/components/color-picker/color-picker.component';
import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { injectRtlTranslation, type ZardRtlTranslations } from '@/shared/demo-utils/rtl-translation';

const translations: ZardRtlTranslations<{ label: string; placeholder: string }> = {
  en: {
    dir: 'ltr',
    values: {
      label: 'Brand color',
      placeholder: 'Pick a color',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      label: 'لون العلامة التجارية',
      placeholder: 'اختر لونًا',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      label: 'צבע המותג',
      placeholder: 'בחרו צבע',
    },
  },
};

@Component({
  selector: 'z-demo-color-picker-rtl',
  imports: [ZardColorPickerComponent, ZardFieldImports],
  template: `
    <div z-field class="mx-auto w-60">
      <label z-field-label for="color-picker-rtl">{{ i18n.t().label }}</label>
      <z-color-picker
        zId="color-picker-rtl"
        zShowValue
        zAlpha
        [zPlaceholder]="i18n.t().placeholder"
        [zPresets]="presets"
        [(value)]="color"
      />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoColorPickerRtlComponent {
  protected readonly i18n = injectRtlTranslation(translations);
  protected readonly presets = ['#dc2626', '#f59e0b', '#16a34a', '#2563eb', '#7c3aed'];
  protected readonly color = signal<string | null>('#2563eb');
}

API Reference

z-color-picker

A swatch button that opens a panel in a popover: a saturation/brightness area, a hue slider, an optional alpha slider, a text field and optional presets. The value is a plain CSS color string in zFormat, and it works with formControl / ngModel through a ControlValueAccessor. Any hex, rgb(), hsl(), oklch() or named CSS color is accepted as input; an oklch() color outside sRGB is brought into gamut by lowering its chroma, as browsers do. A value written from outside is displayed in zFormat, but the value itself is only rewritten in zFormat (and stripped of alpha without zAlpha) when the user picks a color. Where the browser supports the EyeDropper API (Chromium), the panel also offers a button to pick a color from the screen.

Prop
[class]

Additional CSS classes on the host. Also where the trigger width is overridden with zShowValue

Type
ClassValue
Default
''
[zId]

Applied to the trigger button, so a <label for="…"> points at something focusable

Type
string
Default
''
[value]

Selected color, written in zFormat. null while nothing is picked. Supports two-way binding through [(value)]

Type
string | null
Default
null
[zFormat]

Format of the emitted value and of the text field. oklch is written like Tailwind CSS v4 tokens (oklch(0.628 0.25768 29.23)), with enough decimals to read back as the same color

Type
'hex' | 'rgb' | 'hsl' | 'oklch'
Default
'hex'
[zAlpha]

Shows the alpha slider and includes alpha in the value when the color is not opaque

Type
boolean
Default
false
[zPresets]

Preset swatches shown below the panel. Invalid colors are skipped

Type
string[]
Default
[]
[zSize]

Trigger size, on the same scale as z-button and z-input

Type
'sm' | 'default' | 'lg'
Default
'default'
[zShowValue]

Shows the value next to the swatch, turning the square trigger into a full-width field

Type
boolean
Default
false
[zPlaceholder]

Text shown in the trigger while no color is picked

Type
string
Default
'Pick a color'
[zAlign]

Alignment of the panel relative to the trigger

Type
'start' | 'center' | 'end'
Default
'start'
[zShowFormatToggle]

Shows HEX / RGB / HSL / OKLCH tabs above the text field. Only the text changes: the value is still emitted in zFormat

Type
boolean
Default
true
[zDisabled]

Disables the color picker. A disabled form control disables it too, whatever this input says

Type
boolean
Default
false
(zColorChange)

Emitted with the new value whenever the user changes the color, including every frame of a drag

Type
EventEmitter<string>
Default
—
(zColorCommit)

Emitted once the change settles: when a drag ends, on each key press, and when a preset, the text field or the eyedropper sets the color. Use it to save or call an API without debouncing

Type
EventEmitter<string>
Default
—
github iconwhatsapp icondiscord iconX icon

Made with ❤ in Brazil. Open source and available on GitHub .