YearPickerInput

YearPickerInput

연, 여러 연, 연 범위를 선택하는 입력 컴포넌트예요.

출처: 문서

본문

YearPicker props

YearPickerInput은 YearPicker의 대부분의 props를 지원해요. 이 페이지에 나열되지 않은 컴포넌트 기능을 확인하려면 YearPicker 문서를 읽어보세요.

사용법 (Usage)

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

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <YearPickerInput
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

여러 날짜 (Multiple dates)

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

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

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

날짜 범위 (Dates range)

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

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

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

사전 설정 (Presets)

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

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

function Demo() {
  return (
    <YearPickerInput
      label="With presets"
      placeholder="Select year"
      defaultValue={new Date()}
      presets={[{
        label: 'This year',
        date: new Date('2026-01-01'),
      }]}
    />
  );
}

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

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

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

  return (
    <YearPickerInput
      type="range"
      label="With presets"
      placeholder="Select years range"
      presets={[
        { label: 'This year', date: [today.startOf('year').toDate(), today.endOf('year').toDate()] },
        { label: 'Last year', date: [today.subtract(1, 'year').startOf('year').toDate(), today.subtract(1, 'year').endOf('year').toDate()] },
      ]}
    />
  );
}

모달에서 피커 열기 (Open picker in modal)

기본적으로 YearPicker는 Popover 안에 렌더링돼요. dropdownType="modal"을 설정하면 Modal로 바꿀 수 있어요.

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

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return <YearPickerInput dropdownType="modal" label="Pick date" placeholder="Pick date" value={value} onChange={setValue} />;
}

값 형식 (Value format)

valueFormat prop으로 값 라벨의 dayjs format을 바꿀 수 있어요.

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

function Demo() {
  return <YearPickerInput valueFormat="YY" label="Pick year" placeholder="Pick year" />;
}

값 포매터 (Value formatter)

valueFormatter는 valueFormat prop보다 더 강력한 대안이에요. 커스텀 함수로 값 라벨을 서식 지정할 수 있어요. 함수는 모든 컴포넌트 타입(default, multiple, range)에 동일해요. 다른 타입을 처리하려면 함수 안에서 추가 검사를 수행해야 해요.

type="multiple"과 함께 커스텀 포매터 함수를 사용하는 예시:

import dayjs from 'dayjs';
import { useState } from 'react';
import { YearPickerInput, DateFormatter } from '@mantine/dates';

const formatter: DateFormatter = ({ type, date, locale, format }) => {
  if (type === 'multiple' && Array.isArray(date)) {
    if (date.length === 1) {
      return dayjs(date[0]).locale(locale).format(format);
    }

    if (date.length > 1) {
      return `${date.length} dates selected`;
    }

    return '';
  }

  return '';
};

function Demo() {
  const [value, setValue] = useState<Date[]>([]);

  return (
    <YearPickerInput
      type="multiple"
      label="Pick 2 dates or more"
      placeholder="Pick 2 dates or more"
      value={value}
      onChange={setValue}
      valueFormatter={formatter}
    />
  );
}

지우기 가능 (Clearable)

clearable prop을 설정하면 오른쪽 섹션에 지우기 버튼을 표시해요. rightSection prop을 설정하면 지우기 버튼이 표시되지 않는다는 점에 주의해요.

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

function Demo() {
  return <YearPickerInput label="Pick date" defaultValue={new Date('2026-01-01')} clearable />;
}

지우기 섹션 모드 (Clear section mode)

clearSectionMode prop은 지우기 버튼과 rightSection이 어떻게 렌더링되는지 결정해요.

• 'both' (기본) – 지우기 버튼과 rightSection 모두 렌더링해요
• 'rightSection' – 사용자가 제공한 rightSection만 렌더링하고 지우기 버튼을 무시해요
• 'clear' – 지우기 버튼만 렌더링하고 rightSection을 무시해요

import { CaretDownIcon } from '@phosphor-icons/react';
import { Stack } from '@mantine/core';
import { YearPickerInput } from '@mantine/dates';

function Demo() {
  return (
    <Stack>
      <YearPickerInput clearable defaultValue={new Date('2026-01-01')} rightSection={<CaretDownIcon size={16} />} clearSectionMode="both" />
      <YearPickerInput clearable defaultValue={new Date('2026-01-01')} rightSection={<CaretDownIcon size={16} />} clearSectionMode="rightSection" />
      <YearPickerInput clearable defaultValue={new Date('2026-01-01')} rightSection={<CaretDownIcon size={16} />} clearSectionMode="clear" />
    </Stack>
  );
}

비활성 상태 (Disabled state)

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

function Demo() {
  return <YearPickerInput label="Disabled" placeholder="Pick year" disabled />;
}

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

minDate와 maxDate props는 선택할 수 있는 최소·최대 날짜를 정의해요. minDate와 maxDate를 Date 객체로 지정할 수 있어요.

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

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  return (
    <YearPickerInput
      label="Pick year"
      placeholder="Pick year"
      value={value}
      onChange={setValue}
      minDate={new Date('2025-01-01')}
      maxDate={new Date('2027-12-31')}
    />
  );
}

컨트롤 props (Control props)

getYearControlProps prop으로 날짜에 기반해 컨트롤 컴포넌트에 props를 전달할 수 있어요. 특정 날짜를 비활성화하거나 스타일/className을 커스터마이즈하는 데 유용해요.

import dayjs from 'dayjs';
import { useState } from 'react';
import { YearPickerInput, YearPickerInputProps } from '@mantine/dates';

const getYearControlProps: YearPickerInputProps['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 {};
};

연 라벨 형식 (Year label format)

yearsListFormat props로 연 목록의 연 라벨 형식을 바꿀 수 있어요. dayjs format string을 받아요.

십년 라벨 형식 (Decade label format)

decadeLabelFormat prop으로 헤더의 십년(decade) 라벨 형식을 바꿀 수 있어요. dayjs format string을 받아요.

Input props

YearPickerInput 컴포넌트는 Input과 Input.Wrapper 컴포넌트의 기능과 모든 button 요소 props를 지원해요. YearPickerInput 문서에는 컴포넌트가 지원하는 모든 기능이 포함되어 있지 않아요. 사용 가능한 모든 기능은 Input 문서에서 확인할 수 있어요.

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

function Demo() {
  return <YearPickerInput label="Pick date *" placeholder="Pick date" description="Input description" error="Input error" />;
}

아이콘 포함 (With icon)

import { useState } from 'react';
import { CalendarBlankIcon } from '@phosphor-icons/react';
import { YearPickerInput } from '@mantine/dates';

function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  const icon = <CalendarBlankIcon size={16} />;
  return (
    <YearPickerInput
      leftSection={icon}
      leftSectionPointerEvents="none"
      label="Pick date"
      placeholder="Pick date"
      value={value}
      onChange={setValue}
    />
  );
}

요소 ref 가져오기 (Get element ref)

import { useRef } from 'react';
import { YearPickerInput } from '@mantine/dates';

function Demo() {
  const ref = useRef<HTMLButtonElement>(null);
  return <YearPickerInput ref={ref} />;
}

접근성 (Accessibility)

YearPickerInput을 label prop 없이 사용하면 화면 판독기가 제대로 알려주지 못해요. aria-label을 설정하면 라벨이 보이지 않아도 화면 판독기가 알려줘요. label prop을 설정하면 별도로 aria-label을 지정할 필요 없이 접근성이 확보돼요.

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

function Demo() {
  return <YearPickerInput aria-label="Pick a year" />;
}

더 알아보기 (Learn more)

• YearPicker
• TimeInput
• Input