mina-scheduler: a React calendar with day, week and month views

What the component set is for

mina-scheduler is a customizable and flexible calendar component for React that lets you manage and display events in day, week or month views. The README is direct about the constraint that comes with it, which is that the library uses Next UI components for its user interface, so to ensure a consistent user experience you should make sure to use it inside a Next UI project. That single sentence tells you most of what you need to know about adoption. This is not a calendar you can drop into any React project, because the visual result is built out of Next UI primitives and the class name overrides the README demonstrates are Tailwind class strings, which means your Tailwind setup has to be able to see them. The feature list covers day, week and month views, event management with add, update and delete through built-in form validation, a customizable interface for buttons, tabs and event modals, a responsive design optimised for mobile, Framer Motion transitions between views, Zod schema validation for event data and Shadcn UI integration.

Two repositories, one component

The repository description is not a sentence but a pair of names, next-ui-full-calendar and shadcn-ui-full-calendar, and the README links the first of them as the GitHub repository, Mina-Massoud/next-ui-full-calendar. So the picture is a single calendar component maintained in two flavours, one against Next UI and one against Shadcn UI, with the npm package here being the Next UI build, and the live demo hosted at mina-scheduler.vercel.app. The top level of the repository shows the shape of a Next.js application rather than a library, with a `src/` directory, a `public/` directory, a `readme-assets/` directory holding the screenshots, a `components.json` which is the Shadcn configuration file, a `next.config.ts`, a `postcss.config.mjs`, a `tsconfig.json` and a `package-lock.json`. The package.json is marked private with version 0.1.0, which is consistent with a repository whose published artefact is the separate npm package rather than the app in the tree.

Installation and the smallest possible usage

The library installs from npm:

npm install mina-scheduler

And the minimal usage is a provider wrapping a view, with the client directive at the top because the calendar is interactive:

"use client";

import { SchedulerProvider, SchedularView } from "mina-scheduler";


export default function Home() {
  return (
    <section className="flex w-full flex-col items-center justify-center gap-4 py-8 md:py-10">
      <SchedulerProvider>
        <SchedularView />
      </SchedulerProvider>
    </section>
  );
}

Two details in that snippet are worth pausing on. The export name is spelled `SchedularView` rather than `SchedulerView`, which you will type wrong at least once. And the `use client` directive is not optional, because the component holds interactive state in a React context and cannot be rendered on the server without it.

Events, the provider and the dispatch hook

The `SchedulerProvider` and the `useScheduler` hook are how you seed and control events. The provider takes an `initialState` of events plus other props such as `weekStartsOn`, and the hook exposes a `dispatch` function so you can set events dynamically after the component mounts. The event type is imported from the package, and the shape is visible in the example, with an id, a title, a description, a `startDate` and `endDate` as Date objects, and a `variant` field. The dispatch call in the example uses a `SET_EVENTS` action type with the payload. The README includes a warning that is easy to skim past and important in practice, and it is that it is not recommended to use `useScheduler` at the top level of the component; if you use it, ensure that `SchedulerProvider` is applied at a higher level in the component tree so the context is available. This is the ordinary rule about hooks and context, and it is stated because getting it wrong produces a null context error that is not obviously related to where the hook was called.

Where the events actually live

The API documentation makes the data flow clear, and it is the part to read before choosing this component. The `SchedulerProvider` provides context and state management for the events and the calendar views, and it accepts three optional callbacks, `onAddEvent` and `onUpdateEvent` which take an event, and `onDeleteEvent` which takes an id string. The `weekStartsOn` prop takes either `sunday` or `monday` and defaults to `sunday`. The `children` prop is the React node rendered inside the provider. So the library owns the view and the editing flow, and it hands you the events through those callbacks, but persistence is your problem. In the example the initial events are created with `endDate` set one hour after `startDate`, which is described as a simulation of initial events, and the recommended way to set them is to pass them as `initialState` on the provider. The library ships no storage layer, no data fetching and no server integration, so wiring it to your API means holding the events in your own state and dispatching the callbacks into it.

Customising views, buttons and the event modal

The customization story is where the library earns its keep, and it works through three props. The `views` prop takes a `views` array for desktop and a `mobileViews` array for mobile, each entry being `day`, `week` or `month`, so you can offer a full set on a wide screen and only the day view on a phone. The `classNames` prop is a nested map that lets you replace the Tailwind classes on individual elements, and the example shows styling the add event, next and prev buttons with different background colours, and setting a padding class on the tabs panel. The `CustomComponents` prop lets you replace components such as event modals, buttons and tabs, and the example nests a `CustomEventModal` containing a `CustomAddEventModal` with a custom title and a `CustomForm` component of your own. That custom form example is the informative part, because it shows the contract your component has to satisfy, receiving `register` and `errors` from react-hook-form, spreading `register` onto the inputs so the Zod schema validation applies, and reading the error message off the field.

The dependency stack

The package.json tells you what the component is built from, and it is a modern shadcn-style stack. The Radix UI primitives are all present individually, with accordion, alert-dialog, aspect-ratio, avatar, checkbox, collapsible, context-menu, dialog, dropdown-menu, hover-card, label, menubar, navigation-menu, popover, progress, radio-group, scroll-area, select, separator, slider, slot, switch, tabs, toggle, toggle-group and tooltip. Alongside them sit class-variance-authority and clsx for styling, cmdk, date-fns for date handling, lucide-react for icons, next-themes for theming, react-day-picker, react-hook-form for the event forms, react-icons, the @hookform/resolvers package for wiring Zod into react-hook-form, and the `motion` package, which is the current name for Framer Motion and the one the README calls Framer Motion. On the application side there is Next 15.2.3, React 19, and a `next dev --turbopack` script. The dev scripts are the standard Next ones, with dev, build, start and lint.

Where this is the wrong choice

The limits are mostly about coupling and about maturity. First, the Next UI requirement. The component is built on Next UI primitives and the README asks you to use it inside a Next UI project, and while the package description mentions a Shadcn UI variant, the guidance in this README is for the Next UI build, so a project on Shadcn should read the sibling repository before assuming parity. Second, there is no persistence. The provider holds events in client state and the three callbacks are the whole integration surface, so a calendar for real bookings, with availability rules, conflicts and server validation, needs a layer you write. Third, the version. The package version is 0.1.0, the package is marked private, the repository publishes no GitHub releases, and the last push was on 2026-05-10, so there is no changelog and no sense of how the API has been changing. Fourth, the spelling of `SchedularView` and the two flavours of the same component are signs of a small project, and a library whose component name is misspelled in its own export is one that will get renamed at some point, which is a breaking change for you. Fifth, the repository records no licence at all, which for a component you intend to ship inside a product is a question to ask the author rather than a detail to note.

Editorial conclusion

mina-scheduler suits a React team that wants a calendar with a usable event editor rather than a grid of date cells, since the add, update and delete flows with validation are the expensive part and they are already here. It is the wrong choice if your project is not already on Next UI, because the README says to use it inside a Next UI project for a consistent look, and the wrong choice if you need to store events server side, since the state lives in a provider in the client. Before you adopt it, check the peer stack, which is Next 15, React 19 and Radix UI, and read the optional `useScheduler` note, because the README warns against calling the hook at the top level of a component. The last push was on 2026-05-10, the package version is 0.1.0, and the repository records no licence.

Frequently asked questions

Official sources

1. Issues
2. Mina-Massoud/mina-scheduler on GitHub
3. Project website
4. README