React Week Picker Pro 📅


> A modern, lightweight React component for selecting weeks with comprehensive features and zero dependencies.

✨ Features

- 🗓️ Week-only selection - Select entire weeks, not individual days
- 📊 ISO Week numbers - Standards-compliant week numbering system
- 📅 Date range display - Shows selected week's start and end dates
- 🚫 Date restrictions - Min/max date constraints support
- 🌍 Flexible configuration - Sunday or Monday week start
- 🎨 Custom formatting - Configurable date display formats
- 📱 Mobile responsive - Perfect on all screen sizes
- ♿ Accessible - WCAG compliant with keyboard navigation
- 🎯 Lightweight - Under 6KB gzipped
- 📦 Tree-shakeable - Import only what you need
- 💪 TypeScript ready - Full type definitions included
- ⚡ Vite powered - Modern build system
- 🎨 Customizable styling - Easy to theme and customize

🚀 Installation

``bash
npm install react-week-picker-pro prop-types
`

Or with yarn:

`bash
yarn add react-week-picker-pro prop-types
`

Note: prop-types is a peer dependency.

📖 Quick Start

`jsx
import React, { useState } from 'react';
import WeekPicker from 'react-week-picker-pro';
import 'react-week-picker-pro/dist/style.css';

function App() {
const [selectedWeek, setSelectedWeek] = useState();

const handleWeekSelect = (weekStart, weekEnd, weekNumber) => {
setSelectedWeek(weekStart);
console.log(Selected Week ${weekNumber}: ${weekStart.toDateString()} - ${weekEnd.toDateString()});
};

return (

Select a Week

selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
/>

);
}

export default App;
`

🎯 Live Demo

Check out the interactive demo to see all features in action!

📋 API Reference

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| selectedWeek | Date | undefined | Currently selected week |
| onWeekSelect | function | undefined | Callback when a week is selected |
| minDate | Date | undefined | Minimum selectable date |
| maxDate | Date | undefined | Maximum selectable date |
| className | string | '' | Additional CSS class name |
| dateFormat | string | 'MMM dd, yyyy' | Date format for display |
| showWeekNumbers | boolean | true | Whether to show week numbers |
| firstDayOfWeek | 0 \| 1 | 1 | First day of week (0=Sunday, 1=Monday) |

$3

The onWeekSelect callback receives three parameters:

`jsx
const handleWeekSelect = (weekStart, weekEnd, weekNumber) => {
// weekStart: Date - Start of the selected week
// weekEnd: Date - End of the selected week
// weekNumber: number - ISO week number
};
`

🎨 Examples

$3

`jsx
import WeekPicker from 'react-week-picker-pro';
import 'react-week-picker-pro/dist/style.css';

selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
/>
`

$3

`jsx
selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
minDate={new Date(2024, 0, 1)} // From Jan 1, 2024
maxDate={new Date(2024, 11, 31)} // Until Dec 31, 2024
/>
`

$3

`jsx
selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
dateFormat="yyyy-MM-dd" // ISO format
/>
`

$3

`jsx
selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
firstDayOfWeek={0} // Sunday first
/>
`

$3

`jsx
selectedWeek={selectedWeek}
onWeekSelect={handleWeekSelect}
showWeekNumbers={false}
/>
`

$3

`jsx
const [selectedWeek, setSelectedWeek] = useState();

const selectCurrentWeek = () => {
setSelectedWeek(new Date());
};

const clearSelection = () => {
setSelectedWeek(undefined);
};

return (

Select This Week
Clear
selectedWeek={selectedWeek}
onWeekSelect={(start) => setSelectedWeek(start)}
/>

);
`

🛠️ Utility Functions

The library also exports useful utility functions:

`jsx
import {
getISOWeekNumber,
getWeekStart,
getWeekEnd,
formatDate,
isSameWeek
} from 'react-week-picker-pro';

// Get ISO week number for any date
const weekNum = getISOWeekNumber(new Date()); // e.g., 27

// Get week boundaries
const weekStart = getWeekStart(new Date(), 1); // Monday first
const weekEnd = getWeekEnd(new Date(), 1);

// Format dates
const formatted = formatDate(new Date(), 'yyyy-MM-dd'); // "2025-07-07"

// Compare weeks
const sameWeek = isSameWeek(date1, date2, 1); // boolean
`

🎨 Styling & Customization

$3

The component uses BEM-style CSS classes for easy customization:

`css
.week-picker { / Main container / }
.week-picker__header { / Month/year header / }
.week-picker__nav-button { / Navigation buttons / }
.week-picker__calendar { / Calendar grid / }
.week-picker__week-row { / Week rows / }
.week-picker__week-row--selected { / Selected week / }
.week-picker__day { / Individual days / }
.week-picker__day--today { / Today highlight / }
`

$3

`css
/ Custom theme /
.week-picker {
--primary-color: #3b82f6;
--selected-bg: #dbeafe;
--hover-bg: #f9fafb;
}

.week-picker__week-row--selected {
background: var(--selected-bg);
border-color: var(--primary-color);
}

.week-picker__nav-button:hover {
background: var(--hover-bg);
}
`

$3

The component includes built-in dark mode support via CSS media queries:

`css
@media (prefers-color-scheme: dark) {
.week-picker {
background: #1f2937;
color: #f9fafb;
}
}
`

📱 Responsive Design

The component is fully responsive and adapts to different screen sizes:

- Desktop: Full-featured layout with hover effects
- Tablet: Optimized spacing and touch targets
- Mobile: Compact layout with larger touch areas

♿ Accessibility

- Keyboard Navigation: Full keyboard support
- Screen Readers: ARIA labels and semantic HTML
- Focus Management: Clear focus indicators
- WCAG Compliance: Meets accessibility standards

$3

- Arrow Keys: Navigate between months
- Enter/Space: Select week
- Tab: Navigate between interactive elements

🌐 Browser Support

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+

📦 Bundle Size

- Minified: ~8KB
- Gzipped: ~3KB
- Zero dependencies (except peer dependencies)

🧪 Testing

The library includes comprehensive tests:

`bash

Run tests

npm test

Run tests with coverage

npm run test:coverage

Run tests in watch mode

npm run test:watch
`

🔧 Development

$3

- Node.js 18+
- npm or yarn

$3

`bash

Clone the repository

git clone https://github.com/Developer-Nijat/react-week-picker-pro.git
cd react-week-picker-pro

Install dependencies

npm install

Start development server

npm run dev

Build library

npm run build

Run tests

npm test
`

$3

`
react-week-picker-pro/
├── lib/ # Library source code
│ ├── components/ # React components
│ ├── utils/ # Utility functions
│ └── styles/ # CSS styles
├── src/ # Demo application
├── tests/ # Test files
├── dist/ # Built library
└── docs/ # Documentation
``

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

$3

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Ensure all tests pass
6. Submit a pull request

📝 Changelog

See CHANGELOG.md for a detailed list of changes.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Nijat Aliyev
- GitHub: Developer-Nijat
- npm: developer.nijat

🙏 Acknowledgments

- Built with Vite for lightning-fast development
- Styled with modern CSS for beautiful, accessible design
- Tested with Vitest for reliable functionality
- Inspired by modern date picker libraries

🔗 Related Projects

- react-datepicker - Full date picker
- react-day-picker - Flexible date picker
- react-calendar - Calendar component

---