Adding persistent date format hints to the DatePicker component

[ty2k]

My team is working on an implementation of RAC's DatePicker in the context of a government design system. We have questions around the built-in internationalization and placeholder-style text that gets created by the <span role="spinbutton"> elements in the input.

From an accessibility point of view, we normally won't use placeholder-style text as the only affordance for what should go into a field. For sighted users, this text gets over-written when there's data in the field, so we tend towards using visible labels for formatting details (like the expected shape of a date). (See The Anatomy of Accessible Forms: The Problem with Placeholders for more on this topic.)

With the DatePicker, the default case uses the user's browser locale to set the formatting for the component. For example, en-US gets mm/dd/yyyy while en-CA gets yyyy-mm-dd. The placeholder text gets dynamically built into the component by the <span role="spinbutton"> elements. An en-US locale user might see placeholder style text like mm/dd/yyyy for an instance that isn't filled out, and then 2/1/2026 after they've selected a date. The mm/dd/yyyy format hint is no longer visible once the component has data.

If we want to add our own format hint text to the component, we have a couple of options I can think of:

1. Use <I18nProvider> with a hard-coded locale prop, and manually bake the expected date format into the label or description of the component. For us, this might end up being the preferred default case, because nearly all of our apps are targeting a locale like en-CA, and the ability to enforce consistency might trump the need for internationalization for our default path.
2. Use DatePicker without the <I18nProvider> wrapper, but try to generate a format hint string based on what gets rendered in the component. For example, iterate over the <span role="spinbutton"> elements and build a string based on the contents of each.

Ideally, there would be some way for us to access the format hint text using something like DatePickerRenderProps. I'm imagining an interface like:

<DatePicker {...props}>
  {({ formatHintText }) => (
    /* ... */
    {label && (<Label>{label} ({formatHintText})</Label>)}
    /* ... */

I'm wondering if anyone else has bumped up against this problem and found an elegant solution?

(Thanks for this awesome open source library. It has been a pleasure to use it to set up a design system!)

[devongovett]

We support something like this in our Spectrum implementation. See https://react-spectrum.adobe.com/v3/DateField.html#help-text

It's implemented here:

react-spectrum/packages/@react-spectrum/datepicker/src/utils.tsx

Lines 23 to 46 in 1c85bcc

	export function useFormatHelpText(props: Pick<SpectrumDatePickerBase<any>, 'description' | 'showFormatHelpText'>): ReactNode {
	let formatter = useDateFormatter({dateStyle: 'short'});
	let displayNames = useDisplayNames();
	return useMemo(() => {
	if (props.description) {
	return props.description;
	}
	if (props.showFormatHelpText) {
	return (
	formatter.formatToParts(new Date()).map((s, i) => {
	if (s.type === 'literal' || s.type === 'unknown' || (s.type as string) === 'yearName') {
	return <span key={i}>{` ${s.value} `}</span>;
	}
	let type = s.type as string === 'relatedYear' ? 'year' : s.type;
	return <span key={i} style={{unicodeBidi: 'embed', direction: 'ltr'}}>{displayNames.of(type)}</span>;
	})
	);
	}
	return '';
	}, [props.description, props.showFormatHelpText, formatter, displayNames]);
	}

Basically just uses Intl.DateTimeFormat to get the order of segments, and Intl.DisplayNames to get the localized names for those segments.

[ty2k]

Thanks so much @devongovett, that gave us a really elegant solution. Much appreciated!