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

• Storybook
• CodePen

Using With JS Frameworks

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. | | inputType | 'JALALI' \| 'GREGORIAN' | no | Calendar date system used for input and displayed values. | | activeSection | 'DAY' \| 'MONTH' \| 'YEAR' | no | Visible selection section. | | showPersianNumber | boolean | no | Renders numbers with Persian digits when true. | | direction | 'rtl' \| 'ltr' | no | Calendar layout direction. Leave unset to use computed CSS direction. | | cssDirection | 'rtl' \| 'ltr' | yes | Computed CSS direction of the host. | | defaultCalendarData | { jalali, gregorian } | no | Default visible year/month used when no date is selected. | | dateRestrictions | { min: Date \| null; max: Date \| null } | no | Mutable min/max date restriction object. Set dateRestrictions.min and dateRestrictions.max. | | 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. | | selectToday() | void | Selects today in the current inputType. | | setMonthList(inputType, monthList) | void | Replaces the 12 month labels for JALALI or GREGORIAN. | | setupStyleBaseOnCssDirection(dir?) | void | Refreshes direction-sensitive layout classes from dir or computed host direction. | | checkIsDayDisable(dayDate) | { min; max; isAllValid } | Checks whether a Date is valid against min/max restrictions. |

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. |

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

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

Select a date

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.

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.

document.querySelector('jb-calendar').defaultCalendarData = {
  gregorian: {
    year: 2026,
    month: 6,
  },
  jalali: {
    year: 1405,
    month: 3,
  },
};

Persian numbers

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.

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.

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.

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.

Custom style

Set CSS variables in the parent scope of the component.

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

jb-calendar {
  --jb-calendar-day-bg-color-selected: var(--jb-primary);
  --jb-calendar-day-color-selected: var(--jb-white);
  --jb-calendar-arrow-button-border-radius: 62.4375rem;
}

Accessibility notes

• Navigator buttons have localized title attributes.
• 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.