feat(datepicker): add dateFormat prop

apps/web/content/docs/components/datepicker.mdx

@@ -27,6 +27,12 @@ The `labelTodayButton` and `labelClearButton` can also be used to update the tex
 
 <Example name="datepicker.localization" />
 
+## Date format
+
+Use the `dateFormat` prop to customize how the selected date is displayed in the input. It accepts [Intl.DateTimeFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) and combines with the `language` prop, so the same options render locale-appropriate output — the example shows `15/01/2026` for `en-GB`, while `en` renders `01/15/2026`.
+
+<Example name="datepicker.format" />
+
 ## Filter dates
 
 You can use the `filterDate` prop to filter out specific dates from the datepicker component. This is useful if you want to disable certain dates or only allow selection of weekdays, for example.

apps/web/examples/datepicker/datepicker.format.tsx

@@ -0,0 +1,37 @@
+import { Datepicker } from "flowbite-react";
+import type { CodeData } from "~/components/code-demo";
+
+const code = `
+import { Datepicker } from "flowbite-react";
+
+export function Component() {
+  return (
+    <Datepicker
+      defaultValue={new Date(2026, 0, 15)}
+      language="en-GB"
+      dateFormat={{ day: "2-digit", month: "2-digit", year: "numeric" }}
+    />
+  );
+}
+`;
+
+export function Component() {
+  return (
+    <Datepicker
+      defaultValue={new Date(2026, 0, 15)}
+      language="en-GB"
+      dateFormat={{ day: "2-digit", month: "2-digit", year: "numeric" }}
+    />
+  );
+}
+
+export const format: CodeData = {
+  type: "single",
+  code: {
+    fileName: "index",
+    language: "tsx",
+    code,
+  },
+  githubSlug: "datepicker/datepicker.format.tsx",
+  component: <Component />,
+};

apps/web/examples/datepicker/index.ts

@@ -1,4 +1,5 @@
 export { autoHide } from "./datepicker.autoHide";
+export { format } from "./datepicker.format";
 export { inline } from "./datepicker.inline";
 export { localization } from "./datepicker.localization";
 export { filter } from "./datepicker.filter";

packages/ui/src/components/Datepicker/Datepicker.test.tsx

@@ -15,6 +15,29 @@ describe("Components / Datepicker", () => {
     expect(screen.getByDisplayValue(todaysDateInDefaultLanguage)).toBeInTheDocument();
   });
 
+  it("should format the input value with the given `dateFormat`", () => {
+    render(
+      <Datepicker
+        defaultValue={new Date(2023, 0, 15)}
+        dateFormat={{ day: "2-digit", month: "2-digit", year: "numeric" }}
+      />,
+    );
+
+    expect(screen.getByDisplayValue("01/15/2023")).toBeInTheDocument();
+  });
+
+  it("should format the input value with the given `dateFormat` and `language`", () => {
+    render(
+      <Datepicker
+        defaultValue={new Date(2023, 0, 15)}
+        language="en-GB"
+        dateFormat={{ day: "2-digit", month: "2-digit", year: "numeric" }}
+      />,
+    );
+
+    expect(screen.getByDisplayValue("15/01/2023")).toBeInTheDocument();
+  });
+
   it("should update date when a different day is clicked", async () => {
     const todaysDayOfMonth = new Date().getDate();
     const anotherDay = todaysDayOfMonth === 1 ? 2 : 1;

packages/ui/src/components/Datepicker/Datepicker.tsx

@@ -102,6 +102,7 @@ export interface DatepickerProps
   minDate?: Date;
   maxDate?: Date;
   filterDate?: (date: Date, view: Views) => boolean;
+  dateFormat?: Intl.DateTimeFormatOptions;
   language?: string;
   weekStart?: WeekStart;
   onChange?: (date: Date | null) => void;
@@ -130,6 +131,7 @@ export const Datepicker = forwardRef<DatepickerRef, DatepickerProps>((props, ref
     minDate,
     maxDate,
     filterDate,
+    dateFormat,
     language = "en",
     weekStart = WeekStart.Sunday,
     className,
@@ -271,7 +273,7 @@ export const Datepicker = forwardRef<DatepickerRef, DatepickerProps>((props, ref
     }
   }, [value, setSelectedDate, setViewDate, selectedDate]);
 
-  const displayValue = value === null ? label : getFormattedDate(language, selectedDate || new Date());
+  const displayValue = value === null ? label : getFormattedDate(language, selectedDate || new Date(), dateFormat);
 
   return (
     <DatepickerContext.Provider
@@ -306,7 +308,7 @@ export const Datepicker = forwardRef<DatepickerRef, DatepickerProps>((props, ref
               setIsOpen(true);
             }}
             value={displayValue}
-            defaultValue={initialDate ? getFormattedDate(language, initialDate) : label}
+            defaultValue={initialDate ? getFormattedDate(language, initialDate, dateFormat) : label}
             readOnly
             {...restProps}
           />

packages/ui/src/components/Datepicker/helpers.test.tsx

@@ -170,6 +170,77 @@ describe("getFormattedDate", () => {
     const formattedDate = getFormattedDate("pt-BR", date);
     expect(formattedDate).toBe("15 de janeiro de 2023");
   });
+
+  it("keeps the selected calendar day when formatting in another timeZone", () => {
+    const date = new Date(2023, 0, 15); // January 15th, 2023
+    const options: Intl.DateTimeFormatOptions = { timeZone: "UTC", day: "2-digit", month: "2-digit", year: "numeric" };
+    const formattedDate = getFormattedDate("en", date, options);
+    expect(formattedDate).toBe("01/15/2023");
+  });
+
+  it("keeps the selected calendar day at month boundaries in far-ahead time zones", () => {
+    const date = new Date(2026, 0, 31); // January 31st, 2026
+    const options: Intl.DateTimeFormatOptions = {
+      timeZone: "Pacific/Kiritimati",
+      day: "2-digit",
+      month: "2-digit",
+      year: "numeric",
+    };
+    const formattedDate = getFormattedDate("en", date, options);
+    expect(formattedDate).toBe("01/31/2026");
+  });
+
+  it("keeps years 0-99 when formatting in another timeZone", () => {
+    const date = new Date(0);
+    date.setFullYear(5, 0, 15); // January 15th, year 5
+    const formattedDate = getFormattedDate("en-US", date, {
+      timeZone: "UTC",
+      day: "numeric",
+      month: "numeric",
+      year: "numeric",
+    });
+    expect(formattedDate).toBe("1/15/5");
+  });
+
+  it("keeps BCE dates on the selected calendar day when formatting in another timeZone", () => {
+    const date = new Date(0);
+    date.setFullYear(-1, 0, 15); // January 15th, 2 BC
+    const formattedDate = getFormattedDate("en-US", date, {
+      timeZone: "UTC",
+      day: "numeric",
+      month: "numeric",
+      year: "numeric",
+    });
+    expect(formattedDate).toBe("1/15/2");
+  });
+
+  it("keeps the time from the date when time fields are used with a timeZone", () => {
+    const date = new Date(2023, 0, 15, 14, 30);
+    const formattedDate = getFormattedDate("en-US", date, { timeZone: "UTC", hour: "numeric", minute: "numeric" });
+    expect(formattedDate).toBe("2:30 PM");
+  });
+
+  it("shows the selected wall time in the requested timeZone", () => {
+    const date = new Date(2023, 0, 15, 14, 30);
+    const formattedDate = getFormattedDate("en-US", date, {
+      timeZone: "America/New_York",
+      hour: "numeric",
+      minute: "numeric",
+    });
+    expect(formattedDate).toBe("2:30 PM");
+  });
+
+  it("formats the maximum Date without throwing when a timeZone is set", () => {
+    const date = new Date(8.64e15);
+    const expected = `${date.getMonth() + 1}/${date.getDate()}/${date.getFullYear()}`;
+    const formattedDate = getFormattedDate("en-US", date, { timeZone: "UTC" });
+    expect(formattedDate).toBe(expected);
+  });
+
+  it("does not throw when the timeZone correction overflows at the maximum Date", () => {
+    const formattedDate = getFormattedDate("en-US", new Date(8.64e15), { timeZone: "America/New_York" });
+    expect(typeof formattedDate).toBe("string");
+  });
 });
 
 describe("startOfYearPeriod", () => {

packages/ui/src/components/Datepicker/helpers.ts

@@ -119,7 +119,63 @@ export function getFormattedDate(language: string, date: Date, options?: Intl.Da
     defaultOptions = options;
   }
 
-  return new Intl.DateTimeFormat(language, defaultOptions).format(date);
+  const formatter = new Intl.DateTimeFormat(language, defaultOptions);
+
+  if (!defaultOptions.timeZone) {
+    return formatter.format(date);
+  }
+
+  const zonedDateFormatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: defaultOptions.timeZone,
+    era: "short",
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hour12: false,
+  });
+
+  // The date is a local wall clock. Anchor the same wall time at UTC so most
+  // zone offsets keep the selected calendar day, then correct the remaining
+  // offsets by shifting the instant until the zoned wall clock matches.
+  let anchored = new Date(0);
+  anchored.setUTCFullYear(date.getFullYear(), date.getMonth(), date.getDate());
+  anchored.setUTCHours(date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+
+  if (Number.isNaN(anchored.getTime())) {
+    // Only reachable near the maximum Date, where the instant cannot represent
+    // the local day in every zone; format the date as-is.
+    return formatter.format(date);
+  }
+
+  for (let i = 0; i < 3; i++) {
+    const parts = new Map(zonedDateFormatter.formatToParts(anchored).map((part) => [part.type, part.value]));
+    const zonedYear = (parts.get("era") ?? "").startsWith("B")
+      ? 1 - Number(parts.get("year"))
+      : Number(parts.get("year"));
+    const zonedWall = new Date(0);
+    zonedWall.setUTCFullYear(zonedYear, Number(parts.get("month")) - 1, Number(parts.get("day")));
+    zonedWall.setUTCHours(Number(parts.get("hour")) % 24, Number(parts.get("minute")), Number(parts.get("second")), 0);
+    const targetWall = new Date(0);
+    targetWall.setUTCFullYear(date.getFullYear(), date.getMonth(), date.getDate());
+    targetWall.setUTCHours(date.getHours(), date.getMinutes(), date.getSeconds(), 0);
+
+    const diff = zonedWall.getTime() - targetWall.getTime();
+
+    if (diff === 0) {
+      return formatter.format(anchored);
+    }
+
+    const shifted = new Date(anchored.getTime() - diff);
+    if (Number.isNaN(shifted.getTime())) {
+      return formatter.format(date);
+    }
+    anchored = shifted;
+  }
+
+  return formatter.format(anchored);
 }
 
 export function startOfYearPeriod(date: Date, years: number): number {