Download the PHP package webcito/bs-calendar without Composer

Bootstrap Calendar Plugin

bs-calendar is a jQuery plugin for Bootstrap 5 calendars with day, timeline, 4day, week, month, agenda, and year views. It supports remote appointment loading, calendar filters, search, holidays, custom formatting, drag-create, drag-move, tasks, and local appointment add/edit/delete methods.

As of version 2, Bootstrap 4 is no longer supported. Use version ^1 for Bootstrap 4 projects.

Table of Contents

• Requirements
• Installation
• Quick Start
• Run the Demo
• Core Concepts
• Appointment Data
• Recurring Appointments
• Remote Data with url
• Add, Edit, and Delete Workflow
• Options
• Events and Callbacks
• Methods
• Formatters
• Extras Object
• Colors
• Holidays
• Localization and Translations
• Utilities
• Repository Notes
• Completeness Check

Requirements

• jQuery ^3
• Bootstrap ^5 CSS and JavaScript bundle
• Bootstrap Icons ^1
• PHP and Composer are only needed for running the local demo with the bundled vendor/ dependencies.

No Node.js build step is required for normal usage. The browser-ready files are shipped in dist/.

Installation

Use CDN/script tags:

Or install via Composer:

After Composer installation, include vendor/webcito/bs-calendar/dist/bs-calendar.min.js together with jQuery, Bootstrap, and Bootstrap Icons.

Quick Start

Load appointments from a function:

Add, edit, and delete appointments locally:

Run the Demo

Open http://localhost:8000/demo/index.html.

The demo contains one calendar instance and shows a modal-based add/edit/delete flow using addAppointment, editAppointment, and deleteAppointment.

Core Concepts

• url controls remote appointment loading. It can be null, a URL string, or a function returning a Promise.
• calendars defines sidebar filters. Active calendar IDs are always sent as calendarIds in remote requests.
• add.bs.calendar, edit.bs.calendar, and delete.bs.calendar are intent events. They tell your application what the user wants; they do not save anything.
• addAppointment, editAppointment, and deleteAppointment mutate only the currently loaded browser-side appointment list. For backend-backed calendars, persist to your backend first or call refresh after saving.
• refresh reloads data from url.
• render re-renders already loaded data without calling url.
• year view uses summary objects (date, total, optional content), not full appointment objects.
• Recurring appointments are normal appointment objects with a recurrence object. They are expanded only for loaded appointment views.
• Tasks are normal appointment objects with a task object.

Appointment Data

For day, timeline, 4day, week, month, agenda, and search results, appointments use this shape:

Required fields:

Optional fields:

Reserved field:

All-day appointments:

The plugin normalizes all-day start/end values to full-day boundaries internally.

Link object:

Link object fields:

Recurring Appointments

Recurring appointments are stored as one source appointment with a recurrence object. bs-calendar expands that source appointment into renderable occurrences for the currently loaded date range. Your database can therefore keep one master record instead of one row per date. In normal appointment views the source appointment itself is not rendered in addition to its occurrences.

Core model:

Minimal weekly example:

Supported recurrence fields:

Occurrence fields generated by bs-calendar:

after-load.bs.calendar, appointment formatters, and intent events receive the expanded occurrence objects. Use appointment.recurringId or extras.recurrence.recurringId whenever you need to map an occurrence back to the source record.

Frequency behavior:

Multiple weekdays:

This creates Monday and Wednesday occurrences from 2026-06-01 onward.

Every second week with one skipped date:

Client-side local API behavior:

addAppointment, editAppointment, and deleteAppointment work on the source appointment list. If you pass a generated occurrence object to editAppointment or deleteAppointment, bs-calendar uses recurringId and updates/removes the source appointment. This first recurrence API does not create per-occurrence overrides.

Formatter example:

Remote data guidance:

• For day, timeline, 4day, week, month, and agenda, your url receives fromDate and toDate. Return recurring source appointments that can have at least one occurrence in that range.
• Do not filter recurring source appointments only by start date. A weekly source from January can still produce a June occurrence.
• A practical server-side overlap check is: source start <= toDate and either no until or until >= fromDate. If you use count, your backend may need its own recurrence check for exact filtering.
• year view uses summary rows (date, total, optional content), so recurrence expansion is not applied there. Return already counted year summary data.
• Search is controlled by your url response. For broad search across a long-running series, return the matching source or concrete rows your application wants to show.

Current boundaries:

• Supported rules are intentionally simple: daily, weekly, monthly, yearly, interval, until/end, count, weekly days, and date exceptions.
• RRULE strings, nth weekday rules, timezone-specific recurrence sets, moved occurrences, and edited single occurrences are not supported yet.
• Occurrences inherit the source appointment fields. Store exceptions or future per-occurrence overrides in your own backend model.

Task Fields

An appointment is treated as a task when it contains a truthy task object.

Task behavior:

• Task icons use icons.task, icons.taskDone, and icons.taskOverdue.
• Clicking a task icon toggles task.checked locally and fires task-status-changed.bs.calendar.
• The global task sidebar control is shown when showTasks is true.
• Task visibility state is sent to normal view and search requests as showTasks.
• task.isOverdue is internal render state. You may read it in callbacks, but you should not persist it as source data.

Remote Data with url

url is the appointment data source. It accepts three value types:

String URL example:

Function URL example:

Request data in normal appointment views:

Request data in search mode:

Normal response for day, timeline, 4day, week, month, and agenda:

Search response:

Year-view response:

Year summary fields:

Use queryParams to append custom request values:

queryParams receives the generated requestData and should return an object. The returned object is merged into the request. Protected keys fromDate, toDate, year, and view cannot be overridden.

You can also change remote loading at runtime:

Add, Edit, and Delete Workflow

add.bs.calendar, edit.bs.calendar, and delete.bs.calendar are intent events. They let your app open a modal, confirm destructive actions, validate input, save to a backend, and then update the calendar.

Callback options receive the same payloads:

After a local mutation method has succeeded, the calendar fires completion events:

When drag-create is used, dragExtras contains the proposed start, end, hour-slot rule availability, and appointment duration rule availability. When drag-move or drag-resize is used, appointment still contains the original appointment and dragExtras contains the proposed new range.

If hourSlots.rules[].mode is blocked or exclusive, interactive creation, drag-moving, and drag-resizing respect those rules. Day/week/4day drag-create, drag-move, and drag-resize clamp to the nearest valid rule edge while dragging; invalid click-create and invalid drop targets do not fire add.bs.calendar or edit.bs.calendar.

For drag-create, drag-move, and drag-resize, the allowed interval starts as every exclusive range for that weekday. If no exclusive range exists, the whole visible hourSlots.start to hourSlots.end range is allowed. blocked ranges are then subtracted from those intervals. preferred ranges do not block dragging.

For backend-backed calendars, save to your backend first and then either call refresh so the updated data is loaded from url, or call addAppointment, editAppointment, or deleteAppointment for an immediate local update and ensure the backend returns the same data on the next refresh.

Options

All options can be passed during initialization:

Options may also be supplied through jQuery data-* attributes. JavaScript options override data attributes. Some options can be changed later with updateOptions.

Hour Slot Rule Priority

hourSlots.rules affect availability in this order:

1. blocked wins whenever the requested time range overlaps a blocked range.
2. exclusive applies next. If any exclusive rule exists for the weekday, work is allowed only when the requested time range is fully contained in an exclusive range.
3. preferred allows work and sets isPreferred.
4. highlight or an omitted mode is visual only and does not block work.
5. If no rule matches, work is allowed.

This means overlapping blocked and exclusive rules are treated as blocked. Overlapping blocked and preferred rules are also treated as blocked.

Slot background colors use the same mode-aware priority. For overlapping colors, the winning availability rule provides the color.

Appointment Duration Rules

appointmentRules validates timed appointment durations during interactive creation, moving, and resizing. It is separate from hourSlots.rules: hourSlots.rules describes when work is allowed, while appointmentRules describes how long a timed appointment may be.

Fixed 60-minute appointments:

With durationMinutes, click-create and drag-create propose exactly that duration. Resize handles are not rendered for timed appointments because the duration is fixed.

45-minute coaching blocks:

This allows 45, 90, 135 minutes, and so on. draggableSnapMinutes still controls the pointer grid for start/end times; the duration rule then snaps the appointment length to the nearest valid duration.

Flexible 30-minute blocks between 30 and 120 minutes:

If durationMinutes is set, it wins over step/min/max rules. Otherwise, min/max are applied first and durationStepMinutes restricts the result to valid multiples. Drag event payloads expose the validation result as dragExtras.appointmentRules with canWork, durationMinutes, rules, and violations.

Calendar filters:

Calendar fields:

Translations

Icons

Events and Callbacks

Events use the .bs.calendar namespace:

Callback options receive the same payload as their matching event, without the jQuery event object. Callback options may be functions or global function-name strings.

Methods

Call methods with the jQuery plugin method syntax:

Examples:

There is no public getAppointment method. The plugin only stores the currently loaded view/search appointment slice, so ID lookup would not be a reliable global data access API.

Timeline View

The timeline view is a standalone horizontal timeline/Gantt view for one day. It is available as a normal calendar view and can be selected through the view navigation or configured with startView: 'timeline'.

In timeline mode, all timed appointments share one horizontal track. Appointments that overlap in time are placed into additional lanes within that track, so the track grows vertically as needed. With the default timelineGroupBy: null, the location field is not used for grouping. The lane layout is recalculated live while an appointment is moved. Set timelineGroupBy to an appointment attribute such as 'location' to render one timeline row per distinct value. Appointments without that attribute or without a value are collected in one additional localized unassigned row. Array values are combined into one group key. For configured calendars, use either timelineGroupBy: 'calendarId' or the 'calendars' alias; the configured calendar titles are used as row labels. When draggable is disabled, resize handles are hidden and move/resize interactions are unavailable. The view control and UTC offset stay visible independently of the horizontal timeline scroll area.

Timeline appointments support click-to-add, drag-create, horizontal move, and horizontal resize when draggable: true. All of these interactions use the existing add.bs.calendar and edit.bs.calendar events and respect hourSlots.rules, appointmentRules, and draggableSnapMinutes.

Formatters

Formatters customize appointment, search, holiday, info-window, and duration rendering.

Formatter signatures:

In month view, day cells automatically show a small expand button when their appointment list overflows. The expanded month-day overlay uses formatter.monthExpanded(appointment, extras) so the compact formatter.month output can stay single-line.

Extras Object

extras is generated for each appointment after loading/normalization.

extras.recurrence contains:

extras.hourSlotRules and drag dragExtras.hourSlotRules contain:

displayDates[] entries contain:

Year-view summary objects get a smaller extras object with colors, isToday, and isNow.

Colors

Supported color inputs:

• Bootstrap theme names or class combinations, e.g. primary, danger opacity-75 gradient
• Hex colors, e.g. #ff5733
• RGB/RGBA values
• CSS variables, e.g. var(--bs-primary)
• Named CSS colors, e.g. steelblue

Use the public color helper:

Holidays

holidays uses the OpenHolidays API. If country or language is missing, bs-calendar derives it from locale.

If url is null, holidays can still be loaded and rendered.

Localization and Translations

The locale option has two responsibilities:

• It controls date/time formatting through Intl.DateTimeFormat.
• Its language part selects the built-in translation object. For example, de-DE, de-AT, and de_CH all use the de translations after locale normalization.

If no matching language exists, bs-calendar falls back to English.

Built-In Languages

Translation Keys

All built-in translation objects currently use these keys:

Selecting A Locale

Underscores are normalized, so de_DE is treated as de-DE.

Overriding Strings Per Instance

You can override individual strings without redefining the whole language. Custom translations are merged with the selected built-in language.

Registering Or Replacing A Language

Use $.bsCalendar.addTranslation(locale, translation) before initialization. Only the language code before the hyphen is used as the registry key. For example, de-CH registers or replaces de, not a separate Swiss-German variant.

For regional wording differences, keep the regional locale for date formatting and override strings per instance:

Reading Translations Programmatically

These helpers use the language key. If you pass a regional locale like de-DE, only de is used internally.

Changing Locale At Runtime

Use setLocale when you only want to change the locale. Use updateOptions when you also want to override translation keys at the same time.

Runtime locale changes are ignored while the calendar is in search mode.

Utilities

Global API:

Appointment and date helpers:

Lower-level utility helpers:

OpenHolidays helpers:

Repository Notes

Key files:

Development notes:

• No npm build is required.
• dist/bs-calendar.js is the unminified browser source.
• dist/bs-calendar.min.js should be regenerated after changes to dist/bs-calendar.js.
• The demo expects Composer dependencies in vendor/.
• No automated test suite is currently included.

Changelog and support:

• Changelog
• Issues
• License

Completeness Check

This README is intended to cover the public surface of version 2.4.0:

• All DEFAULTS options from dist/bs-calendar.js
• All public plugin methods in the method switch
• All jQuery events emitted through trigger() and matching on* callback options
• Appointment object fields, including task fields and generated id behavior
• url value types, request data, and response contracts
• Formatter signatures
• extras fields used by callbacks and formatters
• Global $.bsCalendar API and utility helpers
• Localization and custom translation handling