jb-calendar

Jalali and Gregorian calendar interface web component.

• Supports Jalali and Gregorian date selection.
• Supports day, month, and year selection views.
• Supports min/max date restrictions.
• Supports Persian digit rendering.
• Supports RTL and LTR layout.
• Customizable with CSS variables.

When to use

Use jb-calendar when you need an inline calendar picker UI.

Use jb-date-input when you need a full date input field with label, validation, text entry, and form input behavior.

Demo

• Demo
• CodePen

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm install jb-calendar

import 'jb-calendar';

<jb-calendar></jb-calendar>

API reference

Attributes

jb-calendar does not currently define public HTML attributes. Configure it with properties and methods.

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | JBCalendarValue | no | Selected date in the active inputType. Set year, month, and day together. Demo | | inputType | 'JALALI' \| 'GREGORIAN' | no | Calendar date system used for input and displayed values. Jalali Demo · Gregorian Demo | | activeSection | 'DAY' \| 'MONTH' \| 'YEAR' | no | Visible selection section. | | showPersianNumber | boolean | no | Renders numbers with Persian digits when true. Demo | | direction | 'rtl' \| 'ltr' | no | Calendar layout direction. Leave unset to use computed CSS direction. RTL Demo | | cssDirection | 'rtl' \| 'ltr' | yes | Computed CSS direction of the host. | | defaultCalendarData | { jalali, gregorian } | no | Default visible year/month used when no date is selected. Demo | | dateRestrictions | { min: Date \| null; max: Date \| null } | no | Mutable min/max date restriction object. Set dateRestrictions.min and dateRestrictions.max. Demo | | data | JBCalendarData | no | Internal visible calendar state: selectedYear, selectedMonth, and yearSelectionRange. |

type JBCalendarValue = {
  year: number | null;
  month: number | null;
  day: number | null;
};

Methods

| name | returns | description | | --- | --- | --- | | select(year, month, day) | void | Selects a date in the current inputType and updates value. Demo | | selectToday() | void | Selects today in the current inputType. Demo | | setMonthList(inputType, monthList) | void | Replaces the 12 month labels for JALALI or GREGORIAN. Demo | | setupStyleBaseOnCssDirection(dir?) | void | Refreshes direction-sensitive layout classes from dir or computed host direction. Demo | | checkIsDayDisable(dayDate) | { min; max; isAllValid } | Checks whether a Date is valid against min/max restrictions. Demo |

Events

| event | detail | description | | --- | --- | --- | | init | none | Dispatched during construction after default properties are initialized. | | load | none | Dispatched from connectedCallback before layout initialization. | | select | none | Dispatched when the user selects an enabled day. Read event.target.value. Demo |

const calendar = document.querySelector('jb-calendar');

calendar.addEventListener('select', (event) => {
  console.log(event.target.value);
});

Select a date

Use select() or set value to choose a date programmatically; see the imperative selection Demo. User selection events expose the date through event.target.value; see the selection event Demo.

const calendar = document.querySelector('jb-calendar');

calendar.select(1402, 8, 24);
console.log(calendar.value); // { year: 1402, month: 8, day: 24 }

You can also set value directly:

calendar.value = {
  year: 2026,
  month: 6,
  day: 16,
};

Jalali and Gregorian input

Set inputType to JALALI or GREGORIAN; see the Jalali Demo or Gregorian Demo.

const calendar = document.querySelector('jb-calendar');

calendar.inputType = 'GREGORIAN';
calendar.select(2026, 6, 16);

Default visible month

defaultCalendarData controls the year and month shown before the user selects a date. Configure it before connecting the element so the initial layout uses the supplied month.

defaultCalendarData configuration is shown in the configured initial-month Demo.

const calendar = document.createElement('jb-calendar');

calendar.defaultCalendarData = {
  gregorian: {
    year: 2026,
    month: 6,
  },
  jalali: {
    year: 1405,
    month: 3,
  },
};

document.body.append(calendar);

Persian numbers

Set showPersianNumber to render Persian digits; see the Persian-digit Demo.

document.querySelector('jb-calendar').showPersianNumber = true;

Min and max restrictions

Set restrictions with JavaScript Date objects. The dates are compared against the currently rendered date system internally; see the restricted date-range Demo.

const calendar = document.querySelector('jb-calendar');

calendar.dateRestrictions.min = new Date(2026, 0, 1);
calendar.dateRestrictions.max = new Date(2026, 11, 31);

Change month labels

Use setMonthList with exactly 12 labels; see the custom Jalali month-label Demo.

const calendar = document.querySelector('jb-calendar');

calendar.setMonthList('JALALI', [
  'حمل',
  'ثور',
  'جوزا',
  'سرطان',
  'اسد',
  'سنبله',
  'میزان',
  'عقرب',
  'قوس',
  'جدی',
  'دلو',
  'حوت',
]);

calendar.setMonthList('GREGORIAN', [
  '1',
  '2',
  '3',
  '4',
  '5',
  '6',
  '7',
  '8',
  '9',
  '10',
  '11',
  '12',
]);

Direction

The component reads CSS direction when it mounts. If your app changes direction after mount, call setupStyleBaseOnCssDirection() or set direction; see the RTL Jalali Demo or RTL Gregorian Demo.

const calendar = document.querySelector('jb-calendar');

calendar.setupStyleBaseOnCssDirection();
calendar.setupStyleBaseOnCssDirection('ltr');
calendar.direction = 'rtl';

Slots and CSS parts

jb-calendar does not currently expose public slots. It exposes CSS parts for navigator, day, month, year, and swipe-up hint internals; see Styling and the CSS-part styling Demo.

Custom style

Set CSS variables in the parent scope of the component.

For complete styling guidance, live examples, and copyable style recipes, see Styling and the style gallery Demo.

jb-calendar {
  --jb-calendar-day-bg-color-selected: var(--jb-primary);
  --jb-calendar-day-color-selected: var(--jb-white);
}

Accessibility notes

• Navigator buttons have localized title attributes; inspect the interactive calendar Demo.
• Day, month, and year choices are rendered as clickable elements inside shadow DOM.
• The component is an inline calendar UI, not a form-associated input. Use jb-date-input when native form input behavior is required.

Dependencies

jb-calendar uses date-fns and date-fns-jalali for Gregorian and Jalali date calculations.

Related Docs

• See jb-calendar/react if you want to use this component in React.
• See All JB Design System Component List for more components.
• Use Contribution Guide if you want to contribute to this component.

AI agent notes

• Import jb-calendar once before using <jb-calendar>.
• Configure the component with properties and methods; it does not expose public HTML attributes.
• Use inputType = 'JALALI' or inputType = 'GREGORIAN' before setting/selecting values when the date system matters.
• Listen to select and read event.target.value; the event does not include selected date data in event.detail.
• Use dateRestrictions.min and dateRestrictions.max with JavaScript Date objects.
• Use jb-date-input instead of jb-calendar when a form-associated date input field is needed.
• This package includes custom-elements.json and points to it with the package.json customElements field. The field is documented by the Custom Elements Manifest project in Referencing manifests from npm packages.
• In custom-elements.json, exports.kind: "js" describes the JavaScript/TypeScript class export and exports.kind: "custom-element-definition" maps the jb-calendar tag name to that class.