MonthPickerInput

MonthPickerInput

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

출처: 문서

본문

MonthPicker props

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

사용법 (Usage)

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

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

여러 날짜 (Multiple dates)

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

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

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

날짜 범위 (Dates range)

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

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

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

사전 설정 (Presets)

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

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

function Demo() {
  return (
    <MonthPickerInput
      label="With presets"
      placeholder="Select month"
      defaultValue={new Date()}
      presets={[
        { label: 'This month', date: new Date() },
        { label: 'Next month', date: dayjs().add(1, 'month').toDate() },
        { label: 'Next year', date: dayjs().add(1, 'year').toDate() },
      ]}
    />
  );
}

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

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

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

  return (
    <MonthPickerInput
      type="range"
      label="With presets"
      placeholder="Select months 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)

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

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

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

값 형식 (Value format)

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

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

function Demo() {
  return <MonthPickerInput valueFormat="MM/YYYY" label="Pick month" placeholder="Pick month" />;
}

값 포매터 (Value formatter)

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

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

import dayjs from 'dayjs';
import { useState } from 'react';
import { MonthPickerInput, 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 (
    <MonthPickerInput
      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 { MonthPickerInput } from '@mantine/dates';

function Demo() {
  return <MonthPickerInput label="Pick date" defaultValue={new Date()} 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 { MonthPickerInput } from '@mantine/dates';

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

비활성 상태 (Disabled state)

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

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

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

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

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

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

컨트롤 props (Control props)

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

import dayjs from 'dayjs';
import { useState } from 'react';
import { MonthPickerInput, MonthPickerInputProps } from '@mantine/dates';

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

const getMonthControlProps: MonthPickerInputProps['getMonthControlProps'] = (date) => {
  if (dayjs(date).month() === 1) {
    return { style: { color: 'var(--mantine-color-blue-filled)', fontWeight: 700 } };
  }

  if (dayjs(date).month() === 5) {
    return { disabled: true };
  }

  return {};
};

라벨 형식 (Label format)

decadeLabelFormat과 yearLabelFormat props로 헤더의 라벨 형식을 바꿀 수 있어요. 이 props는 dayjs format string을 받아요.

목록 형식 (List format)

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

최대 레벨 (Max level)

maxLevel prop으로 헤더의 라벨을 클릭해 도달할 수 있는 최대 레벨을 설정할 수 있어요.

Input props

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

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

function Demo() {
  return <MonthPickerInput 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 { MonthPickerInput } from '@mantine/dates';

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

네이티브 레벨 선택 (Native level select)

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

function Demo() {
  return <MonthPickerInput label="Pick month" placeholder="Pick month" withNativeLevelSelect />;
}

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

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

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

접근성 (Accessibility)

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

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

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

더 알아보기 (Learn more)

• MonthPicker
• YearPicker
• Input