How to use filterDOMProps?

[stevegreco]

This is more of a question regarding best practices and patterns. As we build out our internal design system, we have regularely referenced React Spectrum and react-aria-components source code. We have seen the usage of a utility filterDOMProps but there really is not much info on this. I am mainly curious what the best practices around this are, and what this utility accomplishes in a Typescript world.

My first impression is that it is filtering out props from within the component, so what role does this play if our users are using Typescript exclusively?

It seems to me that this utility is mostly a fallback to ensure that random props do not leak to the DOM in a Non-Typescript environment, would that be a good assumption?

It seems like filterDOMProps does not also include props like style and className, so would the idea be that those DOM props always get manually added to our types and de-structured out?

[snowystinger]

Thanks for the dicussion.

filterDOMProps is an undocumented internal utility we use to prevent random props from being spread on the dom nodes we render. It isn't intended for external use.

If you're just curious what it does, it allows through id first and foremost, then data-*, then possibly labelling props depending on how it is used. You shouldn't need to use it. If you're creating your own RAC compatible components, you can use your own filtering to accomplish what you need to avoid specific props ending up places they shouldn't.

Because it's undocumented and therefore considered private, we do not guarantee its API in semver. If there's a strong reason, we can discuss making it public.

[stevegreco]

Thanks for responding.

As a fellow Design System maintainer, I was mostly just curious about its usage for our internal Design System. We are heavily leveraging React Aria Components, but there are a few limited components, like Card that are basically just DOM elements that do not utilize RAC. We were looking for alternatives to using React.HTMLAttributes<HTMLDivElement> for something like that.

Our internal teams are largely leveraging Typescript, so I think for the most part we are probably covered. It seems like using the out of the box React types for those DOM nodes covers a lot of the bases. What do you see as the main value add for a filter like this?

[snowystinger]

It's mostly there to assist us in making sure pass the id and data-* attributes through to the dom node. You could also just pass id explicitly, and pull all the data-* attributes out and just spread those. This function just happens to do both of those at the same time and gives us a little handle to include aria-labels and link props as well.

Typescript is a good safeguard, but @ts-ignore or not using typescript would, without our filter, allow users to pass anything they wanted to our props and, therefore, to our rendered node. This might result in aria attributes that should not be present, or it could result in a React warning about unknown prop on dom element.

You don't need something like it to work with RAC. If you find yourself repeatedly pulling out certain props to pass along, then you may want to write something similar. I would not use our filterDOMProps function however, as I mentioned before, it's undocumented and therefore private.

[trentonyo]

Maintainer of a project which uses react-aria directly with native HTML elements here.

I haven't seen many other examples of folks handling prop pollution, most are destructuring the react-aria hooks to omit the unused props before spreading onto the native elements. This works just fine, but it does require us to suppress our unused vars lint rule.

const { buttonProps, otherProps } = useSomeReactAria();

const {
  //eslint-ignore unused
  nonHtmlProp,
  //eslint-ignore unused
  otherNonHtmlProp,
  ...safeButtonProps
  } = buttonProps;
  
/* ... */

return <button {...safeButtonProps} />

I've seen other teams with similar setups to ours, but not many - the most notable example being Sentry which uses emotion rather than native HTML and that affords them a prop filter out of the box.

If there's a better solution that I just haven't been able to find, bully! Otherwise, I'd say that internal use is a decent indicator that at least teams who use react-aria directly against native HTML (definitely my team 😁) would find this a useful feature?

[snowystinger]

As mentioned above:

It's mostly there to assist us in making sure pass the id and data-* attributes through to the dom node

This won't pass along most of the things that would come from one of our hooks.

Taking a step back though, if buttonProps has non-html props, then it probably isn't meant to be spread on an html element and should instead be passed to something which makes use of useButton. That or the props should be filtered before they are passed to our hook. Or, many of our hooks do this filtering already, maybe we've missed one?

Do you have a more concrete example?

[trentonyo]

Ahh it could be that we're useButtoning when we don't need to (i.e., directly into a <button>, the hook is maybe for non-button elements)

As for the example, here's one of the simpler implementations, with no stripped props so that the errors pop:

AriaButton.tsx

import {
	AriaButtonProps as ReactAriaButtonProps,
	useButton,
	useObjectRef,
	mergeProps,
} from "react-aria";

import { ariaButtonRecipe } from "./private/AriaButton.css.ts";

/**
 * Implements the "button" ARIA pattern.
 *
 * @prop className - If not defined, a default non-styled button will be rendered.
 */
export type AriaButtonProps = ReactAriaButtonProps & {
	ref?: React.Ref<HTMLButtonElement>;
	className?: string;
	children?: React.ReactNode;
};

export const AriaButton = ({ ref: externalRef, ...props }: AriaButtonProps) => {
	// useObjectRef ensures we have a valid RefObject for useButton
	// while also synchronizing with the external ref passed to the component
	const ref = useObjectRef(externalRef);
	const { buttonProps } = useButton(props, ref);

	// Merge buttonProps with original props to preserve event handlers from parent
	const mergedProps = mergeProps(props, buttonProps);

	return (
		<button {...mergedProps} ref={ref} className={props.className ?? ariaButtonRecipe()}>
			{props.children}
		</button>
	);
};

And the console:

---

For a truncated example of how we "solve it" in another place (that doesn't use an element with events), this doesn't throw anything in the console:

export const AriaListBox = forwardRef(
	(props: ListBoxProps<SelectionListItem>, ref: React.ForwardedRef<HTMLUListElement>) => {
		const { state, className, autoFocus, ...rest } = props;

		const listBoxRef = ref as React.RefObject<HTMLUListElement>;
		const { listBoxProps } = useListBox({ autoFocus, ...rest }, state, listBoxRef);

		// Pull problematic props out so they don't hit the <ul>, I'm sorry
		const mergedProps = mergeProps(listBoxProps, rest);
		const {
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			shouldUseVirtualFocus,
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			linkBehavior,
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			UNSTABLE_itemBehavior,
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			shouldSelectOnPressUp,
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			shouldFocusOnHover,
			// @ts-expect-error prevents prop pollution
			// eslint-disable-next-line @typescript-eslint/no-unused-vars
			escapeKeyBehavior,
			...validUlProps
		} = mergedProps as object;

		return (
			<ul {...validUlProps} ref={ref} className={className}>
				{Array.from(state.collection, item => (
					<AriaListBoxOption key={item.key} item={item} state={state} />
				))}
			</ul>
		);
	}
);
AriaListBox.displayName = "AriaListBox";

[snowystinger]

Ahh it could be that we're useButtoning when we don't need to (i.e., directly into a , the hook is maybe for non-button elements)

useButton is for both button and non-button elements, as controlled by the prop elementType which defaults to 'button'

[snowystinger]

the issue you have is here:

// Merge buttonProps with original props to preserve event handlers from parent
	const mergedProps = mergeProps(props, buttonProps);

you're sending everything from props to the element, which has props that are only meant for useButton, such as onPress

you can filter your own props though

// Merge buttonProps with original props to preserve event handlers from parent
	const mergedProps = mergeProps(filterDOMProps(props), buttonProps);

However, this will again take out pretty much everything, so you may be better served by writing your own filtering