Calendar

Overview

The Calendar component displays a month grid where users can select dates, navigate between months, view event indicators, inspect availability, or choose date ranges. It is a core building block for time-aware interfaces across the Byteion ecosystem.

Calendar is commonly used in booking dashboards, appointment scheduling, event management, ERP attendance, POS reservations, ecommerce delivery date selection, admin reporting date filters, and internal scheduling tools.

Calendar excels when users need spatial understanding of dates within a month. For simple one-field date input, the Date Picker may be a better fit.

What this component includes

• Month heading with year
• Previous / next month controls
• Weekday header row
• 7-column date grid
• Day buttons with select interaction
• Today state highlight
• Selected date highlight
• Outside-month date styling
• Disabled / unavailable date state
• Event indicator pills inside day cells
• Range selection states (start, middle, end)
• Optional multi-date selection
• Compact day-picker variant for popovers
• Custom day rendering via renderDay prop (React only)

Use cases

When to use

Use Calendar when:

• users need to see dates in month context
• users need to choose from available / unavailable dates
• users need to view events or attendance by day
• users need range or multi-date selection
• users need to navigate month by month

When not to use

• users only need to type or pick one date quickly — use Date Picker
• users need a chronological event feed — use Timeline or List
• users need dense records — use Data Table
• users need time slots more than dates — use a scheduler or time picker if available
• mobile space is too limited and a simpler input suffices

Basic example

Month grid with navigation, weekday headers, selectable day buttons, today highlight, selected date, outside-month dates, disabled date, and an event indicator. All classes use Byteion semantic tokens.

import { Calendar } from '@byteion/react';

export default function CalendarDemo() {
  return (
    <Calendar
      month={5}
      year={2026}
      selected="2026-06-15"
      events={[
        { date: '2026-06-15', label: 'Team standup', tone: 'primary' },
      ]}
    />
  );
}

<script setup lang="ts">
import { Calendar } from '@byteion/vue';
</script>

<template>
  <Calendar
    :month="5"
    :year="2026"
    selected="2026-06-15"
    :events="[{ date: '2026-06-15', label: 'Team standup', tone: 'primary' }]"
  />
</template>

Advanced example

Extended month grid showing today highlight, selected date, event dots, multiple event counts, unavailable date, and date range start / middle / end states.

import { Calendar } from '@byteion/react';

export default function AdvancedCalendarDemo() {
  return (
    <Calendar
      month={5}
      year={2026}
      selected="2026-06-15"
      events={[
        { date: '2026-06-15', label: 'Team standup',  tone: 'primary' },
        { date: '2026-06-20', label: 'Design review', tone: 'success' },
        { date: '2026-06-20', label: 'Sprint retro',  tone: 'warning' },
      ]}
    />
  );
}

<script setup lang="ts">
import { Calendar } from '@byteion/vue';
</script>

<template>
  <Calendar
    :month="5"
    :year="2026"
    selected="2026-06-15"
    :events="[
      { date: '2026-06-15', label: 'Team standup',  tone: 'primary' },
      { date: '2026-06-20', label: 'Design review', tone: 'success' },
      { date: '2026-06-20', label: 'Sprint retro',  tone: 'warning' },
    ]"
  />
</template>

React example

Interactive React calendar with useState for current month, selected date, and event data. Uses the real <Calendar> component from @byteion/react.

import { useState } from 'react';
import { Calendar } from '@byteion/react';

const EVENTS = [
  { date: '2026-06-15', label: 'Team standup',  tone: 'primary' as const },
  { date: '2026-06-26', label: 'Design review', tone: 'success' as const },
  { date: '2026-06-26', label: 'Sprint retro',  tone: 'warning' as const },
];

export default function CalendarExample() {
  const [month, setMonth] = useState(5); // June
  const [year, setYear] = useState(2026);
  const [selected, setSelected] = useState('2026-06-15');

  return (
    <Calendar
      month={month}
      year={year}
      selected={selected}
      events={EVENTS}
      onMonthChange={(m, y) => { setMonth(m); setYear(y); }}
      onSelect={(date) => setSelected(date)}
    />
  );
}

Vue example

Interactive Vue 3 calendar using ref for current month, selected date, and events. Uses the real <Calendar> component from @byteion/vue.

<script setup lang="ts">
import { ref } from 'vue';
import { Calendar, type CalendarEvent } from '@byteion/vue';

const month = ref(5);
const year = ref(2026);
const selected = ref('2026-06-15');
const events = ref<CalendarEvent[]>([
  { date: '2026-06-15', label: 'Team standup',  tone: 'primary' },
  { date: '2026-06-26', label: 'Design review', tone: 'success' },
  { date: '2026-06-26', label: 'Sprint retro',  tone: 'warning' },
]);

function onMonthChange(m: number, y: number) {
  month.value = m;
  year.value = y;
}

function onSelect(date: string | null) {
  selected.value = date;
}
</script>

<template>
  <Calendar
    v-model:month="month"
    v-model:year="year"
    v-model:selected="selected"
    :events="events"
    @monthChange="onMonthChange"
    @select="onSelect"
  />
</template>

Anatomy

Date states

Each day in the calendar grid can display one of the following states:

Event indicators

The Calendar renders event indicators as pills inside day cells. Events are passed as an array of CalendarEvent objects with a date, label, and optional tone.

• Use a single pill when one event exists on a date.
• Stack multiple pills when multiple events exist on the same date.
• Choose tone to communicate event type: primary, success, warning, danger, violet, or neutral.
• On mobile, consider showing event details below the grid after a date is selected instead of inside cells.
• Do not rely on color alone — ensure event labels are readable text.
• Keep event colors token-based for theme consistency.

Selection modes

Month navigation

• Previous / next month buttons update the visible month. The Calendar handles this internally.
• An optional month/year picker can be added for jumping to a specific month faster.
• Preserve the selected date when possible — only clear it if the date no longer exists in the new month.
• Keep keyboard focus predictable after month change. Focus should return to the new month's grid or the selected date.
• Disable navigation buttons when min/max date limits are reached (e.g., cannot go before January 2020).

Accessibility

Calendar accessibility is more complex than basic buttons. Follow these guidelines:

• Use semantic <button> elements for each date, or implement a proper ARIA grid pattern if arrow-key navigation is supported.
• Provide visible focus states on all interactive elements.
• Previous / next buttons need accessible labels: aria-label="Previous month" and aria-label="Next month".
• The month heading (<h3>) should be readable by screen readers without extra markup.
• Day buttons need descriptive labels: e.g. aria-label="Select June 15, 2026".
• Today's date should use aria-current="date".
• The selected date should be announced — use aria-selected="true" when using a grid pattern, or clear visible state when using plain buttons.
• Disabled dates should use the disabled attribute so they are skipped in tab order.
• Event indicators need accessible text, not colour-only dots. Use the event label text.
• If arrow-key navigation is implemented: arrow keys move between days, Home/End to start/end of week, PageUp/PageDown to change months.
• Enter or Space should select the focused date.
• Keep focus predictable after month navigation — return focus to the same day number or the selected date.

Responsive behavior

• Calendar should fit narrow mobile screens — use a max-width container.
• On mobile, consider reducing day cell height (min-h-[48px] instead of min-h-[96px]).
• Avoid tiny hit targets — keep date buttons at least 44x44px touch-friendly.
• Show event details below the grid on mobile instead of inside cells.
• Avoid horizontal overflow — the 7-column grid naturally fits within 100% width.
• For complex scheduling on mobile, consider offering a list view alternative or a compact day-picker variant.

Date and timezone guidance

• For date-only selection, store normalized date strings such as YYYY-MM-DD.
• Avoid mixing date-only values with timezone-aware timestamps in the same field.
• Use one consistent date strategy across the UI — either all local dates or all UTC-based dates.
• Convert timezone-aware values at API boundaries, not in the calendar component.
• Test month boundaries, daylight saving changes, and users in different timezones.
• For booking and event systems, backend availability rules remain the source of truth — the UI is a reflection, not the authority.

Validation and constraints

Best practices

Developer tips

Related

• Date Picker — single-date input with dropdown calendar
• Input — text field for manual date entry
• Button — used in calendar navigation and Today action
• Badge — event indicator styling
• Popover — calendar dropdown container
• Card — calendar surface background
• Form Field — date selection within forms
• Alert — validation messages for date errors
• Timeline — chronological event feed alternative
• Spinner — loading state for availability
• Skeleton — placeholder for calendar loading

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX