HST Ethiopian Date Picker

HST Ethiopian Date Picker is a React component library that delivers synchronized Ethiopian and Gregorian calendar experiences on top of Material UI. It includes a polished date picker, a read-only viewer, and a localization layer that helps teams support Amharic, Afan Oromo, or fully custom month labels while preserving a familiar UX for international users.

Key Features

• Dual-calendar popover displaying Ethiopian and Gregorian months side by side
• Controlled and uncontrolled usage patterns with first-class TypeScript support
• Optional locale switcher within the text field or viewer component
• Built-in conversion utilities for moving between Ethiopian and Gregorian dates
• Fine-grained configuration for disabling past/future dates and setting min/max bounds
• Tested with React 18 and 19, Material UI v6, and the latest @mui/x-date-pickers

Installation

npm install hst-ethiopian-datepicker
# or
yarn add hst-ethiopian-datepicker

Peer dependencies: react, react-dom, @mui/material, @mui/icons-material, @mui/x-date-pickers, @emotion/react, and @emotion/styled. Ensure they are already present in your host application.

Quick Start

import { useState } from "react";
import HstDatePicker, {
	HstLocalizationProvider,
	HstDateViewer,
} from "hst-ethiopian-datepicker";

export default function Example() {
	const [date, setDate] = useState<Date | null>(new Date());

	return (
		<HstLocalizationProvider locale="AMH">
			<HstDatePicker
				label="Document Date"
				value={date}
				onChange={(selected) => setDate(selected)}
			/>

			{date && (
				<HstDateViewer
					mt={2}
					date={date}
					showTime
					fontWeight={600}
				/>
			)}
		</HstLocalizationProvider>
	);
}

Core Components

HstDatePicker

Material UI TextField with an Ethiopian and Gregorian calendar popover.

| Prop | Type | Notes | | --- | --- | --- | | value | Date \| null | Controlled Gregorian value. | | defaultValue | Date | Optional uncontrolled initial value. | | onChange | (date: Date) => void | Fired when the user selects a day. | | disablePast | boolean | Prevents selection of days before today. | | disableFuture | boolean | Prevents selection of days after today. | | minDate / maxDate | Date | Hard bounds applied to both calendars. | | ...TextFieldProps | from MUI | Pass label, helperText, size, etc. |

HstDateViewer

Read-only component for displaying localized Ethiopian or Gregorian dates.

| Prop | Type | Notes | | --- | --- | --- | | date | Date | Required Gregorian source date. | | initialDateType | "EN" \| "AMH" \| "AO" \| "CUSTOM" | Defaults to provider locale. | | disableSwitcher | boolean | Locks the viewer to a single locale. | | showTime | boolean | Adds 12-hour time to the output. | | ...TypographyProps | from MUI | Style the output text. |

Localization Provider

Wrap your app (or specific sections) in HstLocalizationProvider to define locale defaults and toggle features:

<HstLocalizationProvider
	locale="AO"
	getLocalMonthName={(monthNumber) => customMonthMap[monthNumber]}
	disableEt={false}
	disableGregorian={false}
	disableSwitcher={false}
>
	{children}
</HstLocalizationProvider>

• locale: "AMH", "AO", "CUSTOM", or "EN".
• getLocalMonthName: required when using CUSTOM to supply localized names (1-indexed months).
• disableEt / disableGregorian: hide either side of the calendar UI.
• disableSwitcher: lock inputs and viewers to the default locale.

Calendar Modes

Choose the calendar experience you expose to users by mixing the provider flags:

// Dual-calendar (default)
<HstLocalizationProvider locale="AMH">
	<HstDatePicker ... />
</HstLocalizationProvider>

// English-only (Gregorian)
<HstLocalizationProvider locale="EN" disableEt disableSwitcher>
	<HstDatePicker ... />
</HstLocalizationProvider>

// Amharic-only (Ethiopian)
<HstLocalizationProvider locale="AMH" disableGregorian disableSwitcher>
	<HstDatePicker ... />
</HstLocalizationProvider>

Omit disableSwitcher if you still want the input toggle icon visible while only one calendar is available.

Conversion Utilities

The library re-exports the EthiopianDate namespace as EthiopianDateUtil for direct consumption:

• toEth(date: Date) converts Gregorian dates to { Day, Month, Year }.
• toGreg(etDate) returns a native Date from Ethiopian parts.
• formatEtDate(etDate, locale, getLocalMonth?, time?) returns localized strings.
• Additional helpers: ethiopianMonthLength, compareDates, addDays, addYears, fullEthiopianYearDifference, and more.

Local Development

Clone the repository and build the package locally:

npm install
npm run build

An embedded Next.js playground under testdate lets you experiment while developing:

cd testdate
npm install
npm run dev

Visit http://localhost:3000 to interact with the components in a live app context.

Publishing Workflow

The project uses tsup to emit ESM, CJS, and type declaration bundles. Run npm run build prior to npm publish to ensure the dist/ folder contains up-to-date artifacts.

License

ISC