Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(date): add weekStartsOn to DateInput, DateRangeInput, DateTimeInput (#4745)

freddymeta2ee5dc47b5ed
diff --git a/.changeset/date-week-start.md b/.changeset/date-week-start.md
new file mode 100644
index 0000000000..ef3fa0e3ca
--- /dev/null
+++ b/.changeset/date-week-start.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] DateInput, DateRangeInput, and DateTimeInput now accept a `weekStartsOn` prop that sets the first day of the week in the calendar popover (0 = Sunday … 6 = Saturday, or a three-letter day name like `"mon"`). It forwards to the underlying Calendar, whose default stays Sunday, so existing usage is unchanged.
+@freddymeta
diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsx
index 93b89640de..ccf81fd20e 100644
--- a/apps/storybook/stories/DateInput.stories.tsx
+++ b/apps/storybook/stories/DateInput.stories.tsx
@@ -58,6 +58,27 @@ const meta: Meta<typeof DateInput> = {
options: [1, 2],
description: 'Number of months to display in calendar',
},
+ weekStartsOn: {
+ control: 'select',
+ options: [
+ 0,
+ 1,
+ 2,
+ 3,
+ 4,
+ 5,
+ 6,
+ 'sun',
+ 'mon',
+ 'tue',
+ 'wed',
+ 'thu',
+ 'fri',
+ 'sat',
+ ],
+ description:
+ 'First day of week in the calendar popover (0 = Sunday, or a three-letter day name)',
+ },
format: {
control: 'select',
options: ['date_long', 'date', 'date_weekday', 'system_date'],
@@ -93,6 +114,19 @@ export const WithValue: Story = {
},
};
+export const MondayFirstWeek: Story = {
+ name: 'Week starts on Monday',
+ render: args => {
+ const [value, setValue] = useState<ISODateString | undefined>(undefined);
+ return <DateInput {...args} value={value} onChange={setValue} />;
+ },
+ args: {
+ label: 'Date',
+ placeholder: 'Select a date',
+ weekStartsOn: 'mon',
+ },
+};
+
/**
* The committed date value can be rendered in different shapes via `format`,
* reusing `Timestamp`'s format vocabulary so the same literal renders the same
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index 7f46de22c3..e043eb8fbb 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -142,6 +142,13 @@ export const docs = {
'Number of months displayed simultaneously in the calendar popover.',
default: '1',
},
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description:
+ 'First day of week in the calendar popover. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',
+ default: '0',
+ },
{
name: 'format',
type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
@@ -417,6 +424,12 @@ export const docsZh = {
description: '日历弹出层中同时显示的月份数量。',
default: '1',
},
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description: '日历弹出层中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',
+ default: '0',
+ },
{
name: 'format',
type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
@@ -520,6 +533,7 @@ export const docsDense = {
labelTooltip: 'tooltip text via info icon at label end',
hasClear: 'Shows clear button when date is set. Clears value on click.',
numberOfMonths: 'months shown simultaneously in calendar popover',
+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
format:
"committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
xstyle: 'StyleX styles for layout; must be stylex.create() value',
diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsx
index 88d40c00a2..305247876c 100644
--- a/packages/core/src/DateInput/DateInput.test.tsx
+++ b/packages/core/src/DateInput/DateInput.test.tsx
@@ -949,6 +949,61 @@ describe('DateInput', () => {
expect(screen.getByDisplayValue('Mar 10, 2026')).toBeInTheDocument();
});
});
+ describe('weekStartsOn', () => {
+ // The calendar popover renders in the top layer; jsdom keeps the content in
+ // the DOM but role queries skip it, so read the columnheaders directly.
+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {
+ fireEvent.keyDown(screen.getByRole('combobox'), {key: 'ArrowDown'});
+ return Array.from(container.querySelectorAll('[role="columnheader"]'))
+ .slice(0, 7)
+ .map(h => h.textContent);
+ };
+
+ it('defaults to a Sunday-first week', () => {
+ const {container} = render(
+ <DateInput label="Date" onChange={() => {}} />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Su',
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ ]);
+ });
+
+ it('forwards a numeric weekStartsOn to the calendar', () => {
+ const {container} = render(
+ <DateInput label="Date" onChange={() => {}} weekStartsOn={1} />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+
+ it('accepts a three-letter day name', () => {
+ const {container} = render(
+ <DateInput label="Date" onChange={() => {}} weekStartsOn="mon" />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+ });
});
describe('DateInput statusVariant forwarding', () => {
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index 3170d1888c..c652c9aafc 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -48,7 +48,13 @@ import {useInputGroup} from '../InputGroup/InputGroupContext';
import {groupStyles} from '../InputGroup/groupStyles';
import {useSize} from '../SizeContext/SizeContext';
import {Spinner} from '../Spinner';
-import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
+import {
+ Calendar,
+ type ISODateString,
+ type CalendarHandle,
+ type DayOfWeek,
+ type DayOfWeekName,
+} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {usePopover} from '../Popover';
@@ -311,6 +317,14 @@ export interface DateInputProps extends Omit<
*/
numberOfMonths?: 1 | 2;
+ /**
+ * First day of week in the calendar popover. Accepts a number
+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
+ * case-insensitive).
+ * @default 0
+ */
+ weekStartsOn?: DayOfWeek | DayOfWeekName;
+
/**
* How the committed date value is displayed in the text field. Accepts a
* named format reused from `Timestamp`'s `format` vocabulary (so the same
@@ -377,6 +391,7 @@ export function DateInput({
labelTooltip,
hasClear = false,
numberOfMonths = 1,
+ weekStartsOn,
format = 'date_long',
width,
xstyle,
@@ -754,6 +769,7 @@ export function DateInput({
max={max}
dateConstraints={dateConstraints}
numberOfMonths={numberOfMonths}
+ weekStartsOn={weekStartsOn}
/>,
{placement: 'below', alignment: 'start'},
)}
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
index 3ba5fbb347..396fbc3857 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs
@@ -145,6 +145,13 @@ export const docs = {
description: 'Number of months in the calendar.',
default: '2',
},
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description:
+ 'First day of week in the calendar. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',
+ default: '0',
+ },
{
name: 'width',
type: 'SizeValue',
@@ -314,6 +321,7 @@ export const docsDense = {
statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'tooltip via info icon at label end',
numberOfMonths: 'months in calendar (default 2)',
+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
changeAction:
'async action fired after onChange; drives optimistic UI updates via useTransition',
isLoading: 'loading state; disables interaction + shows a spinner',
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
index f3436f6254..21c6a34562 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx
@@ -511,6 +511,72 @@ describe('DateRangeInput statusVariant forwarding', () => {
'detached',
);
});
+
+ describe('weekStartsOn', () => {
+ // The calendar popover renders in the top layer; jsdom keeps the content in
+ // the DOM but role queries skip it, so read the columnheaders directly.
+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {
+ fireEvent.click(getButton('Open calendar'));
+ return Array.from(container.querySelectorAll('[role="columnheader"]'))
+ .slice(0, 7)
+ .map(h => h.textContent);
+ };
+
+ it('defaults to a Sunday-first week', () => {
+ const {container} = render(
+ <DateRangeInput label="Range" value={null} onChange={() => {}} />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Su',
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ ]);
+ });
+
+ it('forwards a numeric weekStartsOn to the calendar', () => {
+ const {container} = render(
+ <DateRangeInput
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ weekStartsOn={1}
+ />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+
+ it('accepts a three-letter day name', () => {
+ const {container} = render(
+ <DateRangeInput
+ label="Range"
+ value={null}
+ onChange={() => {}}
+ weekStartsOn="mon"
+ />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+ });
});
describe('DateRangeInput icon theme targets', () => {
diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsx
index c1e3e4235e..bddb89fa4a 100644
--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx
+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx
@@ -45,7 +45,13 @@ import {
} from '../Field';
import {Icon} from '../Icon';
import {Spinner} from '../Spinner';
-import {Calendar, type ISODateString, type DateRange} from '../Calendar';
+import {
+ Calendar,
+ type ISODateString,
+ type DateRange,
+ type DayOfWeek,
+ type DayOfWeekName,
+} from '../Calendar';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {mergeProps} from '../utils';
@@ -355,6 +361,14 @@ export interface DateRangeInputProps extends Omit<
* @default 2
*/
numberOfMonths?: 1 | 2;
+
+ /**
+ * First day of week in the calendar. Accepts a number
+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
+ * case-insensitive).
+ * @default 0
+ */
+ weekStartsOn?: DayOfWeek | DayOfWeekName;
}
/**
@@ -396,6 +410,7 @@ export function DateRangeInput({
statusVariant = 'attached',
labelTooltip,
numberOfMonths = 2,
+ weekStartsOn,
width,
xstyle,
className,
@@ -667,6 +682,7 @@ export function DateRangeInput({
max={max}
dateConstraints={dateConstraints}
numberOfMonths={numberOfMonths}
+ weekStartsOn={weekStartsOn}
/>
</div>,
{placement: 'below', alignment: 'start'},
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
index 3263b399a0..252861cbcb 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
@@ -173,6 +173,13 @@ export const docs = {
description: 'Number of months displayed simultaneously in the calendar.',
default: '1',
},
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description:
+ 'First day of week in the calendar. A number (0 = Sunday … 6 = Saturday) or a three-letter day name.',
+ default: '0',
+ },
{
name: 'width',
type: 'SizeValue',
@@ -477,6 +484,12 @@ export const docsZh = {
description: '日历中同时显示的月份数量。',
default: '1',
},
+ {
+ name: 'weekStartsOn',
+ type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+ description: '日历中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',
+ default: '0',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -577,6 +590,7 @@ export const docsDense = {
status: 'error/warning/success status w/ message',
labelTooltip: 'tooltip text via info icon at label end',
numberOfMonths: 'months shown simultaneously in calendar',
+ weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
xstyle: 'StyleX styles for layout; must be stylex.create() value',
},
};
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
index 098026f731..9157c910be 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx
@@ -820,6 +820,62 @@ describe('DateTimeInput', () => {
expect(onChange.mock.calls[0][0]).toContain('14:31');
});
});
+
+ describe('weekStartsOn', () => {
+ // The calendar popover renders in the top layer; jsdom keeps the content in
+ // the DOM but role queries skip it, so read the columnheaders directly.
+ const openAndReadWeekdays = (container: HTMLElement): (string | null)[] => {
+ fireEvent.keyDown(screen.getAllByRole('combobox')[0], {key: 'ArrowDown'});
+ return Array.from(container.querySelectorAll('[role="columnheader"]'))
+ .slice(0, 7)
+ .map(h => h.textContent);
+ };
+
+ it('defaults to a Sunday-first week', () => {
+ const {container} = render(
+ <DateTimeInput label="When" onChange={() => {}} />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Su',
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ ]);
+ });
+
+ it('forwards a numeric weekStartsOn to the calendar', () => {
+ const {container} = render(
+ <DateTimeInput label="When" onChange={() => {}} weekStartsOn={1} />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+
+ it('accepts a three-letter day name', () => {
+ const {container} = render(
+ <DateTimeInput label="When" onChange={() => {}} weekStartsOn="mon" />,
+ );
+ expect(openAndReadWeekdays(container)).toEqual([
+ 'Mo',
+ 'Tu',
+ 'We',
+ 'Th',
+ 'Fr',
+ 'Sa',
+ 'Su',
+ ]);
+ });
+ });
// ===========================================================================
// Segment theme targets (#4075)
// ===========================================================================
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index df99e881d0..d82018677b 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -47,7 +47,13 @@ import {
import {Icon} from '../Icon';
import {VisuallyHidden} from '../VisuallyHidden';
import {Spinner} from '../Spinner';
-import {Calendar, type ISODateString, type CalendarHandle} from '../Calendar';
+import {
+ Calendar,
+ type ISODateString,
+ type CalendarHandle,
+ type DayOfWeek,
+ type DayOfWeekName,
+} from '../Calendar';
import {useCalendarConstraints} from '../Calendar/hooks';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
@@ -348,6 +354,14 @@ export interface DateTimeInputProps extends Omit<
* @default 1
*/
numberOfMonths?: 1 | 2;
+
+ /**
+ * First day of week in the calendar. Accepts a number
+ * (0 = Sunday … 6 = Saturday) or a three-letter day name ('sun'–'sat',
+ * case-insensitive).
+ * @default 0
+ */
+ weekStartsOn?: DayOfWeek | DayOfWeekName;
}
function splitDateTime(dt: ISODateTimeString | undefined): {
@@ -425,6 +439,7 @@ export function DateTimeInput({
status,
labelTooltip,
numberOfMonths = 1,
+ weekStartsOn,
width,
xstyle,
className,
@@ -1050,6 +1065,7 @@ export function DateTimeInput({
max={calendarMax}
dateConstraints={dateConstraints}
numberOfMonths={numberOfMonths}
+ weekStartsOn={weekStartsOn}
/>,
{placement: 'below', alignment: 'start'},
)}