use-lilius

use-lilius is a headless calendar hook for React. Because it is headless, it provides the logic and state management for a calendar without providing any UI components. You are responsible for rendering the calendar using your own components and styling.

For detailed API documentation, refer to the API docs. For visual examples of how to implement the hook with UI libraries like Chakra UI, visit the use-lilius Storybook.

To use use-lilius in your React project, install the package using yarn:

yarn add use-lilius

The MultiSelect component is a datepicker implementation that allows for selecting multiple dates, built using Chakra UI. It is available as a standalone component within the examples/datepicker directory.

import { MultiSelect } from "./multi-select";

// Usage in a component
<MultiSelect />

You can implement a single-select datepicker by using the SingleSelect component. This component is built using Chakra UI as its styling foundation. In a Storybook environment, it can be rendered as a standalone story to demonstrate its single-selection functionality.

import { SingleSelect } from "./single-select";

// Usage in a component or story
<SingleSelect />

The RangeSelect component is a datepicker implementation designed for selecting a range of dates, built using Chakra UI. It is provided as an example of how to compose use-lilius logic with UI frameworks like Chakra.

import { RangeSelect } from "./range-select";

// Usage in a component
<RangeSelect />

The Returns interface provides access to the current state of the calendar. Use these properties to render the calendar UI and track user selections:

• calendar: A Date[][][] matrix representing the days based on the current viewing date. This is the primary data structure for rendering the calendar grid.
• selected: An array of Date objects representing the currently selected dates.
• viewing: The Date object representing the current view. Note that only the month and year components of this date are used to determine the calendar matrix.
• setSelected: A React state dispatcher to manually override the selected dates.
• setViewing: A React state dispatcher to manually set the viewing date. Only the month and year of the provided date are used.

The Returns interface includes helper methods for date logic:

• clearTime(date): Returns a copy of the provided Date with the time component reset to 00:00:00:00.
• inRange(date, min, max): Returns true if the date falls between min and max (inclusive).

When initializing useLilius, you can provide an optional Options object to customize the calendar's behavior, including how many months are displayed, which dates are pre-selected, the initial view, and the start of the week. All properties are optional and have default values.

const options: Options = {
  numberOfMonths: 2,
  selected: [new Date()],
  viewing: new Date(),
  weekStartsOn: Day.MONDAY
};

Use these methods to change the month or year currently being displayed in the calendar matrix:

• viewToday(): Sets the viewing date to today.
• viewMonth(month): Sets the viewing date to a specific Month enum value.
• viewYear(year): Sets the viewing date to a specific year (e.g., 2024).
• viewNextMonth(): Advances the view to the next month.
• viewPreviousMonth(): Moves the view to the previous month.
• viewNextYear(): Advances the view to the next year.
• viewPreviousYear(): Moves the view to the previous year.

The useLilius function is the primary entry point for the library. It accepts an optional Options object and returns a Returns object containing the tools needed to manage date/time logic within a component.

Refer to the Options interface for available configuration parameters and the Returns interface to understand the available utility methods and state provided by the hook.

// Basic usage pattern
const { /* values from Returns interface */ } = useLilius(options);

When calling useLilius, you can provide an Options object to customize the initial state and behavior:

• weekStartsOn: Defines which day a week starts on within the calendar matrix. Defaults to Day.SUNDAY.
• viewing: The initial date the calendar focuses on. Defaults to new Date().
• selected: An array of initial Date objects representing selected dates. Defaults to [].
• numberOfMonths: The number of months to display in the calendar matrix. Defaults to 1.

import { useLilius, Day } from 'use-lilius';

const options = {
  weekStartsOn: Day.MONDAY,
  viewing: new Date(2023, 0, 1),
  selected: [new Date(2023, 0, 15)],
  numberOfMonths: 2
};

const { calendar } = useLilius(options);