React 날짜 범위 선택기 개요

Ignite UI for React 날짜 범위 선택기는 텍스트 입력과 달력 팝업을 포함하는 경량 구성 요소로, 사용자가 시작 날짜와 종료 날짜를 쉽게 선택할 수 있습니다. 다양한 애플리케이션 요구 사항에 맞게 사용자 정의가 가능하며 날짜 범위 제한, 구성 가능한 날짜 형식 등과 같은 기능을 제공합니다.

Date Range Picker Example

Below is a sample demonstrating the IgrDateRangePicker component in action, where a calendar pop-up allows users to select start and end dates.

시작하기

To start using the IgrDateRangePicker, you first need to install the Ignite UI for React by running the following command:

npm install igniteui-react

After that, you need to import the IgrDateRangePicker and its necessary CSS, as follows:

import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

Now you can start with a basic configuration of the React IgrDateRangePicker.

Ignite UI for React에 대한 완전한 소개는 '시작 주제'를 읽어보세요.

Usage

The IgrDateRangePicker allows users to select a start and end date either by choosing a date range from a dropdown/calendar pop-up or by typing directly into the input fields - one for the start date and one for the end date.

선택기는 날짜 값을 표시하기 위한 두 가지 모드(단일 입력과 두 개의 입력)를 제공합니다. 단일 입력 모드에서는 필드를 편집할 수 없으며 입력하여 날짜 범위를 편집할 수 없습니다. 그러나 두 개의 입력 모드에서 사용자는 별도의 입력 필드를 입력하여 시작 날짜와 종료 날짜를 편집할 수 있습니다.

달력이 표시되면 시작 날짜와 종료 날짜를 모두 선택하여 날짜 범위를 선택할 수 있습니다. 날짜를 선택하면 시작 날짜와 종료 날짜가 모두 설정되며, 두 번째 날짜를 선택하면 종료 날짜가 설정됩니다. 범위가 이미 선택되어 있는 경우 달력에서 다른 날짜를 클릭하면 새 범위 선택이 시작됩니다.

Display Date Range Picker

To instantiate a IgrDateRangePicker in its default single input mode, use the following code:

<IgrDateRangePicker/>

To switch the IgrDateRangePicker to use two inputs, set the useTwoInputs property to true.

<IgrDateRangePicker useTwoInputs/>

Value

In addition to being selected or typed by the user, the range value of the IgrDateRangePicker can also be set using the value property. It's important to note that the value must follow the format: { start: startDate, end: endDate }, where startDate and endDate are Date objects representing the selected range.

const dateRangeRef = useRef<IgrDateRangePicker>();
let startDate = new Date(2025, 4, 6);
let endDate = new Date(2025, 4, 8);
useEffect (() => {
  dateRangeRef.current.value = { start: startDate, end: endDate }
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

<IgrDateRangePicker value={{start: new Date('2025-01-01'), end: new Date('2025-01-02')}}/>

Read-only & Non-editable

You can also make the IgrDateRangePicker read-only, which disables changing the range value through both typing and calendar selection, disables keyboard navigation, and makes the calendar and clear icons appear visually disabled. This is useful when the range is assigned via the value attribute and is intended to be display-only. To enable this behavior, simply set the readOnly property.

<IgrDateRangePicker useTwoInputs readOnly/>

Alternatively, you can use the nonEditable property, which, unlike readOnly, only prevents editing the input(s) via typing, while still allowing selection through the calendar and clearing via the clear icon.

<IgrDateRangePicker useTwoInputs nonEditable/>

By default, when clicked, the IgrDateRangePicker opens its calendar pop-up in dropdown mode. Alternatively, the calendar can be opened in dialog mode by setting the mode property to dialog.

<IgrDateRangePicker mode='dialog'/>

The IgrDateRangePicker features intuitive keyboard navigation, allowing users to easily increment, decrement, or jump between different component parts, all without needing to use a mouse.

사용 가능한 키보드 탐색 옵션은 구성 요소가 단일 입력 모드인지 두 입력 모드인지에 따라 달라집니다.

두 개의 입력 모드:

열쇠	설명
`←`	캐럿을 왼쪽으로 한 문자 이동합니다.
`→`	캐럿을 오른쪽으로 한 문자 이동합니다.
`CTRL` + `ArrowLeft`	캐럿을 현재 입력 마스크 섹션의 시작 부분으로 이동하거나 이미 시작 부분에 있는 경우 이전 섹션의 시작 부분으로 이동합니다
`CTRL` + `ArrowRight`	캐럿을 현재 입력 마스크 섹션의 끝으로 이동하거나 이미 끝에 있는 경우 다음 섹션의 끝으로 이동합니다.
`ArrowUp`	입력 마스크의 현재 "초점이 맞춰진" 부분을 한 단계씩 증가시킵니다
`ArrowDown`	입력 마스크의 현재 "초점이 맞춰진" 부분을 한 단계 감소시킵니다.
`집`	캐럿을 입력 마스크의 시작 부분으로 이동합니다.
`끝`	캐럿을 입력 마스크의 끝으로 이동합니다.
`CTRL` +`;`	현재 날짜를 구성 요소의 값으로 설정합니다.

단일 및 두 개의 입력 모드 모두:

열쇠	설명
`ALT` + `↓`	Opens the calendar dropdown
`ALT` + `↑`	Closes the calendar dropdown

You can also navigate within the calendar pop-up using the keyboard. The navigation is the same as in the IgrCalendar component.

열쇠	설명
`↑` / `↓` / `←` / `→`	해당 월의 요일을 탐색합니다.
`ENTER`	현재 초점이 맞춰진 날짜를 선택합니다.
`페이지 업`	이전 달의 보기로 이동합니다.
`페이지 다운`	다음 달 보기로 이동합니다.
`SHIFT` + `PAGE UP`	전년도로 이동
`SHIFT` + `PAGE DOWN`	다음 해로 이동
`집`	보기에 있는 현재 달의 첫 번째 날(또는 두 개 이상의 개월 보기가 표시되는 경우 가장 빠른 달)에 초점을 맞춥니다.
`끝`	현재 표시된 달의 마지막 날에 초점을 맞춥니다. (또는 두 개 이상의 개월 보기가 표시되는 경우 최신 달)
`Escape`	캘린더 팝업을 닫습니다.

Layout

Label

You can define a label for the IgrDateRangePicker component using the label property when it is in single input mode. In two inputs mode, you can use the labelStart and labelEnd properties to define labels for the start and end date input fields, respectively.

<IgrDateRangePicker label='Date Range'/>

<IgrDateRangePicker useTwoInputs labelStart='Start Date' labelEnd='End Date'/>

Format

You also have the option to customize the date format displayed in the input fields. There are three properties available for this purpose: locale, inputFormat, and displayFormat.

The locale property allows you to set the desired locale identifier, which determines how the date is formatted based on regional conventions. For example, to display the date in a Japanese format, you can set the locale property like this:

<IgrDateRangePicker locale='ja-JP'/>

If you want to manually define the date format, you can use the inputFormat property by passing a custom format string:

<IgrDateRangePicker inputFormat='dd/MM/yy'/>

The displayFormat property also accepts a custom format string, but it only applies when the input field is idle (i.e., not focused). When the field is focused, the format reverts to the default or to the one defined by inputFormat, if both properties are used together:

<IgrDateRangePicker inputFormat='dd/MM/yy' displayFormat='yy/MM/dd'/>

Calendar Layout and Formatting

You can further customize the pop-up calendar using various properties:

이름	유형	설명
`orientation`	'vertical' or 'horizontal'	달력을 세로로 표시할지 가로로 표시할지 여부를 설정할 수 있습니다.
`visibleMonths`	끈	한 번에 표시되는 개월 수를 1 또는 2 값으로 제어합니다.
`showWeekNumbers`	끈	달력에서 주 번호 열을 활성화하거나 비활성화합니다.
`open`	부울	일정 선택기가 열려 있는지 여부를 확인합니다.
`keepOpenOnSelect`	부울	날짜를 선택한 후 달력 선택기를 열어 둡니다.
`keepOpenOnOutsideClick`	부울	달력 선택기 바깥쪽을 클릭할 때 달력 선택기를 열어 둡니다.
`weekStart`	끈	주의 시작 요일을 설정합니다.
`hideOutsideDays`	부울	현재 월 보기를 벗어나는 날짜를 숨깁니다.
`hideHeader`	부울	달력 헤더를 숨깁니다(대화 상자 모드에서만 적용 가능).
`headerOrientation`	'vertical' or 'horizontal'	Aligns the calendar header vertically or horizontally (dialog mode only).
`activeDate`	날짜	달력에서 처음에 강조 표시된 날짜를 설정합니다. 설정하지 않으면 현재 날짜가 활성 날짜가 됩니다.

<IgrDateRangePicker orientation='vertical' visibleMonths={1} showWeekNumbers/>

Min & Max

You can also set the min and max properties to restrict user input by disabling calendar dates outside the defined range. These properties act as validators, so even if the user manually types a date outside the range, the IgrDateRangePicker will become invalid.

<IgrDateRangePicker min={new Date('2025-05-06')} max={new Date('2025-05-10')}/>

Custom & Predefined Date Ranges

You can also add custom date range chips to the calendar pop-up for faster range selection using the customRanges property. For example, you can create a custom date range chip to quickly select the range for the upcoming 7 days, ending with the current date. In addition, by setting the usePredefinedRanges property, a set of predefined ranges chips will be displayed along with the custom ones.

const today = new Date();
const nextSeven = new Date(
  today.getFullYear(),
  today.getMonth(),
  today.getDate() + 7
);
const nextWeek: CustomDateRange[] = [
  {
    label: "Next 7 days",
    dateRange: {
      start: today,
      end: nextSeven
    }
  }
];

return (
  <IgrDateRangePicker usePredefinedRanges customRanges={nextWeek} />
);

이제 새로 생성된 "다음 7일" 칩을 클릭하면 캘린더 팝업에서 오늘부터 다음 7일까지 범위가 자동으로 선택됩니다.

Disabled & Special dates

You also have the ability to set disabled dates in the calendar to narrow the range of dates the user can choose from. To set the disabled dates, you can use the disabledDates property.

const dateRangeRef = useRef<IgrDateRangePicker>();
const minDate = new Date(2025, 4, 5);
const maxDate = new Date(2025, 4, 15);
useEffect (() => {
  dateRangeRef.current.disabledDates = [
    {
      type: DateRangeType.Between,
      dateRange: [minDate, maxDate]
    }
  ] as DateRangeDescriptor[];
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

You can see more information about all the possibilities that the disabledDates property offers here: Disabled dates

You can also do the same if you want to set one or more special dates in the calendar; the only difference is that you need to use the specialDates property instead. Special dates

Forms

The IgrDateRangePicker component can also be used seamlessly with the HTML form element. The min, max, and required properties act as form validators.

Additional configuration

Properties

In addition to the properties we've already covered, the IgrDateRangePicker component offers a variety of additional properties that allow you to further configure its behavior.

이름	유형	설명
`disabled`	부울	구성 요소를 비활성화합니다.
`nonEditable`	부울	입력 필드에 입력할 수 없습니다.
`placeholder`	끈	단일 입력 모드에 대한 자리 표시자 텍스트입니다.
`placeholderStart`	끈	시작 날짜 입력에 대한 자리 표시자 텍스트(두 입력 모드).
`placeholderEnd`	끈	종료 날짜 입력에 대한 자리 표시자 텍스트(두 입력 모드).
`outlined`	부울	입력 파트가 재질 테마에서 윤곽선 모양을 갖을지 여부를 결정합니다.
`prompt`	끈	입력 마스크의 채워지지 않은 부분에 사용되는 프롬프트 문자입니다.
`resourceStrings`	IgcDateRangePickerResourceStrings	날짜 범위 선택기 및 달력의 지역화를 위한 리소스 문자열Resource strings for localization of the date-range picker and the calendar.

Slots

You also have the ability to add custom content and modify the appearance of the IgrDateRangePicker component using the available slots.

The prefix and suffix slots allow you to insert custom content before or after the input field (only available in single input mode):

<IgrDateRangePicker>
  <IgrIcon slot='prefix' name='down_arrow_icon'></IgrIcon>
  <IgrIcon slot='suffix' name='upload_icon'></IgrIcon>
</IgrDateRangePicker>

In two inputs mode, you can use the prefix-start, prefix-end, suffix-start, and suffix-end slots instead to target the individual inputs.

Another set of useful slots are clear-icon and calendar-icon, which allow you to customize the icons for the clear and calendar buttons in the input fields:

<IgrDateRangePicker>
  <IgrIcon slot="clear-icon" name="apps_icon"></IgrIcon>
  <IgrIcon slot="calendar-icon" name="bin_icon"></IgrIcon>
</IgrDateRangePicker>

In two inputs mode, you can also customize the default “to” text between the fields by using the separator slot:

<IgrDateRangePicker useTwoInputs>
  <span slot='separator'>till</span>
</IgrDateRangePicker>

The actions slot allows you to insert a custom action button with your own logic. For example, the button below toggles week numbers column in the calendar:

const dateRangeRef = useRef<IgrDateRangePicker>();
const toggleWeekNumbers = () => {
  dateRangeRef.current.showWeekNumbers = !dateRangeRef.current.showWeekNumbers;
};

return (
  <IgrDateRangePicker ref={dateRangeRef}>
    <IgrButton slot="actions" onClick={toggleWeekNumbers}>Toggle Week Numbers</IgrButton>
  </IgrDateRangePicker>
);

In addition to the slots we've already covered, the following slots are also available in the IgrDateRangePicker component:

이름	설명
`title`	일정 제목에 대한 콘텐츠를 렌더링합니다. 대화 상자 모드에서만 적용할 수 있습니다.
`helper-text`	Renders content below the input field(s).
`header-date`	달력 머리글의 기본 현재 날짜/범위 텍스트를 바꿉니다. 대화 상자 모드에서만 적용할 수 있습니다.
`clear-icon-start`	시작 입력에 대한 사용자 지정 지우기 아이콘(두 개의 입력 모드).
`clear-icon-end`	최종 입력에 대한 사용자 지정 지우기 아이콘(두 개의 입력 모드).
`calendar-icon-start`	시작 입력에 대한 사용자 지정 달력 아이콘(두 개의 입력 모드).
`calendar-icon-end`	끝 입력에 대한 사용자 지정 달력 아이콘(두 개의 입력 모드).
`calendar-icon-open`	선택기가 열려 있을 때 표시되는 아이콘 또는 콘텐츠(두 입력 모드의 두 입력에 모두 적용됨).
`calendar-icon-open-start`	시작 입력의 열린 상태에 대한 아이콘 또는 콘텐츠(두 개의 입력 모드).
`calendar-icon-open-end`	끝 입력의 열린 상태에 대한 아이콘 또는 콘텐츠(두 개의 입력 모드).

Methods

In addition to the properties and slots, the IgrDateRangePicker also exposes few methods that you can use:

이름	설명
`show`	달력 선택기 구성 요소를 표시합니다.
`hide`	Hides the calendar picker component.
`toggle`	달력 선택기를 표시된 상태와 숨겨진 상태 사이에서 전환합니다.
`clear`	입력 필드를 지우고 사용자 입력을 제거합니다.
`select`	선택기에서 날짜 범위 값을 선택합니다.
`setCustomValidity`	사용자 지정 유효성 검사 메시지를 설정합니다. 제공된 메시지가 비어 있지 않으면 입력이 유효하지 않은 것으로 표시됩니다.

Styling

Since the IgrDateRangePicker component uses the IgrCalendar component, it also inherits the Calendar's CSS parts, allowing you to style both components seamlessly. You can find the full list of exposed Calendar CSS parts here: Calendar Styling. In addition to the Calendar's CSS parts, the IgrDateRangePicker also exposes some unique CSS parts that you can use to customize its appearance:

이름	설명
`separator`	두 입력 사이의 구분 기호 요소입니다.
`ranges`	사용자 지정 범위와 미리 정의된 범위를 렌더링하는 래퍼입니다.
`label`	대상 입력 위에 콘텐츠를 렌더링하는 레이블 래퍼입니다.
`container`	모든 기본 입력 요소를 보유하는 기본 래퍼입니다.
`input`	기본 입력 요소입니다.
`prefix`	접두사 래퍼.
`suffix`	접미사 래퍼.
`calendar-icon`	닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-start`	시작 입력(두 개의 입력)의 닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-end`	끝 입력(두 개의 입력)의 닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open`	열린 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open-start`	시작 입력(두 개의 입력)의 열린 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open-end`	끝 입력(두 개의 입력)의 열린 상태에 대한 달력 아이콘 래퍼입니다.
`clear-icon`	지우기 아이콘 래퍼(단일 입력).
`clear-icon-start`	시작 입력(두 개의 입력)에 대한 지우기 아이콘 래퍼입니다.
`clear-icon-end`	끝 입력(두 개의 입력)에 대한 지우기 아이콘 래퍼입니다.
`actions`	작업 래퍼.
`helper-text`	대상 입력 아래의 콘텐츠를 렌더링하는 도우미 텍스트 래퍼입니다.

igc-date-range-picker::part(label) {
  color: var(--ig-gray-600);
}

igc-date-range-picker::part(calendar-icon-start),
igc-date-range-picker::part(calendar-icon-end) {
  background-color: var(--ig-primary-500);
  color: var(--ig-primary-500-contrast);
}

igc-date-range-picker::part(calendar-icon-open-start),
igc-date-range-picker::part(calendar-icon-open-end) {
  background-color: var(--ig-primary-700);
  color: var(--ig-primary-700-contrast);
}

igc-date-range-picker::part(clear-icon-start),
igc-date-range-picker::part(clear-icon-end) {
  background-color: var(--ig-error-500);
  color: var(--ig-error-500-contrast);
}

React 날짜 범위 선택기 개요

Date Range Picker Example

시작하기

Usage

Display Date Range Picker

Value

Read-only & Non-editable

Keyboard Navigation

Layout

Label

Format

Calendar Layout and Formatting

Min & Max

Custom & Predefined Date Ranges

Disabled & Special dates

Forms

Additional configuration

Properties

Slots

Methods

Styling

API References

Additional Resources

React 날짜 범위 선택기 개요

Date Range Picker Example

시작하기

Usage

Display Date Range Picker

Value

Read-only & Non-editable

Popup modes

Keyboard Navigation

Layout

Label

Format

Calendar Layout and Formatting

Min & Max

Custom & Predefined Date Ranges

Disabled & Special dates

Forms

Additional configuration

Properties

Slots

Methods

Styling

API References

Additional Resources