PHPackages                             webcito/bs-calendar - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. webcito/bs-calendar

ActiveLibrary[Utility & Helpers](/categories/utility)

webcito/bs-calendar
===================

A jQuery-based Bootstrap calendar plugin with day/week/month/year views.

v2.0.12.1(2mo ago)182055[1 issues](https://github.com/ThomasDev-de/bs-calendar/issues)MITHTML

Since Mar 11Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/ThomasDev-de/bs-calendar)[ Packagist](https://packagist.org/packages/webcito/bs-calendar)[ Docs](https://github.com/ThomasDev-de/bs-calendar)[ RSS](/packages/webcito-bs-calendar/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (32)Used By (0)

Bootstrap Calendar Plugin
=========================

[](#bootstrap-calendar-plugin)

[![Version](https://camo.githubusercontent.com/bd928b052b68d9f22ad912e55f0129438cb4d3043c4c37e472cc0d11a500938d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d322e302e31322e312d626c7565)](https://camo.githubusercontent.com/bd928b052b68d9f22ad912e55f0129438cb4d3043c4c37e472cc0d11a500938d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d322e302e31322e312d626c7565)[![jQuery](https://camo.githubusercontent.com/efce6a9b239f77cbd3635c29e536e7d760d558512489a9ffd64a1ac971ec9918/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6a51756572792d76332e782d6f72616e6765)](https://camo.githubusercontent.com/efce6a9b239f77cbd3635c29e536e7d760d558512489a9ffd64a1ac971ec9918/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6a51756572792d76332e782d6f72616e6765)[![Bootstrap](https://camo.githubusercontent.com/720b83f2edf76717ab18374a868eedb49337f753c44559d45e56cc69f42b6a0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426f6f7473747261702d76352d626c756576696f6c6574)](https://camo.githubusercontent.com/720b83f2edf76717ab18374a868eedb49337f753c44559d45e56cc69f42b6a0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f426f6f7473747261702d76352d626c756576696f6c6574)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)

[changelog](changelog.md#version-20121)

---

Repository Guide
----------------

[](#repository-guide)

This section provides a practical, up‑to‑date overview of the repository with stack details, installation, local demo setup, scripts, environment variables, tests, project structure, and licensing. It complements the detailed API docs that follow below.

### Overview

[](#overview)

`bs-calendar` is a lightweight jQuery plugin that renders a responsive calendar UI for Bootstrap 5 with day, week, month, and year views. It ships as a browser‑side JavaScript library (no build step required) and includes a demo you can run locally. Distribution is via Composer ( mainly to bundle Bootstrap, Bootstrap Icons, and jQuery for the demo) and via direct script tags/CDNs.

Key entry points:

- `dist/bs-calendar.js` — unminified browser script
- `dist/bs-calendar.min.js` — minified browser script
- Demo: `demo/index.html` (references assets from `vendor/` and `dist/`)

### Requirements

[](#requirements)

- Browser runtime with:
    - jQuery `^3`
    - Bootstrap `^5` (CSS + JS bundle)
    - Bootstrap Icons `^1`
- For running the local demo and installing vendor assets: PHP `>=8.0` (recommended) with Composer

Note: No Node.js toolchain is required for usage; this project ships prebuilt assets in `dist/`.

### Installation

[](#installation)

You can use the plugin either via CDN or by installing it through Composer and serving it from `vendor/`.

1. CDN/script tags (quick start)

```

    $(function () {
        $('#calendar').bsCalendar();
    });

```

2. Composer (PHP projects, or to run the demo)

```
composer require webcito/bs-calendar
```

After installation, the browser script will be available under `vendor/webcito/bs-calendar/dist/bs-calendar.min.js`. Include Bootstrap, Bootstrap Icons, and jQuery as well (installed under `vendor/`).

### Setup and Run (Local Demo)

[](#setup-and-run-local-demo)

This repository contains a demo page at `demo/index.html` that loads assets from `vendor/` and `dist/` using relative paths.

Steps:

- Install dependencies:
    - `composer install`
- Start a simple local server with the project root as the document root so that `/vendor` and `/demo` are both accessible:
    - PHP built‑in server:
        - `php -S localhost:8000 -t .`
- Open the demo:
    -

If you prefer another static server, ensure the server’s document root is the project root so `/vendor/...` paths used by the demo resolve correctly.

### Scripts

[](#scripts)

- Composer scripts: none defined in `composer.json`.
- NPM scripts: not used.

### Environment Variables

[](#environment-variables)

- None required by the library or demo.
- If you integrate holiday APIs or remote data sources in your application, manage your own keys/config in your host app. The library itself does not read env vars.

### Tests

[](#tests)

- No automated tests are present in the repository at this time.
- TODO: Add unit/integration tests and document how to run them.

### Project Structure

[](#project-structure)

High‑level structure (key folders only):

```
.
├── LICENSE
├── README.md
├── changelog.md
├── composer.json
├── composer.lock
├── dist/
│   ├── bs-calendar.js
│   └── bs-calendar.min.js
├── demo/
│   ├── index.html
│   └── img/
└── vendor/            # Installed by Composer (jQuery, Bootstrap, Bootstrap Icons, etc.)

```

### License

[](#license)

This repository includes an MIT license (see `LICENSE`). `composer.json` is aligned to `MIT`.

### Changelog and Support

[](#changelog-and-support)

- Changelog: `changelog.md`
- Issues:
- Docs/homepage:

---

Warning

As of version 2, Bootstrap 4 is no longer supported.
To use the plugin in **Bootstrap 4**, use version **^1.** .

DayWeekMonthYear[![day](demo/img/day.png)](demo/img/day.png)[![week](demo/img/week.png)](demo/img/week.png)[![month](demo/img/month.png)](demo/img/month.png)[![year](demo/img/year.png)](demo/img/year.png)Effortlessly manage and display calendar views with the **Bootstrap Calendar Plugin**, a lightweight yet powerful jQuery plugin designed for modern web applications. This plugin seamlessly integrates with Bootstrap ^v5, offering a fully responsive and customizable calendar interface with advanced features such as event handling, dynamic holiday API integration, and support for multiple views (`day`, `week`, `month`, and `year`).

Whether you're building a scheduling application, an event tracker, or simply need a robust calendar solution, this plugin puts flexibility and ease-of-use at your fingertips. Packed with intuitive options, versatile callbacks, and a highly customizable design, you can tailor it to fit your specific use case effortlessly.

- [Bootstrap Calendar Plugin](#bootstrap-calendar-plugin)
    - [Key Features](#key-features)
    - [Example Usage](#example-usage)
    - [Options](#options)
        - [options.calendars](#optionscalendars)
        - [options.url](#optionsurl)
        - [options.formatter](#optionsformatter)
            - [Properties](#properties)
            - [Example Configuration](#example-configuration)
        - [The 'extras' object](#the-extras-object)
        - [options.holidays](#optionsholidays)
            - [Configuration Structure:](#configuration-structure)
            - [Notes](#notes)
        - [options.translations](#optionstranslations)
            - [Configuration Structure:](#configuration-structure-1)
            - [Notes](#notes-1)
        - [options.icons](#optionsicons)
            - [Configuration Structure:](#configuration-structure-2)
            - [Notes](#notes-2)
    - [Attributes for an Appointment](#attributes-for-an-appointment)
        - [Required Attributes](#required-attributes)
        - [Optional Attributes](#optional-attributes)
        - [Reserved Attributes](#reserved-attributes)
        - [Example](#example)
        - [Notes](#notes-3)
    - [Triggerable Events](#triggerable-events)
        - [Available Events and Parameters](#available-events-and-parameters)
        - [Usage](#usage)
        - [Notes](#notes-4)
    - [Methods](#methods)
        - [Available Methods](#available-methods)
    - [Utilities](#utilities)
    - [Feedback, Assistance, or Suggestions](#feedback-assistance-or-suggestions)
    - [Explore More Projects](#explore-more-projects)

Key Features
------------

[](#key-features)

- 🔄 **Dynamic Views**: Easily toggle between `day`, `week`, `month`, and `year` views.
- 🌐 **Localization Support**: Customize `locale`, start-of-week, and translations.
- 📅 **Event Management**: Add, edit, delete, and view appointments with ease.
- 🛠️ **Customizable Styling**: Fine-tune the appearance with support for themes, icons, and utility classes.
- 🎉 **Holiday Integration**: Fetch and display public holidays and school holidays using the `OpenHolidays API`.
- ⚡ **Interactive UI**: Navigate with the mouse wheel, handle user interactions, and access powerful event callbacks.
- 🕒 **Flexible Time Slots**: Configure detailed hour slots for precision scheduling.

Example Usage
-------------

[](#example-usage)

```
>

    Minimalistic Calendar Example

    $(document).ready(function () {
        $('#calendar').bsCalendar({
            startView: 'week',
            locale: 'de-DE',
            holidays: {country: 'DE', federalState: 'BE'}
        });
    });

```

With the Bootstrap Calendar Plugin, you can turn any project into a fully functional, beautifully styled, and highly interactive scheduling solution!

---

Color Handling
--------------

[](#color-handling)

The plugin offers a flexible and powerful way to handle colors. Whether you want to use predefined Bootstrap styles, custom color codes, or modern CSS variables, `bs-calendar` handles the heavy lifting—including automatic text color contrast for better accessibility.

### Supported Color Formats

[](#supported-color-formats)

You can define colors in several formats across the plugin (e.g., for `mainColor`, `calendars[].color`, or `appointment.color`):

1. **Bootstrap Theme Colors**: Use standard names like `primary`, `success`, `danger`, `warning`, `info`, `dark`, or `light`. The plugin automatically maps these to Bootstrap's utility classes (e.g., `text-bg-primary`).
2. **Hexadecimal Codes**: Standard hex strings like `#ff5733` or shorthand like `#f00`.
3. **RGB/RGBA**: Functional notation like `rgb(255, 0, 0)` or `rgba(0, 255, 0, 0.5)`.
4. **CSS Variables**: Modern CSS variables such as `var(--bs-primary)` or any custom variable defined in your stylesheets.
5. **Named Colors**: Standard HTML color names like `red`, `blue`, or `steelblue`.

### Smart Features

[](#smart-features)

- **Automatic Contrast**: When you provide a direct color (Hex, RGB, or CSS variable), the plugin automatically calculates the brightness and sets the text color to either white or black to ensure readability.
- **Bootstrap Integration**: When using Bootstrap classes, it leverages `text-bg-*` utilities to maintain consistency with your Bootstrap theme.
- **Opacity Support**: If you use RGBA or colors with opacity classes, the plugin correctly computes the resulting background.

---

### Programmatic usage (public API)

[](#programmatic-usage-public-api)

You can also use the color computation helper directly from code. The function is part of the public API:

```
// signature
$.bsCalendar.utils.getColors(color, fallbackColor);

// examples
const fromHex = $.bsCalendar.utils.getColors('#ff5733');
const fromBootstrap = $.bsCalendar.utils.getColors('primary');
const fromCssVar = $.bsCalendar.utils.getColors('var(--bs-primary)', 'primary');

// Returned object (shape)
// {
//   origin: ,
//   backgroundColor: ,
//   backgroundImage: ,
//   color:
// }
```

---

Options
-------

[](#options)

The calendar provides a wide range of configuration options to customize its behavior and appearance. While there are many options available, you don’t need to configure them all—the default values are already set for common use cases. Adjust the options as needed to better fit your specific requirements. Below is a detailed overview of all available options, including their types, default values, and descriptions.

**Option****Type****Default Value****Description****locale**`string``"en-GB"`Specifies the language and country format to be used. Determines the displayed text for months and days of the week based on the language.**title**`string``null`The title displayed at the top-center of the calendar. Can be a string or HTML.**startWeekOnSunday**`boolean``true`Indicates whether the week starts on Sunday. If set to `false`, the week starts on Monday.**showAddButton**`boolean``true`Should a button for adding an appointment be displayed in the top navbar.**navigateOnWheel**`boolean``true`Enables navigation through days, weeks, months, or years using the mouse wheel if set to `true`.**rounded**`number``5`Specifies the border rounding of elements in pixels, enhancing the visual presentation.**border**`number``1`Specifies the border width of elements in pixels, enhancing the visual presentation.**search**`object` | `null``{limit: 10, offset: 0}`Activates search. Set the option to zero to disable searching.**search.limit**`number``10`Sets a maximum number of search results to be returned.**search.offset**`number``0`Sets an offset for starting the search results.**startDate**`Date``new Date()`The starting date for the calendar view.**startView**`string``"month"`Defines the initial view of the calendar. Acceptable values include `"year"`, `"month"`, `"week"`, and `"day"`.**mainColor**`string``"primary"`The main color applied to calendar elements (e.g., events, highlights). It can be a BS class, a hex, rgb, or a CSS variable.**views**`array``["year", "month", "week", "day"]`Lists the available viewing modes for the calendar.**holidays**`object` | `null`See [options.holidays](#optionsHolidays)Data source for holiday display. Use an object for custom settings or `null` for no holidays.**translations**`object`See [options.translations](#optionsTranslations)Defines translations used for various textual content in the calendar.**icons**`object`See [options.icons](#optionsIcons)Specifies icons for different controls and actions in the calendar (e.g., next, back, add).**url**`string` | `function` | `null`See [options.url](#optionsUrl)Specifies the base URL for fetching external data like holidays or events. Can be a fixed string URL or a dynamic function that generates the URL. `null` disables external requests.**queryParams**`function` | `null``null`A function to dynamically define query parameters for external requests. Receives existing request data as input and returns additional key-value pairs for the request. If `null`, no extra parameters are added.**topbarAddons**`function` | `null``null`Allows injecting additional custom content in the top navigation bar of the calendar.**sidebarAddons**`function` | `null``null`Allows injecting additional custom content in the side navigation panel.**formatter**`object`See [options.formatter](#optionsFormatter)Defines formatters to customize the display or structure of specific calendar views.**hourSlots**`object``{height: 30, start: 0, end: 24}`Customizes time slots in the day or week view with detailed configurations (e.g., slot height, starting hour, ending hour).**calendars**`array` | `null``null`Defines a list of calendar objects (id, title, color) used to categorize and filter appointments via the sidebar.**onInit**`function()``null`Called after the calendar is fully initialized. Use this for any required setup operations.**onAdd**`function(data)``null`Triggered when the "Add" button is clicked or when a time grid is clicked in the day/week view. Provides an object with view-specific details.**onEdit**`function(appointment, extras)``null`Triggered when editing an appointment. The first argument is the appointment being edited, and the second provides additional context.**onDelete**`function(appointment, extras)``null`Triggered when deleting an appointment. The first argument is the appointment being deleted, and the second provides additional context.**onView**`function(view)``null`Triggered when the calendar view changes. The new view is passed as an argument.**onBeforeLoad**`function(requestData)``null`Invoked prior to retrieving appointments. Receives contextual information, such as the current view, time span, and search term, if any.**onAfterLoad**`function(appointments)``null`Triggers after the appointments have been loaded and gives them as parameters.**onShowInfoWindow**`function(appointment, extras)``null`Triggered when an information dialog (info window) is displayed. The appointment and supplemental context are passed as parameters.**onHideInfoWindow**`function()``null`Triggered when an information dialog (info window) is closed.**onNavigateForward**`function(view, from, to)``null`Triggered when navigating forward within the calendar. Provides the current view, and the starting and ending dates of the period.**onNavigateBack**`function(view, from, to)``null`Triggered when navigating backward within the calendar. Similar to `onNavigateForward`, providing the current view, and the starting/ending dates of the period.**storeState**`boolean``false`When enabled (`true`), the current calendar state (e.g., selected view) is saved to `localStorage` and restored on the next page load. Additionally, if `options.calendars` contains items with unique `id` values, the active/inactive state per calendar is persisted and restored.**debug**`boolean``false`Enables debug mode for development purposes. Logs additional information on various calendar operations.### options.calendars

[](#optionscalendars)

Defines a list of calendar categories displayed in the sidebar. This allows users to toggle the visibility of specific appointment groups interactively.

- **Type**: `Array` | `null`
- **Default**: `null`

#### Configuration Structure per Calendar Object

[](#configuration-structure-per-calendar-object)

AttributeTypeRequiredDefaultDescription**id**`string`|`number`**Yes**-Unique identifier. This ID is passed to the backend/fetch function to filter appointments.**title**`string`No`"Calendar {i}"`The display name shown in the sidebar list.**color**`string`No`settings.mainColor`The visual color indicator. Supports Bootstrap classes (e.g., `primary`), Hex, RGB values, or CSS variables.**active**`boolean`No`true`The initial visibility state. Users can toggle this interactively.### options.url

[](#optionsurl)

The `url` option controls how the calendar fetches appointment (and search) data. It accepts a `string`, a `function`, or `null`. If left as `null` (the default), the calendar will not attempt to load external appointment data. **Note**: Even if `url` is `null`, the calendar will still load and display holidays (if configured in `options.holidays`).

- Type: `string | function | null`
- Default: `null`
- Purpose: Provide either a static endpoint or a custom fetch function to supply appointments to the calendar.

Usage patterns:

1. Static URL (string)
    Provides a server endpoint that returns JSON in the expected structure. The plugin uses a GET request and passes query parameters describing the requested period or search parameters.

    Example response formats:

    - For normal views (day / week / month): an array of appointment objects:

    ```
    [
      {
        "id": 1,
        "title": "Meeting",
        "start": "2025-07-01 10:00:00",
        "end": "2025-07-01 11:00:00",
        "color": "primary"
      }
    ]
    ```

    - For search mode: an object with `rows` (an appointment array) and `total` (number of results):

    ```
    {
      "rows": [],
      "total": 42
    }
    ```

    Request parameters sent by the plugin:

    - Non-search mode:
        - `view`: one of `"day"`, `"week"`, `"month"`, `"year"`
        - If `view === "year"`: `year` (numeric)
        - Otherwise: `fromDate` (YYYY-MM-DD), `toDate` (YYYY-MM-DD)
        - `calendarIds`: Array of active calendar IDs (e.g., `['1', '2']`).
    - Search mode:
        - `search`: the search string
        - `limit`: page size (from `options.search.limit`)
        - `offset`: pagination offset (from `options.search.offset`)
        - `calendarIds`: Array of active calendar IDs.

    Example configuration:

    ```
    $('#calendar').bsCalendar({
      url: '/api/appointments'
    });
    ```
2. Function (dynamic)
    Pass a function that receives a `requestData` object (same shape as above) and must return a Promise that resolves to the expected response (array for normal views, or `{ rows, total }` for search). This allows full control over how the data is fetched (e.g., using fetch, adding auth headers, POST requests, local filtering, etc.).

    Example:

    ```
    $('#calendar').bsCalendar({
      url: (requestData) => {
        // requestData contains fromDate/toDate or search pagination depending on mode
        // requestData.calendarIds contains the list of active calendar IDs
        return fetch('/api/appointments?' + new URLSearchParams(requestData), {
          headers: { 'Authorization': 'Bearer ...' }
        }).then(r => r.json());
      }
    });
    ```

Important notes

- If `url` is a string, the plugin uses jQuery.ajax GET requests. Any running request for the same calendar instance will be aborted when a new fetch is started.
- If `url` is a function, it must return a Promise. The calendar will call it and expect a resolved value as described above.
- Use `queryParams` (option) to append or override query parameters before the request is sent. `queryParams` is invoked with the prepared `requestData` and should return an object with extra key/value pairs to be merged into the request.
- For search mode, the plugin sends `search`, `limit`, `offset`, and `calendarIds`. The server should return `{ rows: [...], total:  }`.
- Keep CORS and authentication in mind when calling external APIs from the browser.

Examples serverside contract (summary)

- GET /api/appointments?fromDate=2025-07-01&toDate=2025-07-31&view=month&calendarIds\[\]=1&calendarIds\[\]=2 → JSON array of appointments
- GET /api/appointments?search=john&limit=10&offset=0&calendarIds\[\]=1 → { "rows": \[ ... \], "total": 123 }

### options.formatter

[](#optionsformatter)

The `formatter` object enables advanced customization of various calendar views and components. Each property within `formatter` accepts a function to adjust the display or behavior of the respective calendar component dynamically.

#### Properties

[](#properties)

**Property****Type****Params****Description****day**`function`(appointment, extras)Customizes the rendering of the daily view contents.**week**`function`(appointment, extras)Customizes the rendering of the weekly view contents.**allDay**`function`(appointment, extras, view)Customizes the rendering of the all-day area in weekly or daily view.**month**`function`(appointment, extras)Customizes the rendering of the monthly view contents.**search**`function`(appointment, extras)Formats the search results displayed in the search section.**holiday**`function`(holiday, view)Customizes how holidays are displayed.**window**`Promise`(appointment, extras)Handles the rendering of the information window. This **must** be implemented as a Promise to support asynchronous operations.**duration**`function`(duration)Defines how to calculate and display the duration of appointments or calendar events.---

#### Example Configuration

[](#example-configuration)

```
 $('#calendar').bsCalendar({
    formatter: {
        day(appointment, extras) {
            // console.log(appointment, extras)
            return appointment.title;
        },
        week(appointment, extras) {
            // console.log(appointment, extras)
        },
        month(appointment, extras) {
            // console.log(appointment, extras)
        },
        search(appointment, extras) {
            // console.log(appointment, extras)
        },
        holiday(holiday, view) {
            // console log(holiday, view)
        },
        window: async function (appointment, extras) {
            return new Promise((resolve) => {
                const result = [
                    `${appointment.title}`,
                    `${appointment.description || "Keine Beschreibung verfügbar."}`
                ].join('');
                resolve(result);
            });
        },
        duration(duration) {
            // console.log(duration)
        }
    }
});
```

### The 'extras' object

[](#the-extras-object)

For each appointment, the plugin creates an 'extras' object with additional information.

AttributeDescriptionlocaleLanguage/locale used for display formatting (e.g. date formats).iconIcon class used for the appointment (e.g. Bootstrap Icons class).colors.originSemantic label/origin of the color combination.colors.backgroundColorBackground color for the element (RGBA or HEX).colors.backgroundImageOptional background gradient/image for the element.colors.colorText color appropriate for the background.colors.classListArray of extra CSS classes applied to the element.start.dateAppointment start date (YYYY-MM-DD).start.timeAppointment start time (HH:MM:SS).end.dateAppointment end date (YYYY-MM-DD).end.timeAppointment end time (HH:MM:SS).duration.daysDuration in full days.duration.hoursRemaining duration hours (after counting full days).duration.minutesRemaining duration minutes (after hours).duration.secondsRemaining duration seconds (after minutes).duration.totalMinutesThe absolute number of minutes.duration.totalSecondsThe absolute number of seconds.duration.formattedHuman-friendly short duration (e.g. "1d", "2h 30m").displayDatesList of display/visibility entries (used for month/week views).displayDates\[\].dateSpecific date for this display entry.displayDates\[\].dayWeekday index for the date (0-6).displayDates\[\].times.startVisible start time for this date (or null).displayDates\[\].times.endVisible end time for this date (or null).displayDates\[\].visibleInWeekBoolean flag: visible in week view.displayDates\[\].visibleInMonthBoolean flag: visible in month view.allDayBoolean: whether the appointment is all-day.inADayBoolean: whether the appointment stays within a single day.isTodayBoolean: whether the appointment date is today.isNowBoolean: whether the appointment is currently active.### options.holidays

[](#optionsholidays)

If an object is passed for this option (see structure below), holidays and school holidays will be fetched from the [OpenHolidays API](https://www.openholidaysapi.org/en/).
This option allows configuring the details of the holidays, such as specifying the country, federal state, and language.

- **Automatic Detection**:
    If the `country` or `language` attributes are not explicitly set, their values are automatically determined based on the locale (`options.locale`) of the calendar.
- **Mandatory Field**:
    The `federalState` field is required when fetching school holidays.

#### Configuration Structure:

[](#configuration-structure)

**Key****Type****Default Value****Description****federalState**`null` | `string``null`The federal state identifier (e.g., `DE-BE` for Berlin in Germany). This value is required when fetching school holidays.**country**`null` | `string``null`The country code in ISO 3166-1 alpha-2 format (e.g., `DE` for Germany). A full list of supported countries can be found [here](https://www.openholidaysapi.org/en/sources/).**language**`null` | `string``null`The language code in ISO 639-1 format (e.g., `DE` for German). Determines the language used when fetching holidays.#### Notes

[](#notes)

- **OpenHolidays API Integration:**
    This API serves as the source for holidays and school holidays data. Ensure the configuration matches the requirements of the API (e.g., valid country or state codes).
- **Dynamic Locale Handling:**
    If `country` or `language` are omitted, their values are derived from the calendar's locale setting (specified in `options.locale`).

### options.translations

[](#optionstranslations)

The `options.translations` option allows you to customize the text displayed in the calendar, enabling adaptation to different languages or personal preferences.

#### Configuration Structure:

[](#configuration-structure-1)

**Key****Type****Default Value****Description****search**`string``"Type and press Enter"`The placeholder text displayed in the search input field.**searchNoResult**`string``"No appointment found"`The message displayed when a search query returns no results.#### Notes

[](#notes-1)

- **Localization**:
    This feature is particularly useful for multi-language applications, allowing developers to easily customize text based on user locale or branding needs.

### options.icons

[](#optionsicons)

The `options.icons` configuration allows customization of the icons used in the calendar interface.
By default, icons are defined using the Bootstrap Icons library.

#### Configuration Structure:

[](#configuration-structure-2)

**Key****Bootstrap Icon****Description****day**`"bi bi-calendar-day"`Icon for the day view.**week**`"bi bi-kanban"`Icon for the week view.**month**`"bi bi-calendar-month"`Icon for the month view.**year**`"bi bi-calendar4"`Icon for the year view.**add**`"bi bi-plus-lg"`Icon for the add button.**menu**`"bi bi-list"`Icon for the menu button.**search**`"bi bi-search"`Icon displayed in the search functionality.**prev**`"bi bi-chevron-left"`Icon for the previous navigation button.**next**`"bi bi-chevron-right"`Icon for the next navigation button.**link**`"bi bi-box-arrow-up-right"`Icon used for links associated with the calendar.**appointment**`"bi bi-clock"`Icon representing time-based appointments.**appointmentAllDay**`"bi bi-brightness-high"`Icon representing all-day appointments.#### Notes

[](#notes-2)

- **Default Icon Library**:
    Bootstrap Icons are used as the default icon set. Ensure the appropriate icons are loaded in your project.
- **Customization**:
    Each key can be replaced with a different icon class to align with design requirements or preferences.

---

Attributes for an Appointment
-----------------------------

[](#attributes-for-an-appointment)

### Required Attributes

[](#required-attributes)

1. **`title`**

    - **Description**: The title of the appointment.
    - **Example**: `"Meeting with Bob"`
2. **`start`**

    - **Description**: The starting date and time of the appointment in `YYYY-MM-DD HH:mm:ss` format.
    - **Example**: `"2025-07-01 10:00:00"`
3. **`end`**

    - **Description**: The ending date and time of the appointment in `YYYY-MM-DD HH:mm:ss` format.
    - **Example**: `"2025-07-01 12:00:00"`

### Optional Attributes

[](#optional-attributes)

1. **`id`**

    - **Description**: A unique identifier for the appointment.
    - **Example**: `1`
2. **`description`**

    - **Description**: A detailed description of the appointment.
    - **Example**: `"Discuss project roadmap and deliverables"`
3. **`allDay`**

    - **Description**: Specifies whether the appointment spans the whole day.
    - **Example**: `true` or `false`
4. **`color`**

    - **Description**: The color associated with the appointment. It can be a predefined class (`Bootstrap classes`), a color code (e.g., HEX) or a CSS variable.
    - **Example**: `"primary"`, `"danger"`, `"#FF5733"`, or `"var(--bs-primary)"`
5. **`link`**

    - **Description**: A link associated with the appointment (e.g., an external reference or more details).
    - **Example**: `"https://example.com"`
    - **Extended (Object or String)**:

        - `string`: simple URL. A standard button with default values is created (`text: "Link"`, `target: "_blank"`, `rel: "noopener noreferrer"`). Example: ```
            "https://example.com"
            ```
        - `object`: extended link object with attributes:
            - `href` (required): Destination URL
            - `text` (optional, default: `"Link"`)
            - `target` (optional, default: `"_blank"`)
            - `rel` (optional, default: `"noopener noreferrer"`)
            - `disabled` (optional, default: `false`) – if `true`, adds class `disabled`
            - `html` (optional): if set, this HTML content will be used instead of `text`Example:

            ```
            {
              "href": "https://example.com",
              "text": "Learn more",
              "target": "_self",
              "rel": "nofollow",
              "disabled": false
            }
            ```
    - **Generated markup (simplified)**:

        ```
        [html|text]
        ```
6. **`location`**

    - **Description**: The location of the appointment. It can be:
        - A string: `"Conference Room A"`
        - An array: `["Room 3", "Building 1"]`
        - Or `null` if no location is specified.
7. **`editable`**

    - **Description**: Specifies whether the appointment can be edited.
    - **Example**: `true` or `false`
8. **`deleteable`**

    - **Description**: Specifies whether the appointment can be deleted.
    - **Example**: `true` or `false`

### Reserved Attributes

[](#reserved-attributes)

1. **`extras`**
    - **Description**: An object containing additional information about the appointment.

### Example

[](#example)

```
{
  "id": 123,
  "title": "Project Kickoff Meeting",
  "description": "Initial meeting to discuss project goals, timelines, and responsibilities.",
  "start": "2025-07-01 10:00:00",
  "end": "2025-07-01 12:00:00",
  "allDay": false,
  "color": "#FF5733",
  "link": "https://example.com/meeting-details",
  "location": [
    "Room 5A",
    "Building HQ"
  ],
  "editable": true,
  "deleteable": false
}
```

### Notes

[](#notes-3)

- `start` and `end` times are **mandatory** for creating valid appointments.
- Appointments marked as `allDay: true` do not require specific times, only the start, and the end dates.
- Additional attributes like `id`, `color`, or `link` provide extended functionality, but are not strictly required.
- When handling appointments using the modal in the code, attributes like `title`, `description`, `from_date`, `to_date`, etc., are mapped to respective inputs for user interaction.

---

Triggerable Events
------------------

[](#triggerable-events)

In addition to the configurable callback options like **onAdd**, **onEdit**, and **onNavigateBack**, custom events are available for further flexibility. These events can perform specific actions when certain calendar interactions occur. They follow the naming convention:

```
[event-name].bs.calendar

```

### Available Events and Parameters

[](#available-events-and-parameters)

**Event****Parameters****Description****all.bs.calendar**`eventName, ...params`Triggered for every calendar event.**init.bs.calendar**`-`Triggered after the calendar has been initialized.**add.bs.calendar**`data`Triggered when a new item (e.g., appointment) is added.**edit.bs.calendar**`appointment, extras`Triggered when an appointment or item is edited.**delete.bs.calendar**`appointment, extras`Fired when an appointment is deleted.**view.bs.calendar**`view`Triggered when the calendar view is changed (e.g., from month to week).**navigate-forward.bs.calendar**`view, from, to`Triggered when navigating forwards (e.g., to the next month or year).**navigate-back.bs.calendar**`view, from, to`Fired when navigating backwards (e.g., to the previous month or year).**show-info.bs.calendar**`appointment, extras`Triggered when the information dialog (info window) for an appointment is displayed.**hide-info.bs.calendar**`-`Triggered when the information dialog (info window) is closed.**before-load.bs.calendar**`requestData`Fires before appointment data is retrieved.**after-load.bs.calendar**`appointments`Triggers after the appointments have been loaded and gives them as parameters.### Usage

[](#usage)

JavaScript can be used to listen to these events and take specific actions:

```
$('#calendar').on('view.bs.calendar', function (event, view) {
    console.log("The calendar view has changed to:", view);
});

$('#calendar').on('add.bs.calendar', function (event, data) {
    console.log("A new appointment is to be created", data);
});

$('#calendar').on('navigate-forward.bs.calendar', function (event, view, from, to) {
    console.log(`Navigated forward in view: ${view}, from: ${from}, to: ${to}`);
});
```

### Notes

[](#notes-4)

- **Global Event Handling**: The `all.bs.calendar` event provides a way to handle all events in one place with the `eventName` and its corresponding parameters.
- **Detailed Parameters**: Each event passes specific arguments to provide more detailed contextual information.
- **Flexibility**: These events allow developers to tap into native jQuery event management, enabling robust and custom handling for various use cases.

---

Methods
-------

[](#methods)

The `bsCalendar` plugin offers various methods to dynamically control and interact with the calendar. Here is a list of supported methods with their usage:

### Available Methods

[](#available-methods)

1. **`refresh`**

    - **Description**: Refreshes the calendar and reloads all data.
    - **Usage**: ```
        $('#calendar').bsCalendar('refresh');
        ```
2. **`clear`**

    - **Description**: Clears all content and appointments from the calendar.
    - **Note**: This method is not available in search mode.
    - **Usage**: ```
        $('#calendar').bsCalendar('clear');
        ```
3. **`updateOptions`**

    - **Description**: Updates the calendar's configuration options at runtime.
    - **Parameters**: An object containing options to update.
    - **Usage**: ```
        $('#calendar').bsCalendar('updateOptions', {
            startView: 'month',
            locale: 'en-US'
        });
        ```
4. **`destroy`**

    - **Description**: Completely removes the calendar and restores the original DOM element.
    - **Usage**: ```
        $('#calendar').bsCalendar('destroy');
        ```
5. **`setDate`**

    - **Description**: Sets the provided date as the currently visible reference date in the calendar.
    - **Parameters**: A valid date object or a date string in the `YYYY-MM-DD` format.
    - **Note**: Not available in search mode.
    - **Usage**: ```
        $('#calendar').bsCalendar('setDate', '2025-07-01');
        ```
6. **`setToday`**

    - **Description**: Navigates to and sets today's date as the reference date.
    - **Note**: Not available in search mode.
    - **Usage**: ```
        $('#calendar').bsCalendar('setToday');
        ```

---

Utilities
---------

[](#utilities)

```
// Returns a formatted date using the extra Object
const formattedAppointmentTimespan = $.bsCalendar.utils.getAppointmentTimespanBeautify(extras, withDuration);
console.log(formattedAppointmentTimespan); // Wednesday, October 8th 2:10 p.m.-4:10 p.m. (2h)

// Available countries from the OpenHolidays API
$.bsCalendar.utils.openHolidayApi.getCountries('DE')
    .then(countries => {
        console.log('Countries loaded successfully:', countries);
    })
    .catch(error => {
        console.error('Error while fetching countries:', error.message || error);
    });

// Available languages from the OpenHolidays API
$.bsCalendar.utils.openHolidayApi.getLanguages('DE')
    .then(languages => {
        console.log(languages);
    });

// Available subdivisions (states, regions, etc.)
$.bsCalendar.utils.openHolidayApi.getSubdivisions('DE', 'DE')
    .then(subdivisions => {
        console.log(subdivisions);
    });

// Retrieve school holidays based on state and date range
$.bsCalendar.utils.openHolidayApi.getSchoolHolidays(
    'DE',          // Country (Germany)
    'BE',          // State (Berlin)
    '2025-01-01',  // Start date
    '2025-12-31'   // End date
)
    .then(schoolHolidays => {
        console.log(schoolHolidays);
    })

// Retrieve public holidays based on country, region, language, and date range
$.bsCalendar.utils.openHolidayApi.getPublicHolidays(
    'DE',          // Country (Germany)
    'BE',          // State (Berlin)
    'DE',          // Language
    '2025-01-01',  // Start date
    '2025-12-31'   // End date
)
    .then(publicHolidays => {
        console.log(publicHolidays);
    })

// Convert ICS string to appointments
const icsString = `BEGIN:VCALENDAR
    VERSION:2.0
    BEGIN:VEVENT
    SUMMARY:Team Meeting
    DTSTART:20251126T090000
    DTEND:20251126T100000
    DESCRIPTION:Discussing the Q4 roadmap.
    END:VEVENT
    END:VCALENDAR`;

const appointmentsFromIcs = $.bsCalendar.utils.convertIcsToAppointments(icsString);
console.log(appointmentsFromIcs);
```

---

Feedback, Assistance, or Suggestions
------------------------------------

[](#feedback-assistance-or-suggestions)

I would love to hear your feedback, help improve this project, or learn about your feature requests!
Feel free to [create an issue](https://github.com/ThomasDev-de/bs-calendar/issues) or reach out directly.
Your support and ideas are greatly appreciated!

---

Explore More Projects
---------------------

[](#explore-more-projects)

Feel free to explore my other repositories: [ThomasDev-de on GitHub](https://github.com/ThomasDev-de?tab=repositories)

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance86

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Total

31

Last Release

62d ago

Major Versions

1.2.12 → 2.0.02025-10-31

### Community

Maintainers

![](https://www.gravatar.com/avatar/6d5f10c16b4b6bd1ac531ffc39c23c569490ec4630829511692c03ec89d36a11?d=identicon)[thomasK81](/maintainers/thomasK81)

---

Top Contributors

[![ThomasDev-de](https://avatars.githubusercontent.com/u/67106837?v=4)](https://github.com/ThomasDev-de "ThomasDev-de (304 commits)")

---

Tags

bootstrap5calendarcalendar-eventscalendar-viewjqueryschedulerpluginuieventsjquerycalendarbootstrapbootstrap5Bootstrap Icons

### Embed Badge

![Health badge](/badges/webcito-bs-calendar/health.svg)

```
[![Health](https://phpackages.com/badges/webcito-bs-calendar/health.svg)](https://phpackages.com/packages/webcito-bs-calendar)
```

###  Alternatives

[onokumus/metismenu

A jQuery menu plugin

2.0k263.3k5](/packages/onokumus-metismenu)[techlab/smartwizard

The awesome jQuery step wizard plugin

79096.2k2](/packages/techlab-smartwizard)[serhioromano/bootstrap-calendar

Bootstrap full view calendar.

3.0k5.9k2](/packages/serhioromano-bootstrap-calendar)[kartik-v/yii2-widget-rating

A Yii2 widget for the simple yet powerful bootstrap-star-rating plugin with fractional rating support (sub repo split from yii2-widgets)

444.1M8](/packages/kartik-v-yii2-widget-rating)[execut/yii2-widget-bootstraptreeview

Bootstrap Tree View widget wrapper for yii2

46170.2k](/packages/execut-yii2-widget-bootstraptreeview)[datatables.net/datatables.net-bs5

DataTables is a plug-in for the jQuery Javascript library. It is a highly flexible tool, based upon the foundations of progressive enhancement, which will add advanced interaction controls to any HTML table. This is DataTables with styling for \[Bootstrap5\](https://getbootstrap.com/)

2185.7k16](/packages/datatablesnet-datatablesnet-bs5)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)