ColorPicker

ColorPicker (색상 선택기)

ColorPicker는 사용자가 커스터마이즈된 색을 선택해야 할 때 사용하는 컴포넌트예요.

출처: 문서

본문

언제 사용하나요

사용자가 커스터마이즈된 색을 선택해야 할 때 사용해요.

예제 (Examples)

기본 사용 (Basic Usage)

기본 사용법이에요.

import React from 'react';
import { ColorPicker } from 'antd';

const Demo = () => <ColorPicker defaultValue="#1677ff" />;

export default Demo;

트리거 크기 (Trigger size)

Ant Design은 small, default, large 세 가지 트리거 크기를 지원해요.

large나 small 트리거가 필요하면 size 속성을 각각 large 또는 small로 설정하세요. 기본 크기는 size 속성을 생략하면 돼요.

import React from 'react';
import { ColorPicker, Space } from 'antd';

const Demo = () => (
  <Space>
    <Space vertical>
      <ColorPicker defaultValue="#1677ff" size="small" />
      <ColorPicker defaultValue="#1677ff" />
      <ColorPicker defaultValue="#1677ff" size="large" />
    </Space>
    <Space vertical>
      <ColorPicker defaultValue="#1677ff" size="small" showText />
      <ColorPicker defaultValue="#1677ff" showText />
      <ColorPicker defaultValue="#1677ff" size="large" showText />
    </Space>
  </Space>
);

export default Demo;

제어 모드 (controlled mode)

컴포넌트를 제어 모드로 설정해요. onChangeComplete로 제어하면 표시 색이 고정돼요.

import React, { useState } from 'react';
import { ColorPicker, Space } from 'antd';
import type { ColorPickerProps, GetProp } from 'antd';

type Color = GetProp<ColorPickerProps, 'value'>;

const Demo: React.FC = () => {
  const [color, setColor] = useState<Color>('#1677ff');

  return (
    <Space>
      <ColorPicker value={color} onChange={setColor} />
      <ColorPicker value={color} onChangeComplete={setColor} />
    </Space>
  );
};

export default Demo;

선형 그라데이션 (Line Gradient)

mode로 색을 단일 또는 그라데이션 색으로 설정해요.

import React from 'react';
import { ColorPicker, Space } from 'antd';

const DEFAULT_COLOR = [
  {
    color: 'rgb(16, 142, 233)',
    percent: 0,
  },
  {
    color: 'rgb(135, 208, 104)',
    percent: 100,
  },
];

const Demo = () => (
  <Space vertical>
    <ColorPicker
      defaultValue={DEFAULT_COLOR}
      allowClear
      showText
      mode={['single', 'gradient']}
      onChangeComplete={(color) => {
        console.log(color.toCssString());
      }}
    />
    <ColorPicker
      defaultValue={DEFAULT_COLOR}
      allowClear
      showText
      mode="gradient"
      onChangeComplete={(color) => {
        console.log(color.toCssString());
      }}
    />
  </Space>
);

export default Demo;

트리거 텍스트 렌더링 (Rendering Trigger Text)

showText가 true일 때 트리거의 기본 텍스트를 렌더링해요. 텍스트를 커스터마이즈할 때는 showText를 함수로 사용해 커스텀 텍스트를 반환할 수 있어요.

import React, { useState } from 'react';
import { DownOutlined } from '@ant-design/icons';
import { ColorPicker, Space } from 'antd';

const Demo = () => {
  const [open, setOpen] = useState(false);
  return (
    <Space vertical>
      <ColorPicker defaultValue="#1677ff" showText allowClear />
      <ColorPicker
        defaultValue="#1677ff"
        showText={(color) => <span>Custom Text ({color.toHexString()})</span>}
      />
      <ColorPicker
        defaultValue="#1677ff"
        open={open}
        onOpenChange={setOpen}
        showText={() => (
          <DownOutlined
            rotate={open ? 180 : 0}
            style={{
              color: 'rgba(0, 0, 0, 0.25)',
            }}
          />
        )}
      />
    </Space>
  );
};

export default Demo;

비활성 (Disable)

비활성 상태로 설정해요.

import React from 'react';
import { ColorPicker } from 'antd';

export default () => <ColorPicker defaultValue="#1677ff" showText disabled />;

Alpha 비활성 (Disabled Alpha)

색의 알파를 비활성화해요.

import React from 'react';
import { ColorPicker } from 'antd';

const Demo = () => <ColorPicker defaultValue="#1677ff" disabledAlpha />;

export default Demo;

색 지우기 (Clear Color)

색을 지워요.

import React from 'react';
import { ColorPicker } from 'antd';

export default () => {
  const [color, setColor] = React.useState<string>('#1677ff');
  return (
    <ColorPicker
      value={color}
      allowClear
      onChange={(c) => {
        setColor(c.toHexString());
      }}
    />
  );
};

커스텀 트리거 (Custom Trigger)

색 패널을 여는 커스텀 트리거예요.

import React, { useMemo, useState } from 'react';
import { Button, ColorPicker } from 'antd';
import type { ColorPickerProps, GetProp } from 'antd';

type Color = Extract<GetProp<ColorPickerProps, 'value'>, string | { cleared: any }>;

const Demo: React.FC = () => {
  const [color, setColor] = useState<Color>('#1677ff');

  const bgColor = useMemo<string>(
    () => (typeof color === 'string' ? color : color!.toHexString()),
    [color],
  );

  const btnStyle: React.CSSProperties = {
    backgroundColor: bgColor,
  };

  return (
    <ColorPicker value={color} onChange={setColor}>
      <Button type="primary" style={btnStyle}>
        open
      </Button>
    </ColorPicker>
  );
};

export default Demo;

커스텀 트리거 이벤트 (Custom Trigger Event)

색 패널을 여는 이벤트를 커스터마이즈하며, click과 hover 옵션을 제공해요.

import React from 'react';
import { ColorPicker } from 'antd';

const Demo = () => <ColorPicker defaultValue="#1677ff" trigger="hover" />;

export default Demo;

색 포맷 (Color Format)

인코딩 포맷으로 HEX, HSB, RGB를 지원해요.

import React, { useState } from 'react';
import { ColorPicker, Space } from 'antd';
import type { ColorPickerProps, GetProp } from 'antd';

type Color = Extract<GetProp<ColorPickerProps, 'value'>, string | { cleared: any }>;
type Format = GetProp<ColorPickerProps, 'format'>;

const HexCase: React.FC = () => {
  const [colorHex, setColorHex] = useState<Color>('#1677ff');
  const [formatHex, setFormatHex] = useState<Format | undefined>('hex');

  const hexString = React.useMemo<string>(
    () => (typeof colorHex === 'string' ? colorHex : colorHex?.toHexString()),
    [colorHex],
  );

  return (
    <Space>
      <ColorPicker
        format={formatHex}
        value={colorHex}
        onChange={setColorHex}
        onFormatChange={setFormatHex}
      />
      <span>HEX: {hexString}</span>
    </Space>
  );
};

const HsbCase: React.FC = () => {
  const [colorHsb, setColorHsb] = useState<Color>('hsb(215, 91%, 100%)');
  const [formatHsb, setFormatHsb] = useState<ColorPickerProps['format']>('hsb');

  const hsbString = React.useMemo(
    () => (typeof colorHsb === 'string' ? colorHsb : colorHsb?.toHsbString()),
    [colorHsb],
  );

  return (
    <Space>
      <ColorPicker
        format={formatHsb}
        value={colorHsb}
        onChange={setColorHsb}
        onFormatChange={setFormatHsb}
      />
      <span>HSB: {hsbString}</span>
    </Space>
  );
};

const RgbCase: React.FC = () => {
  const [colorRgb, setColorRgb] = useState<Color>('rgb(22, 119, 255)');
  const [formatRgb, setFormatRgb] = useState<ColorPickerProps['format']>('rgb');

  const rgbString = React.useMemo(
    () => (typeof colorRgb === 'string' ? colorRgb : colorRgb?.toRgbString()),
    [colorRgb],
  );

  return (
    <Space>
      <ColorPicker
        format={formatRgb}
        value={colorRgb}
        onChange={setColorRgb}
        onFormatChange={setFormatRgb}
      />
      <span>RGB: {rgbString}</span>
    </Space>
  );
};

const Demo: React.FC = () => (
  <Space vertical size="medium" style={{ display: 'flex' }}>
    <HexCase />
    <HsbCase />
    <RgbCase />
  </Space>
);

export default Demo;

프리셋 색 (Preset Colors)

색 선택기의 프리셋 색을 설정해요.

import React from 'react';
import { generate, green, presetPalettes, red } from '@ant-design/colors';
import { ColorPicker, theme } from 'antd';
import type { ColorPickerProps } from 'antd';

type Presets = Required<ColorPickerProps>['presets'][number];

function genPresets(presets = presetPalettes) {
  return Object.entries(presets).map<Presets>(([label, colors]) => ({ label, colors, key: label }));
}

const Demo: React.FC = () => {
  const { token } = theme.useToken();
  const presets = genPresets({ primary: generate(token.colorPrimary), red, green });
  return <ColorPicker presets={presets} defaultValue="#1677ff" />;
};

export default Demo;

커스텀 렌더 패널 (Custom Render Panel)

panelRender로 자유로운 컨트롤 패널을 렌더링해요.

import React from 'react';
import { cyan, generate, green, presetPalettes, red } from '@ant-design/colors';
import { Col, ColorPicker, Divider, Row, Space, theme } from 'antd';
import type { ColorPickerProps } from 'antd';

type Presets = Required<ColorPickerProps>['presets'][number];

function genPresets(presets = presetPalettes) {
  return Object.entries(presets).map<Presets>(([label, colors]) => ({ label, colors, key: label }));
}

const HorizontalLayoutDemo = () => {
  const { token } = theme.useToken();

  const presets = genPresets({
    primary: generate(token.colorPrimary),
    red,
    green,
    cyan,
  });

  const customPanelRender: ColorPickerProps['panelRender'] = (
    _,
    { components: { Picker, Presets } },
  ) => (
    <Row justify="space-between" wrap={false}>
      <Col span={12}>
        <Presets />
      </Col>
      <Divider vertical style={{ height: 'auto' }} />
      <Col flex="auto">
        <Picker />
      </Col>
    </Row>
  );

  return (
    <ColorPicker
      defaultValue={token.colorPrimary}
      styles={{ popupOverlayInner: { width: 480 } }}
      presets={presets}
      panelRender={customPanelRender}
    />
  );
};

const BasicDemo = () => (
  <ColorPicker
    defaultValue="#1677ff"
    panelRender={(panel) => (
      <div className="custom-panel">
        <div
          style={{
            fontSize: 12,
            color: 'rgba(0, 0, 0, 0.88)',
            lineHeight: '20px',
            marginBottom: 8,
          }}
        >
          Color Picker
        </div>
        {panel}
      </div>
    )}
  />
);

export default () => (
  <Space vertical>
    <Space>
      <span>Add title:</span>
      <BasicDemo />
    </Space>
    <Space>
      <span>Horizontal layout:</span>
      <HorizontalLayoutDemo />
    </Space>
  </Space>
);

커스텀 시맨틱 DOM 스타일링

classNames와 styles에 객체/함수를 전달해 ColorPicker의 시맨틱 DOM 스타일을 커스터마이즈할 수 있어요.

import React from 'react';
import { ColorPicker, Flex, Space } from 'antd';
import type { ColorPickerProps, GetProp } from 'antd';
import { createStyles } from 'antd-style';

const useStyles = createStyles(({ token }) => ({
  root: {
    borderRadius: token.borderRadius,
  },
}));

const stylesObject: ColorPickerProps['styles'] = {
  popup: {
    root: {
      border: '1px solid #fff',
    },
  },
};

const stylesFn: ColorPickerProps['styles'] = (
  info,
): GetProp<ColorPickerProps, 'styles', 'Return'> => {
  if (info.props.size === 'large') {
    return {
      popup: {
        root: {
          border: '1px solid #722ed1',
        },
      },
    };
  }
  return {};
};

const App: React.FC = () => {
  const { styles: classNames } = useStyles();
  return (
    <Space size={[8, 16]} wrap>
      <Flex gap="small">
        <ColorPicker
          defaultValue="#1677ff"
          arrow={false}
          styles={stylesObject}
          classNames={classNames}
        />
      </Flex>
      <Flex gap="small">
        <ColorPicker
          defaultValue="#722ed1"
          size="large"
          styles={stylesFn}
          arrow={false}
          classNames={classNames}
        />
      </Flex>
    </Space>
  );
};

export default App;

API

공통 props 참고: Common props

이 컴포넌트는 [email protected]부터 사용할 수 있어요.

속성	설명	타입	기본값	버전	전역 설정
allowClear	선택한 색 지우기 허용	boolean	false		×
arrow	팝업 화살표 설정	boolean | { pointAtCenter: boolean }	true		6.3.0
children	ColorPicker의 트리거	React.ReactNode	-		×
classNames	컴포넌트 내부 각 시맨틱 구조의 클래스 커스터마이즈. 객체 또는 함수 지원	Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>	-		6.0.0
defaultValue	색의 기본값	ColorType	-		×
defaultFormat	색의 기본 포맷	rgb | hex | hsb	hex	5.9.0	×
disabled	ColorPicker 비활성화	boolean	-		×
disabledAlpha	Alpha 비활성화	boolean	-	5.8.0	×
disabledFormat	색의 포맷 비활성화	boolean	-	5.22.0	×
destroyTooltipOnHide	닫을 때 dom 파괴 여부	boolean	false	5.7.0	×
destroyOnHidden	닫을 때 dom 파괴 여부	boolean	false	5.25.0	×
format	색의 포맷	rgb | hex | hsb	-		×
mode	단일 또는 그라데이션 색 설정	'single' | 'gradient' | ('single' | 'gradient')[]	single	5.20.0	×
open	팝업 표시 여부	boolean	-		×
presets	프리셋 색	PresetColorType	-		×
placement	팝업의 위치	placement 파라미터 디자인은 Tooltips 컴포넌트와 같음.	bottomLeft		×
panelRender	커스텀 렌더 패널	(panel: React.ReactNode, extra: { components: { Picker: FC; Presets: FC } }) => React.ReactNode	-	5.7.0	×
showText	색 텍스트 표시	boolean | (color: Color) => React.ReactNode	-	5.7.0	×
size	트리거 크기 설정	large | medium | small	medium	5.7.0	×
styles	컴포넌트 내부 각 시맨틱 구조의 인라인 스타일 커스터마이즈. 객체 또는 함수 지원	Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>	-		6.0.0
trigger	ColorPicker 트리거 모드	hover | click	click		×
value	색의 값	ColorType	-		×
onChange	value가 바뀔 때 콜백	(value: Color, css: string) => void	-		×
onChangeComplete	색 선택이 끝날 때 호출. onChangeComplete로 제어되는 value는 표시 색을 바꾸지 않음	(value: Color) => void	-	5.7.0	×
onFormatChange	format이 바뀔 때 콜백	(format: 'hex' | 'rgb' | 'hsb') => void	-		×
onOpenChange	open이 바뀔 때 콜백	(open: boolean) => void	-		×
onClear	지울 때 호출	() => void	-	5.6.0	×

ColorType

type ColorType =
  | string
  | Color
  | {
      color: string;
      percent: number;
    }[];

PresetColorType

type PresetColorType = {
  label: React.ReactNode;
  defaultOpen?: boolean;
  key?: React.Key;
  colors: ColorType[];
};

Color

속성	설명	타입	버전
toCssString	CSS 호환 포맷으로 변환	() => string	5.20.0
toHex	hex 포맷 문자로 변환, 반환 타입 예: 1677ff	() => string	-
toHexString	hex 포맷 색 문자열로 변환, 반환 타입 예: #1677ff	() => string	-
toHsb	hsb 객체로 변환	() => ({ h: number, s: number, b: number, a: number })	-
toHsbString	hsb 포맷 색 문자열로 변환, 반환 타입 예: hsb(215, 91%, 100%)	() => string	-
toRgb	rgb 객체로 변환	() => ({ r: number, g: number, b: number, a: number })	-
toRgbString	rgb 포맷 색 문자열로 변환, 반환 타입 예: rgb(22, 119, 255)	() => string	-

시맨틱 DOM (Semantic DOM)

https://ant.design/components/color-picker/semantic.md

FAQ

색 할당 관련 질문 {#faq-color-assignment}

색 선택기의 값은 문자열 색 값과 선택기에서 생성된 Color 객체를 모두 지원해요. 하지만 서로 다른 포맷의 색 문자열끼리 변환할 때 정밀도 오류가 있으므로, 제어 시나리오에서 할당 작업에는 선택기에서 생성된 Color 객체를 사용하는 것을 권장해요. 그러면 정밀도 문제를 피하고 값이 정확하며 선택기가 예상대로 동작함을 보장할 수 있어요.

더 알아보기 (Learn more)

• Typography 컴포넌트 — 색 텍스트 사용
• 색 (Color) — 색 시스템 이해하기
• Ant Design 시작하기 — 프로젝트 설정