시간 선택

시간 선택 (TimePicker)

입력창을 클릭해 팝업 패널에서 시간을 선택할 수 있는 컴포넌트입니다.

출처: 문서

본문

언제 사용하나요 (When To Use)

입력창을 클릭하면 팝업 패널에서 시간을 선택할 수 있습니다.

예제 (Examples)

기본 (Basic)

TimePicker를 클릭하면 패널에서 시간을 선택하거나 입력할 수 있습니다.

import React from 'react';
import type { TimePickerProps } from 'antd';
import { TimePicker } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

const onChange: TimePickerProps['onChange'] = (time, timeString) => {
  console.log(time, timeString);
};

const App: React.FC = () => (
  <TimePicker onChange={onChange} defaultOpenValue={dayjs('00:00:00', 'HH:mm:ss')} />
);

export default App;

제어 (Under Control)

value와 onChange는 함께 사용해야 합니다.

import React, { useState } from 'react';
import { TimePicker } from 'antd';
import type { Dayjs } from 'dayjs';

const App: React.FC = () => {
  const [value, setValue] = useState<Dayjs | null>(null);

  const onChange = (time: Dayjs | null) => {
    setValue(time);
  };

  return <TimePicker value={value} onChange={onChange} />;
};

export default App;

세 가지 크기 (Three Sizes)

입력창은 large, medium, small 세 가지 크기가 있습니다. large는 폼에서, medium이 기본 크기로 사용됩니다.

import React from 'react';
import { Space, TimePicker } from 'antd';
import dayjs from 'dayjs';

const App: React.FC = () => (
  <Space wrap>
    <TimePicker defaultValue={dayjs('12:08:23', 'HH:mm:ss')} size="large" />
    <TimePicker defaultValue={dayjs('12:08:23', 'HH:mm:ss')} />
    <TimePicker defaultValue={dayjs('12:08:23', 'HH:mm:ss')} size="small" />
  </Space>
);

export default App;

확인 필요 (Need Confirm)

TimePicker는 picker 속성에 따라 확인(confirm) 버튼 표시 여부를 자동으로 결정합니다. needConfirm 속성을 설정해 확인 버튼 표시 여부를 직접 정할 수도 있습니다. needConfirm이 설정되면 사용자가 확인 버튼을 클릭해야 선택이 완료됩니다. 그렇지 않으면 picker가 포커스를 잃거나 시간을 선택할 때 선택이 제출됩니다.

import React from 'react';
import type { TimePickerProps } from 'antd';
import { TimePicker } from 'antd';

const onChange: TimePickerProps['onChange'] = (time, timeString) => {
  console.log(time, timeString);
};

const App: React.FC = () => <TimePicker onChange={onChange} needConfirm />;

export default App;

비활성화 (disabled)

TimePicker의 비활성화 상태입니다.

import React from 'react';
import { TimePicker } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

const App: React.FC = () => <TimePicker defaultValue={dayjs('12:08:23', 'HH:mm:ss')} disabled />;

export default App;

시와 분 (Hour and minute)

format의 일부를 생략하면 패널의 해당 컬럼도 함께 사라집니다.

import React from 'react';
import { TimePicker } from 'antd';
import dayjs from 'dayjs';

const format = 'HH:mm';

const App: React.FC = () => <TimePicker defaultValue={dayjs('12:08', format)} format={format} />;

export default App;

간격 옵션 (interval option)

hourStep, minuteStep, secondStep으로 계단식 옵션을 표시합니다.

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

const App: React.FC = () => <TimePicker minuteStep={15} secondStep={10} hourStep={1} />;

export default App;

애드온 (Addon)

타임 피커 패널 하단에 애드온 콘텐츠를 렌더링합니다.

import React, { useState } from 'react';
import { Button, TimePicker } from 'antd';

const App: React.FC = () => {
  const [open, setOpen] = useState(false);

  return (
    <TimePicker
      open={open}
      onOpenChange={setOpen}
      renderExtraFooter={() => (
        <Button size="small" type="primary" onClick={() => setOpen(false)}>
          OK
        </Button>
      )}
    />
  );
};

export default App;

12시간제 (12 hours)

기본 포맷이 h:mm:ss a인 12시간제 TimePicker입니다.

import React from 'react';
import type { TimePickerProps } from 'antd';
import { Space, TimePicker } from 'antd';

const onChange: TimePickerProps['onChange'] = (time, timeString) => {
  console.log(time, timeString);
};

const App: React.FC = () => (
  <Space wrap>
    <TimePicker use12Hours onChange={onChange} />
    <TimePicker use12Hours format="h:mm:ss A" onChange={onChange} />
    <TimePicker use12Hours format="h:mm a" onChange={onChange} />
  </Space>
);

export default App;

스크롤 시 변경 (Change on scroll)

changeOnScroll과 needConfirm을 사용해 스크롤할 때 값을 변경합니다.

import React from 'react';
import type { TimePickerProps } from 'antd';
import { TimePicker } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

const onChange: TimePickerProps['onChange'] = (time, timeString) => {
  console.log(time, timeString);
};

const App: React.FC = () => <TimePicker onChange={onChange} changeOnScroll needConfirm={false} />;

export default App;

시간 범위 피커 (Time Range Picker)

TimePicker.RangePicker로 시간 범위 피커를 사용합니다.

import React from 'react';
import { TimePicker } from 'antd';
import dayjs from 'dayjs';

const format = 'HH:mm:ss';

const App: React.FC = () => {
  const startTime = dayjs('12:08:23', 'HH:mm:ss');
  const endTime = dayjs('12:08:23', 'HH:mm:ss');

  return <TimePicker.RangePicker defaultValue={[startTime, endTime]} format={format} />;
};

export default App;

변형 (Variants)

TimePicker의 변형은 outlined, filled, borderless, underlined 네 가지입니다.

import React from 'react';
import { Flex, TimePicker } from 'antd';

const { RangePicker } = TimePicker;

const App: React.FC = () => (
  <Flex vertical gap={12}>
    <Flex gap={8}>
      <TimePicker placeholder="Outlined" />
      <RangePicker placeholder={['Outlined Start', 'Outlined End']} />
    </Flex>
    <Flex gap={8}>
      <TimePicker variant="filled" placeholder="Filled" />
      <RangePicker variant="filled" placeholder={['Filled Start', 'Filled End']} />
    </Flex>
    <Flex gap={8}>
      <TimePicker variant="borderless" placeholder="Borderless" />
      <RangePicker variant="borderless" placeholder={['Borderless Start', 'Borderless End']} />
    </Flex>
    <Flex gap={8}>
      <TimePicker variant="underlined" placeholder="Underlined" />
      <RangePicker variant="underlined" placeholder={['Underlined Start', 'Underlined End']} />
    </Flex>
  </Flex>
);

export default App;

상태 (Status)

status로 TimePicker에 상태를 추가합니다. error 또는 warning이 될 수 있습니다.

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

const App: React.FC = () => (
  <Space vertical>
    <TimePicker status="error" />
    <TimePicker status="warning" />
    <TimePicker.RangePicker status="error" />
    <TimePicker.RangePicker status="warning" />
  </Space>
);

export default App;

접두사와 접미사 (Prefix and Suffix)

커스텀 prefix와 suffixIcon을 설정합니다.

import React from 'react';
import { SmileOutlined } from '@ant-design/icons';
import { Space, TimePicker } from 'antd';
import type { TimePickerProps } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';

dayjs.extend(customParseFormat);

const onChange: TimePickerProps['onChange'] = (time, timeString) => {
  console.log(time, timeString);
};

const App: React.FC = () => (
  <Space vertical size={12}>
    <TimePicker
      suffixIcon={<SmileOutlined />}
      onChange={onChange}
      defaultOpenValue={dayjs('00:00:00', 'HH:mm:ss')}
    />
    <TimePicker prefix={<SmileOutlined />} />
    <TimePicker.RangePicker prefix={<SmileOutlined />} />
  </Space>
);

export default App;

커스텀 시맨틱 DOM 스타일링 (Custom semantic dom styling)

classNames와 styles에 객체 또는 함수를 넘겨서 TimePicker의 시맨틱 DOM 스타일을 커스터마이즈할 수 있습니다.

import React from 'react';
import { Flex, TimePicker } from 'antd';
import type { GetProp, TimePickerProps } from 'antd';
import { createStyles } from 'antd-style';

const useStyles = createStyles(({ token }) => ({
  root: {
    border: `${token.lineWidth}px ${token.lineType} ${token.colorPrimary}`,
    width: 150,
  },
}));

const stylesObject: TimePickerProps['styles'] = {
  root: {
    borderColor: '#d9d9d9',
  },
};

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

const App: React.FC = () => {
  const { styles: classNames } = useStyles();
  return (
    <Flex vertical gap="medium">
      <TimePicker classNames={classNames} styles={stylesObject} placeholder="Object" />
      <TimePicker classNames={classNames} styles={stylesFn} placeholder="Function" size="large" />
    </Flex>
  );
};

export default App;

API

---

Common props ref：Common props

import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat'

dayjs.extend(customParseFormat)

<TimePicker defaultValue={dayjs('13:30:56', 'HH:mm:ss')} />;

Property	Description	Type	Default	Version	Global Config
allowClear	Customize clear icon	boolean | { clearIcon?: ReactNode }	true	5.8.0: Support object type	6.4.0
addon	Called from time picker panel to render an addon to its bottom, please use renderExtraFooter instead	() => ReactNode	-	-	×
cellRender	Custom rendering function for picker cells	(current: number, info: { originNode: React.ReactElement, today: dayjs, range?: 'start' | 'end', subType: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode	-	5.4.0	×
changeOnScroll	Trigger selection when scroll the column	boolean	false	5.14.0	×
classNames	Customize class for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>	-		5.25.0
defaultValue	To set default time	dayjs	-		×
disabled	Determine whether the TimePicker is disabled	boolean	false		×
disabledTime	To specify the time that cannot be selected	DisabledTime	-	4.19.0	×
format	To set the time format	string	HH:mm:ss		×
getPopupContainer	To set the container of the floating layer, while the default is to create a div element in body	function(trigger)	-		×
hideDisabledOptions	Whether hide the options that can not be selected	boolean	false		×
hourStep	Interval between hours in picker	number	1		×
inputReadOnly	Set the readonly attribute of the input tag (avoids virtual keyboard on touch devices)	boolean	false		×
minuteStep	Interval between minutes in picker	number	1		×
needConfirm	Need click confirm button to trigger value change	boolean	-	5.14.0	×
open	Whether to popup panel	boolean	false		×
placeholder	Display when there's no value	string | [string, string]	Select a time		×
placement	The position where the selection box pops up	bottomLeft bottomRight topLeft topRight	bottomLeft		×
popupClassName	The className of panel, please use classNames.popup instead	string	-		×
popupStyle	The style of panel, please use styles.popup instead	CSSProperties	-		×
prefix	The custom prefix	ReactNode	-	5.22.0	×
previewValue	When the user selects the time hover option, the value of the input field undergoes a temporary change	false | hover	hover	6.0.0	×
renderExtraFooter	Called from time picker panel to render some addon to its bottom	() => ReactNode	-		×
secondStep	Interval between seconds in picker	number	1		×
showNow	Whether to show Now button on panel	boolean	-	4.4.0	×
size	To determine the size of the input box, the height of large and small, are 40px and 24px respectively, while default size is 32px	large | medium | small	-		×
status	Set validation status	'error' | 'warning' | 'success' | 'validating'	-	4.19.0	×
styles	Customize inline style for each semantic structure inside the component. Supports object or function.	Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>	-		5.25.0
suffixIcon	The custom suffix icon	ReactNode	-		6.3.0
use12Hours	Display as 12 hours format, with default format h:mm:ss a	boolean	false		×
value	To set time	dayjs	-		×
variant	Variants of picker	outlined | borderless | filled | underlined	outlined	5.13.0 | underlined: 5.24.0	5.19.0
onCalendarChange	Callback function, can be executed when the start time or the end time of the range is changing. info argument is added in 4.4.0	function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start|end })	-		×
onChange	A callback function, can be executed when the selected time is changing	function(time: dayjs, timeString: string): void	-		×
onClear	Callback when click the clear button	() => void	-	6.5.0	×
onOpenChange	A callback function which will be called while panel opening/closing	(open: boolean) => void	-		×

DisabledTime

type DisabledTime = (now: Dayjs) => {
  disabledHours?: () => number[];
  disabledMinutes?: (selectedHour: number) => number[];
  disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[];
  disabledMilliseconds?: (
    selectedHour: number,
    selectedMinute: number,
    selectedSecond: number,
  ) => number[];
};

참고: disabledMilliseconds는 5.14.0에서 추가되었습니다.

메서드 (Methods)

Name	Description	Version
blur()	Remove focus
focus()	Get focus

RangePicker

DatePicker의 RangePicker와 동일한 props를 가집니다. 그리고 추가 props도 포함합니다:

Property	Description	Type	Default	Version
disabledTime	To specify the time that cannot be selected	RangeDisabledTime	-	4.19.0
order	Order start and end time	boolean	true	4.1.0

RangeDisabledTime

type RangeDisabledTime = (
  now: Dayjs,
  type = 'start' | 'end',
) => {
  disabledHours?: () => number[];
  disabledMinutes?: (selectedHour: number) => number[];
  disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[];
};

시맨틱 DOM (Semantic DOM)

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

디자인 토큰 (Design Token)

컴포넌트 토큰 (Component Token - DatePicker)

Token Name	Description	Type	Default Value
activeBg	Background color when the input box is activated	string	#ffffff
activeBorderColor	Active border color	string	#1677ff
activeShadow	Box-shadow when active	string	0 0 0 2px rgba(5,145,255,0.1)
addonBg	Background color of addon	string	rgba(0,0,0,0.02)
cellActiveWithRangeBg	Background color of cell in range	string	#e6f4ff
cellBgDisabled	Background color of disabled cell	string	rgba(0,0,0,0.04)
cellHeight	Height of cell	number	24
cellHoverBg	Background color of cell hover state	string	rgba(0,0,0,0.04)
cellHoverWithRangeBg	Background color of hovered cell in range	string	#cbe0fd
cellRangeBorderColor	Border color of cell in range when picking	string	#82b4f9
cellWidth	Width of cell	number	36
errorActiveShadow	Box-shadow when active in error status	string	0 0 0 2px rgba(255,38,5,0.06)
hoverBg	Background color when the input box hovers	string	#ffffff
hoverBorderColor	Hover border color	string	#4096ff
inputFontSize	Font size	number	14
inputFontSizeLG	Font size of large	number	16
inputFontSizeSM	Font size of small	number	14
multipleItemBg	Background color of multiple tag	string	rgba(0,0,0,0.06)
multipleItemBorderColor	Border color of multiple tag	string	transparent
multipleItemBorderColorDisabled	Border color of multiple tag when disabled	string	transparent
multipleItemColorDisabled	Text color of multiple tag when disabled	string	rgba(0,0,0,0.25)
multipleItemHeight	Height of multiple tag	number	24
multipleItemHeightLG	Height of multiple tag with large size	number	32
multipleItemHeightSM	Height of multiple tag with small size	number	16
multipleSelectorBgDisabled	Background color of multiple selector when disabled	string	rgba(0,0,0,0.04)
paddingBlock	Vertical padding of input	number	4
paddingBlockLG	Vertical padding of large input	number	7
paddingBlockSM	Vertical padding of small input	number	0
paddingInline	Horizontal padding of input	number	11
paddingInlineLG	Horizontal padding of large input	number	11
paddingInlineSM	Horizontal padding of small input	number	7
presetsMaxWidth	Max width of preset area	number	200
presetsWidth	Width of preset area	number	120
textHeight	Height of cell text	number	40
timeCellHeight	Height of time cell	number	28
timeColumnHeight	Height of time column	number	224
timeColumnWidth	Width of time column	number	56
warningActiveShadow	Box-shadow when active in warning status	string	0 0 0 2px rgba(255,215,5,0.1)
withoutTimeCellHeight	Height of decade/year/quarter/month/week cell	number	66
zIndexPopup	z-index of popup	number	1050

글로벌 토큰 (Global Token)

Token Name	Description	Type	Default Value
borderRadius	Border radius of base components	number
borderRadiusLG	LG size border radius, used in some large border radius components, such as Card, Modal and other components.	number
borderRadiusSM	SM size border radius, used in small size components, such as Button, Input, Select and other input components in small size	number
borderRadiusXS	XS size border radius, used in some small border radius components, such as Segmented, Arrow and other components with small border radius.	number
boxShadowSecondary	Control the secondary box shadow style of an element.	string
colorBgContainer	Container background color, e.g: default button, input box, etc. Be sure not to confuse this with colorBgElevated.	string
colorBgContainerDisabled	Control the background color of container in disabled state.	string
colorBgElevated	Container background color of the popup layer, in dark mode the color value of this token will be a little brighter than colorBgContainer. E.g: modal, pop-up, menu, etc.	string
colorBorder	Default border color, used to separate different elements, such as: form separator, card separator, etc.	string
colorBorderDisabled	Control the border color of the element in the disabled state.	string
colorError	Used to represent the visual elements of the operation failure, such as the error Button, error Result component, etc.	string
colorErrorAffix	Control the color of form control prefix/suffix in error state.	string
colorErrorBg	The background color of the error state.	string
colorErrorBgHover	The hover state background color of the error state.	string
colorErrorBorderHover	The hover state border color of the error state.	string
colorErrorText	The default state of the text in the error color.	string
colorFillSecondary	The second level of fill color can outline the shape of the element more clearly, such as Rate, Skeleton, etc. It can also be used as the Hover state of the third level of fill color, such as Table, etc.	string
colorFillTertiary	The third level of fill color is used to outline the shape of the element, such as Slider, Segmented, etc. If there is no emphasis requirement, it is recommended to use the third level of fill color as the default fill color.	string
colorIcon	Weak action. Such as allowClear or Alert close button	string
colorIconHover	Weak action hover color. Such as allowClear or Alert close button	string
colorPrimary	Brand color is one of the most direct visual elements to reflect the characteristics and communication of the product. After you have selected the brand color, we will automatically generate a complete color palette and assign it effective design semantics.	string
colorPrimaryBorder	The stroke color under the main color gradient, used on the stroke of components such as Slider.	string
colorSplit	Used as the color of separator, this color is the same as colorBorderSecondary but with transparency.	string
colorText	Default text color which comply with W3C standards, and this color is also the darkest neutral color.	string
colorTextDisabled	Control the color of text in disabled state.	string
colorTextHeading	Control the font color of heading.	string
colorTextLightSolid	Control the highlight color of text with background color, such as the text in Primary Button components.	string
colorTextPlaceholder	Control the color of placeholder text.	string
colorTextQuaternary	The fourth level of text color is the lightest text color, such as form input prompt text, disabled color text, etc.	string
colorTextTertiary	The third level of text color is generally used for descriptive text, such as form supplementary explanation text, list descriptive text, etc.	string
colorWarning	Used to represent the warning map token, such as Notification, Alert, etc. Alert or Control component(like Input) will use these map tokens.	string
colorWarningAffix	Control the color of form control prefix/suffix in warning state.	string
colorWarningBg	The background color of the warning state.	string
colorWarningBgHover	The hover state background color of the warning state.	string
colorWarningBorderHover	The hover state border color of the warning state.	string
colorWarningText	The default state of the text in the warning color.	string
controlHeight	The height of the basic controls such as buttons and input boxes in Ant Design	number
controlHeightLG	LG component height	number
controlHeightSM	SM component height	number
controlItemBgActive	Control the background color of control component item when active.	string
fontFamily	The font family of Ant Design prioritizes the default interface font of the system, and provides a set of alternative font libraries that are suitable for screen display to maintain the readability and readability of the font under different platforms and browsers, reflecting the friendly, stable and professional characteristics.	string
fontSize	The most widely used font size in the design system, from which the text gradient will be derived.	number
fontSizeLG	Large font size	number
fontSizeSM	Small font size	number
fontWeightStrong	Control the font weight of heading components (such as h1, h2, h3) or selected item.	number
lineHeight	Line height of text.	number
lineHeightLG	Line height of large text.	number
lineType	Border style of base components	string
lineWidth	Border width of base components	number
lineWidthBold	The default line width of the outline class components, such as Button, Input, Select, etc.	number
marginXS	Control the margin of an element, with a small size.	number
marginXXS	Control the margin of an element, with the smallest size.	number
motionDurationMid	Motion speed, medium speed. Used for medium element animation interaction.	string
motionDurationSlow	Motion speed, slow speed. Used for large element animation interaction.	string
motionEaseInOutCirc	Preset motion curve.	string
motionEaseInQuint	Preset motion curve.	string
motionEaseOutCirc	Preset motion curve.	string
motionEaseOutQuint	Preset motion curve.	string
padding	Control the padding of the element.	number
paddingSM	Control the small padding of the element.	number
paddingXS	Control the extra small padding of the element.	number
paddingXXS	Control the extra extra small padding of the element.	number
sizePopupArrow	The size of the component arrow	number

FAQ

• Moment.js 같은 커스텀 날짜 라이브러리와 TimePicker 사용하는 방법

더 알아보기 (Learn more)

• 스타터 가이드: 시간 선택 문서 보기
• Ant Design 컴포넌트 개요
• ConfigProvider로 컴포넌트 설정하기