Month Navigator
View in Storybook
Explore interactive examples and all component variations in our Storybook.
The MonthNavigator component provides an intuitive interface for navigating between months and years. Built with accessibility in mind, it offers both month-by-month and year-by-year navigation modes. Perfect for calendar interfaces, date pickers, scheduling applications, and any interface that requires temporal navigation.
Basic Usage
January
2026
Year Navigation Mode
Calendar Integration
Date Range Selection
Localization Support
English (Default)
January
2026
💡 The MonthNavigator supports all date-fns locales. Import your desired locale and pass it to the locale prop for internationalization.
Different Navigation Modes
Properties
MonthNavigator
| Property | Type | Default | Description |
|---|---|---|---|
currentMonth | Month | - | The currently selected month (0-11). |
currentYear | number | - | The currently selected year. |
onChangeMonthYear | (month: Month, year: number) => void | - | Callback fired when the month or year changes. |
mode | 'month' | 'year' | 'month' | Navigation mode - month-by-month or year-by-year. |
locale | Locale | enUS | Date-fns locale for internationalization. |
Month Type
type Month = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
Represents months as zero-indexed numbers (0 = January, 11 = December).
Navigation Behavior
Month Mode
- Previous: Decrements month, wraps to December of previous year when at January
- Next: Increments month, wraps to January of next year when at December
- Display: Shows full month name and year
Year Mode
- Previous: Decrements year by 1, month stays constant
- Next: Increments year by 1, month stays constant
- Display: Shows only the year value
Accessibility
The MonthNavigator component includes comprehensive accessibility features:
- Keyboard Navigation - Arrow keys and Enter/Space for button activation
- Screen Reader Support - Proper ARIA labels describing navigation actions
- Focus Management - Clear focus indicators on navigation buttons
- Semantic HTML - Uses proper button elements with descriptive labels
- High Contrast - Supports high contrast mode and custom themes
- Reduced Motion - Respects user's motion preferences
Common Use Cases
The MonthNavigator component is perfect for:
- Calendar Interfaces - Navigate between months in calendar views
- Date Pickers - Provide month/year selection in date picker components
- Scheduling Applications - Navigate time periods for appointments and events
- Reporting Dashboards - Select time periods for data visualization
- Content Archives - Browse content by month and year
- Event Planning - Navigate dates for event scheduling
- Financial Applications - Select periods for financial reports
- Analytics Tools - Choose time ranges for data analysis
Best Practices
- State Management - Always use controlled state for month and year values
- Validation - Validate month/year combinations for your use case
- Localization - Use appropriate date-fns locale for your target audience
- Mode Selection - Choose the right navigation mode for your use case
- Visual Integration - Style the navigator to match your application's design
- Responsive Design - Ensure the navigator works well on mobile devices
- Accessibility - Test with screen readers and keyboard navigation
- Performance - Memoize callback functions to prevent unnecessary re-renders