Color Input

Color Input lets a user specify a color by entering a hexadecimal value into a text field.

v14.2.34

Sources

GitHub Storybook Figma

Install

yarn add @workday/canvas-kit-react

Color Input Anatomy

Image of a Color Input in its default state.

Label: Title of the input. Label position could be set to the top or left of the Color Input.
Active Color Swatch: Square container that shows what the color looks like. Checkmark is optional and could be set on when a valid hex value is entered in the text input.
Text Input: Placeholder text of the Color Input is “#FFFFFF”. Placeholder text is replaced when the user enters a different hex value.

Color Input Usage Guidance

Color Input lets a user apply a specific color to an element.
The user should enter a value in hexadecimal format (6 digits).

When to Use

Use Color Input to apply a custom color to an element such as text or background color using hexadecimal numbers. This is commonly used for theming.

Color Input Examples

Basic Example

Color Input should be used in tandem with Form Field to meet accessibility standards.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Disabled

Set the disabled prop of the Color Input to prevent users from interacting with it.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} disabled onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Checked

Set the showCheck prop of the Color Input to display a check icon in the swatch.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} showCheck={true} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Ref Forwarding

Color Input supports ref forwarding. It will forward ref to its underlying <input type="text"> element.

Background Color

import React from 'react';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');
  const ref = React.useRef(null);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  const handleClick = () => {
    ref.current.focus();
  };

  return (
    <>
      <FormField>
        <FormField.Label>Background Color</FormField.Label>
        <FormField.Field>
          <FormField.Input as={ColorInput} onChange={handleChange} ref={ref} value={value} />
        </FormField.Field>
      </FormField>
      <PrimaryButton onClick={handleClick}>Focus Color Input</PrimaryButton>
    </>
  );
};

Valid Color Change Callback

Set the onValidColorChange prop of the Color Input to set a callback for when a valid hex color is provided.

The color passed to the callback will be prefixed with a hash and expanded if necessary. For example, 03F would be converted to #0033FF.

Background Color

Last valid color:

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';
import {type} from '@workday/canvas-kit-react/tokens';

export default () => {
  const [value, setValue] = React.useState('');
  const [validColor, setValidColor] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  const handleValidColorChange = (color: string) => {
    setValidColor(color);
  };

  return (
    <>
      <FormField>
        <FormField.Label>Background Color</FormField.Label>
        <FormField.Field>
          <FormField.Input
            as={ColorInput}
            onChange={handleChange}
            onValidColorChange={handleValidColorChange}
            value={value}
          />
        </FormField.Field>
      </FormField>
      <p style={type.levels.subtext.large}>Last valid color: {validColor}</p>
    </>
  );
};

Grow

Set the grow prop of the wrapping Form Field to true to configure the Color Input to expand to the width of its container.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField cs={{width: '100%'}}>
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input
          cs={{width: '100%'}}
          as={ColorInput}
          onChange={handleChange}
          value={value}
        />
      </FormField.Field>
    </FormField>
  );
};

The grow prop may also be applied directly to the Color Input if Form Field is not being used.

Label Position Horizontal

Set the orientation prop of the Form Field to designate the position of the label relative to the input component. By default, the orientation will be set to vertical.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField orientation="horizontalStart">
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Required

Set the required prop of the wrapping Form Field to true to indicate that the field is required. Labels for required fields are suffixed by a red asterisk.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField isRequired={true}>
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Error States

Set the error prop of the wrapping Form Field to "caution" or "error" to set the Color Input to the Caution or Error state, respectively. You will also need to set the hintId and hintText props on the Form Field to meet accessibility standards.

Caution

Background Color

Please select a background color.

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField error="caution">
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} value={value} />
        <FormField.Hint>Please select a background color.</FormField.Hint>
      </FormField.Field>
    </FormField>
  );
};

Error

Background Color

Please select a background color.

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorInput} from '@workday/canvas-kit-react/color-picker';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField error="error">
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorInput} onChange={handleChange} value={value} />
        <FormField.Hint>Please select a background color.</FormField.Hint>
      </FormField.Field>
    </FormField>
  );
};

Component API

ColorInput

Props

Props extend from input. Changing the as prop will change the element interface.

Name	Type	Description	Default
`value`	`string`	The value of the ColorInput.	`''`
`showCheck`	`boolean`	If true, show a checkmark in the swatch tile when a custom hex color is entered in the ColorInput.	`false`
`placeholder`	`string`	The placeholder text of the ColorInput.	`'FFFFFF'`
`error`		The type of error associated with the ColorInput (if applicable).
`disabled`	`boolean`	If true, set the ColorInput to the disabled state.	`false`
`onChange`	`(event: <>) => void`	The function called when the ColorInput state changes.
`onValidColorChange`	`(color: string) => void`	The function called when a valid hex value is entered in the ColorInput. The `color` argument passed to the callback function is prefixed with a hash and expanded if necessary (e.g., `03F` is converted to `#0033FF`).
`width`	`number \| string`	The width of the TextInput.
`grow`	`boolean`	True if the component should grow to its container's width. False otherwise.
`cs`		The `cs` prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using `cs`, you can merge that prop in as well. Any style that is passed to the `cs` prop will override style props. If you wish to have styles that are overridden by the `css` prop, or styles added via the `styled` API, use wherever `elemProps` is used. If your component needs to also handle style props, use {@link mergeStyles } instead. import {handleCsProp} from '@workday/canvas-kit-styling'; import {mergeStyles} from '@workday/canvas-kit-react/layout'; // ... // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same // function signature, but adds support for style props. return ( <Element {...handleCsProp(elemProps, [ myStyles, myModifiers({ size: 'medium' }), myVars({ backgroundColor: 'red' }) ])} > {children} </Element> )
`children`	`React.ReactNode`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`input`
`ref`	`React.Ref<R = input>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).

Specifications

Color Preview Anatomy

Image of a Color Preview in a changed state.

Label: Title of the input. Label position could be set to the top or left of the Color Preview.
Active Color Swatch: Square container that shows what the color looks like.
Value: 6 digit hexadecimal that corresponds to the active color swatch.

Color Preview Usage Guidance

Color Preview is the read-only version of a Color Input
It lets a user see what the color looks like in addition to displaying the hex value.

When to Use

When the color value of an element needs to be displayed, but should not be editable.

Color Preview Examples

Basic Example

Current Color

import {ColorPreview} from '@workday/canvas-kit-react/color-picker';
import {FormField} from '@workday/canvas-kit-react/form-field';

export default () => {
  return (
    <FormField>
      <FormField.Label>Current Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorPreview} value="#00ffcc" />
      </FormField.Field>
    </FormField>
  );
};

Ref Forwarding

Color Preview supports ref forwarding. It will forward ref to its underlying <input type="text"> element.

Background Color

Width of Color Preview:

import React from 'react';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorPreview} from '@workday/canvas-kit-react/color-picker';
import {type} from '@workday/canvas-kit-react/tokens';

export default () => {
  const [width, setWidth] = React.useState(null);
  const ref = React.useRef(null);

  const handleClick = () => {
    setWidth(ref.current.offsetWidth);
  };

  return (
    <>
      <FormField>
        <FormField.Label>Background Color</FormField.Label>
        <FormField.Field>
          <FormField.Input as={ColorPreview} ref={ref} value="#00ffcc" />
        </FormField.Field>
      </FormField>
      <p style={type.levels.subtext.large}>Width of Color Preview: {width}</p>
      <PrimaryButton onClick={handleClick}>Calculate Width of Color Preview</PrimaryButton>
    </>
  );
};

Label Position Horizontal

Set the orientation prop of the Form Field to designate the position of the label relative to the input component. By default, the orientation will be set to vertical.

Background Color

import React from 'react';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {ColorPreview} from '@workday/canvas-kit-react/color-picker';

export default () => {
  return (
    <FormField orientation="horizontalStart">
      <FormField.Label>Background Color</FormField.Label>
      <FormField.Field>
        <FormField.Input as={ColorPreview} value="#00ffcc" />
      </FormField.Field>
    </FormField>
  );
};

Component API

ColorPreview

Props

Props extend from input. Changing the as prop will change the element interface.

Name	Type	Description	Default
`value`	`string`	The value of the ColorPreview.
`id`	`string`	The HTML `id` of the underlying text input element.
`error`		The type of error associated with the TextInput (if applicable).
`width`	`number \| string`	The width of the TextInput.
`grow`	`boolean`	True if the component should grow to its container's width. False otherwise.
`cs`		The `cs` prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using `cs`, you can merge that prop in as well. Any style that is passed to the `cs` prop will override style props. If you wish to have styles that are overridden by the `css` prop, or styles added via the `styled` API, use wherever `elemProps` is used. If your component needs to also handle style props, use {@link mergeStyles } instead. import {handleCsProp} from '@workday/canvas-kit-styling'; import {mergeStyles} from '@workday/canvas-kit-react/layout'; // ... // `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same // function signature, but adds support for style props. return ( <Element {...handleCsProp(elemProps, [ myStyles, myModifiers({ size: 'medium' }), myVars({ backgroundColor: 'red' }) ])} > {children} </Element> )
`children`	`React.ReactNode`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`input`
`ref`	`React.Ref<R = input>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).

Specifications

Accessibility Guidelines

Color Input and Color Preview must have visual labels that clearly indicate the purpose of the input.
When possible, error and alert states should provide information on how to fix issues or provide hints on how to fix formatting.
Do not use color alone to differentiate between errors and alerts. Although color is a great visual indicator for users without disabilities, “Error” or “Alert” text should always be used to distinguish errors and alerts on a page. Use icons as supplementary visual indicators for different message states.

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #ask-canvas-design or #ask-canvas-kitchannels on Slack.

FAQ Section

Color Input

Color Input Anatomy

Color Input Usage Guidance

When to Use

Color Input Examples

Basic Example

Disabled

Checked

Ref Forwarding

Valid Color Change Callback

Grow

Label Position Horizontal

Required

Error States

Caution

Error

Component API

ColorInput

Props

Specifications

Color Preview Anatomy

Color Preview Usage Guidance

When to Use

Color Preview Examples

Basic Example

Ref Forwarding

Label Position Horizontal

Component API

ColorPreview

Props

Specifications

Accessibility Guidelines

Can't Find What You Need?

On this Page:

Resources

Guidelines

Workday