RangeDatePickerWithButtons

RangeDatePickerWithButtons 컴포넌트는 날짜 범위를 선택할 수 있는 RangeDatePicker와 기간 버튼이 결합된 컴포넌트입니다.
사용자는 직접 날짜를 선택하거나, 오늘/1주일/1개월 등 미리 정의된 기간 버튼을 클릭하여 손쉽게 날짜 범위를 설정할 수 있습니다.

기본 사용법

import { RangeDatePickerWithButtons } from '@ncds/ui-admin';
import { useState } from 'react';

function App() {
  const [currentButtonId, setCurrentButtonId] = useState<'NONE' | 'TODAY' | 'WEEK' | '1MONTHS' | '1YEAR' | 'ENTIRE'>(
    'TODAY'
  );
  const [startDate, setStartDate] = useState('2025-01-01');
  const [endDate, setEndDate] = useState('2025-01-31');

  return (
    <RangeDatePickerWithButtons
      currentButtonId={currentButtonId}
      setCurrentButtonId={setCurrentButtonId}
      periodKeys={['TODAY', '1WEEK', '1MONTHS', '1YEAR', 'ENTIRE']}
      startDateOptions={{
        currentDate: startDate,
        onChangeDate: setStartDate,
      }}
      endDateOptions={{
        currentDate: endDate,
        onChangeDate: setEndDate,
      }}
    />
  );
}

Props

Prop	Type	필수	Description
currentButtonId	'NONE' \| 'TODAY' \| 'YESTERDAY' \| '3DAYS' \| '7DAYS' \| '1WEEK' \| '15DAYS' \| '1MONTHS' \| '3MONTHS' \| '1YEAR' \| 'ENTIRE'	Yes	현재 선택된 기간 버튼의 ID
setCurrentButtonId	Dispatch<SetStateAction<PeriodKeyType>>	Yes	기간 버튼 ID를 설정하는 함수
periodKeys	PeriodKeyType[]	Yes	표시할 기간 버튼들의 배열
startDateOptions	{ currentDate: string; onChangeDate: (date: string) => void; }	Yes	시작일 관련 옵션
endDateOptions	{ currentDate: string; onChangeDate: (date: string) => void; }	Yes	종료일 관련 옵션
validationOption	{ startDate: string; endDate: string; }	No	날짜 유효성 검사 옵션
onDateValidation	(isValid: boolean) => void	No	날짜 유효성 검사 결과를 처리하는 콜백 함수
buttonGroupSize	'xs' \| 'sm' \| 'md' \| 'lg'	No	기간 버튼 그룹의 크기

buttonGroupSize 예시

buttonGroupSize prop을 사용하여 기간 버튼 그룹의 크기를 조정할 수 있습니다.

Extra Small (xs)

Small (sm) - Default

Medium (md)

Large (lg)

currentButtonId와 setCurrentButtonId 예시

기간 버튼을 클릭하면 currentButtonId가 변경되고, 해당 기간에 맞는 시작일과 종료일이 자동으로 설정됩니다. 날짜를 직접 선택하면 currentButtonId가 'NONE'으로 변경됩니다.

periodKeys 예시

periodKeys 배열에는 사용하고자 하는 기간 버튼의 ID들을 포함해야 합니다. 아래는 다양한 조합의 예시입니다.

사용 가능한 periodKeys 값들:

TODAY: 오늘
YESTERDAY: 어제
3DAYS: 3일
7DAYS: 7일
1WEEK: 1주일
15DAYS: 15일
1MONTHS: 1개월
3MONTHS: 3개월
1YEAR: 1년
ENTIRE: 전체 기간
NONE: 버튼 선택 해제 상태

위 예시에서:

초기 currentButtonId는 'TODAY'로 설정되어 있어 오늘 날짜가 자동으로 선택됩니다.
'1주일' 버튼을 클릭하면 currentButtonId가 '1WEEK'으로 변경되고, 1주일 전 날짜부터 오늘까지가 선택됩니다.
날짜를 직접 선택하면 currentButtonId가 'NONE'으로 변경되어 버튼 선택이 해제됩니다.
'ENTIRE' 버튼을 클릭하면 시작일과 종료일이 모두 비워집니다.

유효성 검사 옵션

validationOption과 onDateValidation을 사용하여 날짜 범위에 대한 유효성 검사를 수행할 수 있습니다.

onDateValidation 콜백

유효성 검사 결과를 받아 처리할 수 있는 콜백 함수입니다.

주의사항

currentButtonId와 setCurrentButtonId는 반드시 함께 사용해야 합니다.
periodKeys 배열에는 사용하고자 하는 기간 버튼의 ID들을 포함해야 합니다.
날짜 선택 시 자동으로 currentButtonId가 'NONE'으로 변경됩니다.
기간 버튼 클릭 시 자동으로 해당 기간의 시작일과 종료일이 설정됩니다.

HTML 버전

DatePickerProps

속성	타입	필수	설명
wrapper	HTMLElement	true	DatePicker가 렌더링될 DOM 요소
buttons	DatePickerButtonOption[]	false	버튼 그룹 옵션
datePickerOptions	DatePickerOption[]	true	DatePicker 설정 옵션 배열

DatePickerButtonOption

속성	타입	필수	설명
text	string	true	버튼 노출 값
period	'days' \| 'weeks' \| 'months' \| 'years'	true	날짜 계산을 위한 기간 값
isCurrent	boolean	true	현재 선택된 버튼 여부

DatePickerOption

속성	타입	필수	설명
element	string	true	DatePicker의 고유 식별자
size	'sm' \| 'md'	true	DatePicker의 크기
options	Options	true	flatpickr 옵션

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css" />
<!-- flatpickr css -->
<link rel="stylesheet" href="https://fe-sdk.cdn-nhncommerce.com/@ncds/ui-admin/1.0/main.min.css" />
<!-- ncds css -->
<script src="https://fe-sdk.cdn-nhncommerce.com/@ncds/ui-admin/1.0/main.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
<!-- flatpickr js -->
<script src="https://npmcdn.com/flatpickr/dist/l10n/ko.js"></script>
<!-- flatpickr locale -->
<script
  src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.30.1/moment.min.js"
  integrity="sha512-hUhvpC5f8cgc04OZb55j0KNGh4eh7dLxd/dPSJ5VyzqDWxsayYbojWyl5Tkcgrmb/RVKCRJI1jNlRbVP4WWC4w=="
  crossorigin="anonymous"
  referrerpolicy="no-referrer"
></script>
<!-- moment js (필요시) -->
<div id="datepicker-container"></div>

<script>
  document.addEventListener('DOMContentLoaded', function () {
    const datePicker = new ncua.DatePicker(document.querySelector('#datepicker-container'), {
      size: 'sm',
      buttons: [
        {
          text: '오늘',
          period: 0,
          unit: 'days',
          isCurrent: true,
        },
        {
          text: '3일',
          period: 3,
          unit: 'days',
          isCurrent: false,
        },
        {
          text: '1주일',
          period: 1,
          unit: 'weeks',
          isCurrent: false,
        },
        {
          text: '1개월',
          period: 1,
          unit: 'months',
          isCurrent: false,
        },
        {
          text: '1년',
          period: 1,
          unit: 'years',
          isCurrent: false,
        },
      ],
      datePickerOptions: [
        {
          element: 'start-date',
          options: {
            mode: 'single',
            static: true,
            dateFormat: 'Y-m-d',
            clickOpens: true,
            allowInvalidPreload: true,
            locale: 'ko',
          },
        },
        {
          element: 'end-date',
          options: {
            mode: 'single',
            static: true,
            dateFormat: 'Y-m-d',
            clickOpens: true,
            allowInvalidPreload: true,
            locale: 'ko',
          },
        },
      ],
    });

    // datepicker 날짜 가져오기
    console.log(datePicker.getDates());

    // datepicker 날짜 설정하기
    datePicker.setDate(['2025-07-01']);
  });
</script>

flatpickr에 대한 자세한 사항은 링크를 참조 부탁드립니다.
moment에 대한 자세한 사항은 링크를 참조 부탁드립니다.

기본 사용법​

Props​

buttonGroupSize 예시​

Extra Small (xs)

Small (sm) - Default

Medium (md)

Large (lg)

Extra Small (xs)

Small (sm) - Default

Medium (md)

Large (lg)

currentButtonId와 setCurrentButtonId 예시​

periodKeys 예시​

유효성 검사 옵션​

onDateValidation 콜백​

주의사항​

HTML 버전​

기본 사용법

Props

buttonGroupSize 예시

currentButtonId와 setCurrentButtonId 예시

periodKeys 예시

유효성 검사 옵션

onDateValidation 콜백

주의사항

HTML 버전