YearPicker

YearPicker

인라인(inline) 연, 여러 연, 연 범위를 선택하는 피커 컴포넌트예요.

출처: 문서

본문

사용법 (Usage)

YearPicker로 단일 연, 여러 연, 연 범위를 인라인으로 선택할 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker value={value} onChange={setValue} />;
}

선택 해제 허용 (Allow deselect)

allowDeselect를 설정하면 사용자가 현재 선택된 날짜를 클릭해 선택을 해제할 수 있어요. allowDeselect는 type prop이 range 또는 multiple일 때 무시돼요. 날짜가 선택 해제되면 onChange가 null로 호출돼요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker value={value} onChange={setValue} allowDeselect />;
}

여러 날짜 (Multiple dates)

type="multiple"을 설정하면 사용자가 여러 날짜를 선택할 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date[]>([]);
  return <YearPicker type="multiple" value={value} onChange={setValue} />;
}

날짜 범위 (Dates range)

type="range"를 설정하면 사용자가 날짜 범위를 선택할 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return <YearPicker type="range" value={value} onChange={setValue} />;
}

범위에서 단일 날짜 (Single date in range)

기본적으로 범위로 단일 날짜를 선택하는 것은 허용되지 않아요. 사용자가 같은 날짜를 두 번째로 클릭하면 선택이 해제돼요. 이 동작을 바꾸려면 allowSingleDateInRange prop을 설정해요. allowSingleDateInRange는 type prop이 range가 아닐 때 무시돼요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return <YearPicker type="range" allowSingleDateInRange value={value} onChange={setValue} />;
}

사전 설정 (Presets)

presets prop으로 커스텀 연 사전 설정을 추가할 수 있어요. 사전 설정은 캘린더 옆에 표시돼요.

import dayjs from 'dayjs';
import { YearPicker } from '@mantine/dates';

function Demo() {
  return (
    <YearPicker
      presets={[
        { label: 'This year', date: new Date() },
        { label: 'Next year', date: dayjs().add(1, 'year').toDate() },
        { label: 'Last year', date: dayjs().subtract(1, 'year').toDate() },
        { label: 'In 5 years', date: dayjs().add(5, 'year').toDate() },
        { label: '5 years ago', date: dayjs().subtract(5, 'year').toDate() },
      ]}
    />
  );
}

type="range"와 함께 presets를 사용하려면 값을 두 날짜의 튜플로 정의해요.

import dayjs from 'dayjs';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const today = dayjs();

  return (
    <YearPicker
      type="range"
      presets={[
        { label: 'Last 2 years', date: [today.subtract(2, 'year').toDate(), today.toDate()] },
        { label: 'Last 5 years', date: [today.subtract(5, 'year').toDate(), today.toDate()] },
        { label: 'Next 5 years', date: [today.toDate(), today.add(5, 'year').toDate()] },
        { label: 'Last decade', date: [today.subtract(10, 'year').toDate(), today.toDate()] },
      ]}
    />
  );
}

기본 날짜 (Default date)

defaultDate prop으로 처음에 어떤 십년(decade)을 표시할지 결정하는 날짜 값을 설정할 수 있어요. 예를 들어 2040 – 2049 십년을 표시하려면 defaultDate={new Date(2040, 1)}을 설정해요. 값을 지정하지 않으면 defaultDate는 new Date()를 사용해요. 제공된 날짜 객체에서 월, 일, 분, 초는 무시되고 연만 사용돼요. 어떤 날짜 값이든 지정할 수 있어요.

date prop을 설정하면 defaultDate 값은 무시된다는 점에 주의해요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker defaultDate={new Date(2040, 1)} value={value} onChange={setValue} />;
}

제어된 날짜 (Controlled date)

date와 onDateChange props를 설정하면 현재 표시되는 십년(decade)을 제어할 수 있어요. 이렇게 하면 날짜 선택 경험을 커스터마이즈할 수 있어요. 예를 들어 사용자가 범위에서 첫 날짜를 선택하면 현재 날짜 값에 20년을 더할 수 있어요.

import dayjs from 'dayjs';
import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<[string | null, string | null]>([null, null]);
  const [date, setDate] = useState(dayjs().format('YYYY-MM-DD'));

  const handleChange = (val: [string | null, string | null]) => {
    if (val[0] !== null && val[1] === null) {
      setDate((current) => dayjs(current).add(20, 'year').format('YYYY-MM-DD'));
    }

    setValue(val);
  };

  return <YearPicker type="range" date={date} onDateChange={setDate} value={value} onChange={handleChange} />;
}

최소·최대 날짜 (Min and max date)

minDate와 maxDate props로 최소·최대 날짜를 정의할 수 있어요. 이전/다음 페이지를 사용할 수 없으면 해당 컨트롤이 비활성화돼요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker minDate={new Date('2020-01-01')} maxDate={new Date('2029-12-31')} value={value} onChange={setValue} />;
}

연 컨트롤에 props 추가 (Add props to year control)

getYearControlProps 함수로 연 컨트롤에 props를 추가할 수 있어요. 연 날짜를 단일 인자로 받아요. 함수에서 반환된 props가 연 컨트롤에 추가돼요. 예를 들어 특정 컨트롤을 비활성화하거나 스타일을 추가하는 데 사용할 수 있어요.

import dayjs from 'dayjs';
import { useState } from 'react';
import { YearPicker, YearPickerProps } from '@mantine/dates';

const getYearControlProps: YearPickerProps['getYearControlProps'] = (date) => {
  if (dayjs(date).year() === new Date().getFullYear()) {
    return { style: { color: 'var(--mantine-color-blue-filled)', fontWeight: 700 } };
  }

  if (dayjs(date).year() === new Date().getFullYear() + 1) {
    return { disabled: true };
  }

  return {};
};

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker getYearControlProps={getYearControlProps} value={value} onChange={setValue} />;
}

열 수 (Number of columns)

numberOfColumns prop을 설정해 나란히 렌더링할 피커 수를 정의할 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null]>([null, null]);
  return <YearPicker type="range" numberOfColumns={2} value={value} onChange={setValue} />;
}

전체 너비 (Full width)

fullWidth prop을 설정하면 연 피커가 부모 컨테이너 너비의 100%를 채우도록 늘어나요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker fullWidth value={value} onChange={setValue} />;
}

크기 (Size)

import dayjs from 'dayjs';
import { YearPicker } from '@mantine/dates';

function Demo() {
  return <YearPicker size="lg" />;
}

연 컨트롤 형식 변경 (Change year controls format)

yearsListFormat을 사용해 연 컨트롤의 dayjs format을 바꿀 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker yearsListFormat="YY" value={value} onChange={setValue} />;
}

십년 라벨 형식 변경 (Change decade label format)

decadeLabelFormat을 사용해 십년(decade) 라벨의 dayjs format을 바꿀 수 있어요.

import { useState } from 'react';
import { YearPicker } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPicker decadeLabelFormat="YY" value={value} onChange={setValue} />;
}

접근성 (Accessibility)

ariaLabels prop으로 이전/다음 컨트롤의 aria-label 속성을 지정할 수 있어요.

import { YearPicker } from '@mantine/dates';

function Demo() {
  return (
    <YearPicker
      ariaLabels={{
        nextDecade: 'Next decade',
        previousDecade: 'Previous decade',
      }}
    />
  );
}

getYearControlProps를 사용해 aria-label 속성을 커스터마이즈할 수 있어요.

import { YearPicker } from '@mantine/dates';

function Demo() {
  return (
    <YearPicker
      getYearControlProps={(date) => ({
        'aria-label': `Select year ${date.getFullYear()}`,
      })}
    />
  );
}

다음 이벤트는 포커스가 연 컨트롤에 있을 때만 트리거된다는 점에 주의해요.

키 (Key)	설명 (Description)
ArrowRight	다음 비활성 연에 포커스를 둬요
ArrowLeft	이전 비활성 연에 포커스를 둬요
ArrowDown	같은 열의 다음 비활성 연에 포커스를 둬요
ArrowUp	같은 열의 이전 비활성 연에 포커스를 둬요

더 알아보기 (Learn more)

• MonthPickerInput
• YearPickerInput
• Getting started