# VueSimpleCalendar: a month grid that draws events, not a date picker

> VueSimpleCalendar is a Vue 3 component that renders a month, week or year grid and lays scheduled items on it, including multi-day items. It deliberately leaves out an agenda view, item management and AJAX, and it ships with no external runtime dependencies beyond Vue itself.

**richardtallent/vue-simple-calendar** — Simple Vue component to show a month-grid calendar with events

- Repository: https://github.com/richardtallent/vue-simple-calendar
- Stars: 935 · Forks: 158
- Language: Vue
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/richardtallent-vue-simple-calendar

## A display component, deliberately narrower than a scheduling suite

VueSimpleCalendar is built for one job: showing a month as a grid and drawing scheduled activities on it. The project explains the motivation directly, that other calendar components tend to be either date pickers or overloaded with features, and that the author wanted something that simply shows a month and its scheduled items, including multi-day ones, on a grid. That simple use case remains the stated core focus even though the component goes beyond it.

What the component will not do is as informative as what it does. There is no agenda view, the time-of-day grid, because the project says that would require too much additional complexity. There is no interface for managing calendar items, described as far too use-specific, and no built-in AJAX mechanism for the same reason. Only the Gregorian calendar is supported, with seven-day weeks. And it is not currently possible to resize an item to cover more or fewer days, which the project flags as a possible future addition rather than a promise.

So the data model is yours. The component receives items with properties, renders them, and emits user events. The audience is a developer building an application that already has a schedule somewhere else and needs a good looking, themeable way to display it.

## Beyond the month grid: weeks, years, ranges and drag select

The display range is wider than the name suggests. The component shows a traditional month grid, and it also supports weeks, years, or multiple weeks, months, or years. If there are too many items to see in a week, you scroll to see the others, and the same applies when there are too many weeks in the component. Both are scrolling regions rather than truncated overflow.

Items can carry an optional time of day, and multi-day items are a first-class case rather than an afterthought. Dragging and dropping items between dates is optional, so a read-only view is a supported configuration. Date range selection works either programmatically or by drag-selecting with the user. Weeks can start on any day of the week, with Sunday as the default.

Localization is automatic and can be overridden. The component emits user events, clicks and drags among them, so the parent application owns the behaviour and the component owns the rendering.

Styling runs through two channels. The first is CSS class names you can target, with separate classes for the calendar, weeks, days and calendar items, which is how the built-in themes work. The second is Vue slots, and the documented set covers header, dayHeader, dayNumber, dayContent, item and weekNumber, so each piece of the grid can be replaced without forking the component.

## Installing the package and wiring up the two components

The component is published to npm and installed with a single command, assuming you already have a Vue application set up.

```bash
npm i --save vue-simple-calendar
```

In your application you import the component and register it with Vue, import the default theme or another theme as CSS, create the `CalendarView` component, add a `CalendarViewHeader` as a child if you want a header, and then wire up properties and events. Two conventions catch people out. Use kebab-case when specifying properties as attributes, for example `month-name-format="long"`, and use the `:` data binding prefix for properties that should be a Boolean, Number, Array or otherwise interpreted by JavaScript, for example `:show-times="true"`. You can omit the `:` for String properties with literal values.

The component fills its parent's height and width, so the parent needs a minimum height appropriate to the number of weeks and the average number of items per week being shown. The project also recommends that the parent of the `<CalendarView>` element contain only that component, with these styles, to keep an ancestor's layout from interfering with the calendar's own behaviour:

```css
display: flex;
flex-direction: column;
flex-grow: 1;
```

The default header emits an `input` event when a user clicks a button to move backward or forward through time, and the event argument is the new date to show. You handle that event and pass the date back to the calendar, which means navigation is not built in for you.

## Themes ship as separate CSS exports from the package

The packaging is worth understanding before you start, because the styles are not bundled into the JavaScript. The package manifest exposes several CSS entry points through its exports map: the main stylesheet at ./dist/vue-simple-calendar.css, then ./dist/css/default.css, ./dist/css/gcal.css, ./dist/css/holidays-us.css and ./dist/css/holidays-ue.css. There is also a separate ./interfaces entry point, which exposes the TypeScript declaration files at ./dist/lib/interfaces.d.ts.

That means importing a theme is an explicit import of a stylesheet path, and the sample application in the project does exactly that:

```javascript
import "..relative-path-to-node_modules/vue-simple-calendar/dist/vue-simple-calendar.css"
import "..relative-path-to-node_modules/vue-simple-calendar/dist/css/default.css"
import "..relative-path-to-node_modules/vue-simple-calendar/dist/css/holidays-us.css"
```

The class names applied on the element are what activate a theme. The documented example puts three of them on the same element, the base theme plus the US traditional and US official holiday classes, so themes compose rather than replace one another.

This arrangement is also why the customisation story is CSS first. The project documents a class for the calendar, for weeks, for days and for calendar items, and the recommended path for a site with its own design is to write your own rules against those names instead of overriding internal component structure.

## The limits the project states: no agenda view, no mobile drag, no IE11

Three limitations are stated rather than discovered, which is unusual and useful.

The first is the missing agenda view. There is no time-of-day grid, and the project explains the reason as the additional complexity involved. A team that needs hourly slots within a day has to build that on top, because this component renders days as cells rather than as time axes.

The second is the mobile story. The component is designed first for desktop web applications, and while it may operate on a mobile device, the limited resolution may not allow for much in the way of useful functionality. More concretely, drag and drop only works on desktop browsers, because the drag events on touch devices behave differently and the author says there has been no time to dig into them.

The third is the browser floor. The component is compatible with relatively modern browsers and not IE11. Version 6.0, released 2021-03-27, dropped IE11 support and moved to Vue 3 and Vite. Version 5 remains available on npm for anyone who needs Vue 2 or IE11, but the project states it will not be maintained going forward, so a Vue 2 project is on a frozen track.

There is also a build limitation for TypeScript users. The project describes it as nearly impossible to get Vite configured to both emit `.d.ts` files on build and to allow use of `npm run dev`, and says the `typescript2` plugin breaks hot module replacement. The author decided not to let that block the release, so declaration files exist in the package while the dev server workflow stays awkward.

## A date picker or a full calendar suite are different tools

The nearest comparison is a date picker, and the project itself draws the line. A picker answers one question, which day did the user choose, and it renders a popover. VueSimpleCalendar answers a different question, what is scheduled on this month, and it renders the full grid with items laid across it. If you only need a single date from a user, a picker is less code and less surface area.

The other comparison is a full scheduling suite with agenda views, event editing forms, resource booking and a data layer. The difference in approach is that such a suite owns your data model and your interaction rules, whereas this component is a presentation layer over data you already hold. The project is explicit that there is no interface for managing calendar items and no AJAX mechanism, so the arrangement is deliberate: you keep the schedule in your own store, hand it in as props, and react to the events the component emits.

There is a middle option too, a grid you write yourself in a few dozen lines of table markup. The counterargument to doing that is the long tail: multi-day items spanning cells, overflow scrolling when a week is dense, per-slot templates, week numbers, holiday theming, and drag reordering. VueSimpleCalendar exists because that tail is the same for everyone.

For a team already on Vue 3 with a schedule elsewhere, the trade is between writing that tail yourself and accepting the constraints listed above.

## MIT licensed, versioned releases and a three-year Vue 2 tail

The licence is MIT, and the package manifest repeats it, so the code and the styles can be used in a commercial application without copyleft obligations.

The versioning history explains the compatibility story. Version 6.0 on 2021-03-27 was the break to Vue 3 and Vite. The recent tags are v7.2.2 on 2026-04-17, v7.2.1 on 2025-03-29 and v7.2.0 on 2025-03-29, and the repository was last pushed on 2026-10-17. The manifest, meanwhile, sits at version 7.3.0, which suggests the working tree is ahead of the most recent published tag.

The manifest also states the runtime floor for contributors and for anyone building the package: Node `^20.19.0 || >=22.12.0`. The library's only runtime dependency is Vue itself at `^3.5.44`, which is the honest definition of the lightweight claim in the feature list, since the project explicitly lists no Moment and no jQuery.

The test setup shows how the component handles the kind of bug that a calendar invites, date and timezone arithmetic. The test script runs the suite three times, once with `TZ=America/New_York`, once with `TZ=Pacific/Auckland` and once with `TZ=UTC`:

```json
"test": "TZ=America/New_York vitest run && TZ=Pacific/Auckland vitest run && TZ=UTC vitest run"
```

Running the same tests across three timezones is a deliberate choice, and it is the part of the project most worth copying if you maintain a date component of your own.

## Conclusion

VueSimpleCalendar suits an application that needs to display existing scheduled items on a readable grid and nothing more, in a Vue 3 project on Node 20 or later. It does not suit a scheduling product that needs time-of-day slots, item editing, or a data layer, since the project states those are out of scope, and drag and drop does not work on touch devices. Before adopting it, check the theme CSS you plan to import from the package exports, set a minimum height on the parent of the CalendarView element as the documentation asks, and confirm your Vue version is 3, since the Vue 2 line is version 5 and is no longer maintained.

## FAQ

### How do I install VueSimpleCalendar?

Install it from npm with `npm i --save vue-simple-calendar`. You then import the component, register it with Vue, import a theme stylesheet such as `dist/css/default.css`, and create the `CalendarView` component with an optional `CalendarViewHeader` child.

### Does VueSimpleCalendar support Vue 2?

Version 6.0, released 2021-03-27, dropped IE11 support and migrated to Vue 3 and Vite. Version 5 is still available on npm for Vue 2 or IE11 needs, but the project states it will not be maintained going forward.

### Can VueSimpleCalendar show an agenda or time-of-day view?

No. The project states there will be no agenda view, because adding that grid would require too much additional complexity. It renders month, week and year grids with optional times on items instead.

### How do I customise the look of VueSimpleCalendar?

There are two routes. You can write your own CSS against the documented calendar, week, day and calendar item classes, or you can replace parts of the grid using Vue slots, with slots available for the header, dayHeader, dayNumber, dayContent, item and weekNumber.

### Does drag and drop work in VueSimpleCalendar on mobile?

No. The project states that drag and drop only works on desktop browsers, because the drag events on touch devices are different and were not investigated. The component is designed first for desktop web applications.

## Sources

- [Issues](https://github.com/richardtallent/vue-simple-calendar/issues)
- [License: MIT](https://github.com/richardtallent/vue-simple-calendar/blob/main/LICENSE)
- [README](https://github.com/richardtallent/vue-simple-calendar/blob/main/README.md)
- [Releases](https://github.com/richardtallent/vue-simple-calendar/releases)
- [richardtallent/vue-simple-calendar on GitHub](https://github.com/richardtallent/vue-simple-calendar)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/richardtallent-vue-simple-calendar