Skip to Content

FullCalendar

일정 데이터를 날짜/시간 기준으로 배치하여 표시하는 캘린더 컴포넌트


개요

FullCalendar 컴포넌트는 Toast UI Calendar 기반으로 월/주/일 뷰를 제공합니다. 일정 카드 표시, 뷰 모드 전환, 네비게이션, 기간 선택, 드래그 앤 드롭 등 풍부한 기능을 지원합니다.

주요 특징

  • ✅ 기본 상태: 일정 데이터를 날짜/시간 기준으로 배치하여 표시
  • ✅ 뷰 모드 전환: 월(Month) / 주(Week) / 일(Day) 보기 전환 토글
  • ✅ 월 뷰 표시: 한 화면에 한 달 기준 날짜 그리드
  • ✅ 주 뷰 표시: 시간 축 기반 주 단위 그리드 + 세로 스크롤
  • ✅ 일 뷰 표시: 하루의 시간 단위 일정 집중 표시
  • ✅ 시간 축 표시: 주/일 뷰에서 시간 단위 세로 축
  • ✅ 오늘 날짜 강조: 오늘 날짜/현재 시간 시각적 강조
  • ✅ 일정 카드 표시: 카테고리별 색상 지원
  • ✅ 일정 초과 처리: “더보기” UI
  • ✅ 네비게이션 버튼: 이전/다음/오늘 이동 버튼
  • ✅ 일정 선택: 일정 카드 클릭 시 선택 상태
  • ✅ 기간 선택: 날짜/시간 셀 클릭/드래그로 기간 선택 이벤트
  • ✅ 날짜 표기 현지화: locale로 더보기 팝업 헤더 날짜 표기 지정

프로젝트팀 구현: 일정 상세 호출(Popup/Detail View)은 onEventClick 핸들러를 통해 프로젝트팀이 직접 구현합니다.

뷰를 바꾸면 캘린더를 다시 만듭니다. 캘린더 엔진이 뷰마다 다른 패널 높이를 내부에 쌓아 두고 지우지 않아, 전환을 반복하면 시간 그리드가 짧아집니다. 새로 만들어 그 상태를 남기지 않습니다. 준비될 때까지 감췄다가 표시하므로 빈 화면은 보이지 않습니다.


기본 상태

일정 데이터를 날짜/시간 기준으로 배치하여 표시하는 Calendar 기본 UI를 제공합니다.

September 2026

뷰 모드 전환

월(Month) / 주(Week) / 일(Day) 보기 전환 토글을 제공합니다.

September 2026

월 뷰 표시

한 화면에 한 달 기준 날짜 그리드를 표시합니다.

September 2026

주 뷰 표시 / 시간 축 표시

시간 축 기반의 주 단위 그리드를 표시하고 세로 스크롤을 지원합니다. 주/일 뷰에서 시간 단위를 세로 축으로 표시합니다.

September 2026 Week 3

일 뷰 표시

선택한 하루의 시간 단위 일정만 집중적으로 표시합니다.

September 17, 2026 (Thursday)

오늘 날짜 강조

오늘 날짜 또는 현재 시간을 시각적으로 강조 표시합니다.

September 2026

일정 카드 표시

일정 데이터를 카드 형태로 날짜 또는 시간 셀 내부에 표시합니다. 카테고리별 색상을 지정할 수 있습니다.

September 2026

일정 초과 처리

일정 카드가 셀 영역을 초과하는 경우 일부 숨김 처리 후 “더보기” UI를 제공합니다. 팝업은 화면 경계를 넘지 않게 자리를 잡고, 스크롤하면 닫힙니다.

September 2026

네비게이션 버튼

이전/다음 기간 이동 및 오늘 이동 버튼을 제공합니다.

September 2026

일정 선택

일정 카드 클릭 시 선택 상태로 표시됩니다. onEventClick 핸들러로 선택된 일정 데이터를 전달받습니다.

September 2026

기간 선택

날짜(또는 시간 셀) 클릭/드래그 시 기간 선택 이벤트를 발생시킵니다. 일정 입력 popup 호출 등에 활용합니다.

September 2026 Week 3

빈 칸을 클릭하거나 끌어 보세요


날짜 표기 현지화

locale은 이 컴포넌트가 직접 찍는 날짜 표기(더보기 팝업 헤더)에 쓰입니다. 미지정 시 실행 환경의 표기를 따릅니다.

September 2026

시간대

timezone으로 그리드가 그려지는 시간대를 정합니다. 일정의 절대 시각은 그대로고, 화면에서 놓이는 위치만 바뀝니다. 미지정 시 실행 환경의 시간대를 씁니다.

<FullCalendar events={events} viewMode="week" timezone="America/New_York" timezoneLabel="EST" />

timezoneLabel은 시간 축 왼쪽에 붙는 표기입니다. 생략하면 캘린더가 GMT 오프셋을 계산해 보여 줍니다.


API Reference

Props

PropTypeDefaultDescription
eventsCalendarEvent[][]일정 데이터
calendarsCalendarCategory[]-캘린더 카테고리
restrictionsCalendarRestriction[][]제한 기간 (휴일, 마감 등)
viewMode"month" | "week" | "day""month"현재 뷰 모드
currentDateDatenew Date()현재 표시 날짜
editablebooleanfalse드래그 앤 드롭 활성화
readOnlybooleanfalse읽기 전용 모드
heightstring | number700높이
startDayOfWeek0-60시작 요일 (0: 일요일)
showViewModeTogglebooleantrue뷰 모드 토글 표시
availableViewModesCalendarViewMode[]["day","week","month"]사용 가능 뷰 모드
showNavigationbooleantrue네비게이션 버튼 표시
showTodayButtonbooleantrue오늘 버튼 표시
monthVisibleEventCountnumber4월 뷰 셀당 최대 일정 수
highlightTodaybooleantrue오늘 날짜 강조
showCurrentTimeLinebooleantrue현재 시간 라인 표시
weekStartTimestring"00:00"주/일 뷰 시작 시간
weekEndTimestring"24:00"주/일 뷰 종료 시간
localestring실행 환경 표기날짜 표기 (BCP-47)
timezonestring실행 환경 타임존그리드가 그려지는 시간대 (IANA)
timezoneLabelstring-시간 축에 붙는 표기 (예: KST)
loadingbooleanfalse로딩 오버레이
classNamestring-추가 CSS 클래스

Events

EventTypeDescription
onViewModeChange(mode: CalendarViewMode) => void뷰 모드 변경 시
onDateChange(date: Date) => void날짜 변경 시
onEventClick(event: CalendarEvent) => void일정 클릭 시
onEventDoubleClick(event: CalendarEvent) => void일정 더블클릭 시
onDateSelect(data: CalendarDateSelectData) => void기간 선택 시
onEventChange(data: CalendarEventChangeData) => void일정 드래그/크기조절 완료 시 — changes는 네이티브 Date
onMoreClick(date: Date, events: CalendarEvent[]) => void더보기 클릭 시

CalendarEvent

PropTypeDescription
idstring | number고유 ID
calendarIdstring캘린더 카테고리
titlestring일정 제목
startDate | string시작 시간
endDate | string종료 시간
isAllDayboolean종일 일정 여부
backgroundColorstring배경 색상

기본 사용법

import { FullCalendar, type CalendarEvent, type CalendarCategory, } from "@vortex/ui-foundation" <FullCalendar events={events} calendars={calendars} viewMode="month" height={700} showViewModeToggle showNavigation highlightToday />

접근성

권장 사항

  • ✅ 키보드 네비게이션으로 날짜 이동 가능
  • ✅ 일정 카드에 의미 있는 title 제공
  • ❌ 색상만으로 카테고리를 구분하지 않음 (텍스트 레이블 병행)
Last updated on