Par3aa.PersianDatePicker 1.0.1

PersianDatePicker

A Blazor Razor Class Library providing a Persian (Jalali) date picker built on System.Globalization.PersianCalendar. It supports binding to DateTime and DateTime?, two input modes (dropdowns or numeric inputs), and global defaults configured once per application.

Features

• 📅 Persian (Jalali) calendar via System.Globalization.PersianCalendar
• 🔁 Two-way binding for DateTime and DateTime?
• 🔽 DropDown mode or 🔢 TextBox mode
• 📆 Configurable year range with automatic normalization
• 🧰 Optional Today and Clear actions
• ⚙️ Global defaults (PersianDatePicker.Defaults) so parameters aren’t repeated in every instance
• 🎨 Minimal CSS; integrates cleanly with popular UI libraries
• ♿ Accessibility-conscious (ARIA and focus handling)
• 🧩 Customizable SVG icons

Installation

dotnet add package Par3aa.PersianDatePicker

Getting Started

Add the namespace:

@using Par3aa

Bind to DateTime:

<PersianDatePicker TValue="DateTime"
                   @bind-Value="MyDate"
                   SelectionMode="PersianDatePicker.SelectionMode.DropDown"
                   ShowTodayButton="true"
                   StartYear="1350"
                   EndYear="1450" />

Bind to DateTime? (nullable):

<PersianDatePicker TValue="DateTime?"
                   @bind-Value="MyNullableDate"
                   SelectionMode="PersianDatePicker.SelectionMode.TextBox"
                   ShowClearButton="true"
                   ShowTodayButton="true" />

ShowClearButton is valid only when bound to DateTime?.

Configure Once, Use Everywhere

Set global defaults at application startup:

using Par3aa;

// Example defaults
PersianDatePicker.Defaults.SelectionMode = PersianDatePicker.SelectionMode.DropDown;
PersianDatePicker.Defaults.ShowTodayButton = true;
PersianDatePicker.Defaults.ShowClearButton = true;
PersianDatePicker.Defaults.StartYear = 1320;
PersianDatePicker.Defaults.EndYear = PersianCalendar.GetYear(DateTime.Today);

// Optional styling defaults
PersianDatePicker.Defaults.InputClass = "my-input";
PersianDatePicker.Defaults.ButtonClass = "my-button";
PersianDatePicker.Defaults.Style = "border: 1px solid #e6e6e6; border-radius: 6px;";
PersianDatePicker.Defaults.Color = "slategray";

Any instance parameter overrides the corresponding default.

Color and Theming

Button and icon color is driven by a CSS variable with a broad fallback chain across popular frameworks:

:root {
  --button-color:
    var(--rz-primary,               /* Radzen */
    var(--mud-palette-primary,      /* MudBlazor */
    var(--kendo-color-primary,      /* Kendo/Telerik */
    var(--e-primary-color,          /* Syncfusion */
    var(--dxbl-primary,             /* DevExpress Blazor */
    var(--bs-primary,               /* Blazorise / Bootstrap */
    #7f00ff                         /* Fallback (Blazor violet) */
  )))));
}

Icons use fill="currentColor", so they inherit --button-color. You can add fill="currentColor" to your own SVG files to have them inherit the color dynamically too.

• Set per instance:

  <PersianDatePicker TValue="DateTime?"
                     @bind-Value="MyNullableDate"
                     Color="#2d6a4f"  
                     ShowClearButton="true"
                     ShowTodayButton="true" />
  

• Set globally:

  PersianDatePicker.Defaults.Color = "#2d6a4f";
  

• Customize icons (globally or per instance) by supplying inline SVG:

  PersianDatePicker.Defaults.TodayIcon = "<svg ... fill=\"currentColor\">...</svg>";
  PersianDatePicker.Defaults.ClearIcon = "<svg ... fill=\"currentColor\">...</svg>";
  

Accessibility

• aria-label and aria-disabled on interactive elements
• tabindex set to -1 when not interactive
• Native inputs that support keyboard navigation
• Invalid date combinations revert to last valid value

API Overview

Key parameters:

Selected parts (two-way binding):

Tooltips:

How To Use

Option 1: Build and pack locally

dotnet pack -c Release

Option 2: Install from NuGet

dotnet add package Par3aa.PersianDatePicker

License

MIT License file available in root directory.