Documentation for ARIA attributes and data attributes

[liaujianjie]

Since ARIA attributes and data attributes are extensively used for the application of accessibility markup and conditional application of styles, it would be great if we had more documentation regarding these attributes.

Specifically, these are the things that could further clarify the scopes and usage for the attributes:

1. Which ARIA attributes are used in each Radix component? How are they applied?
2. What data attributes are used in each Radix component? How are they applied?
   Example: In Toasts, [data-swipe="move"] is used when a swipe gesture is in-flight to dismiss the toast. The --radix-toast-swipe-move-x CSS variable contains the X offset of the swipe gesture—which can be used to animate the exit animation when swiped (e.g. a fade out effect as the toast is swiped away).
3. Should I be using ARIA attributes or data attributes for conditional styling of components built on Radix primitives?
4. More generally than (3) to prevent abuse of data attributes by consumers of Radix primitives: What is the scope of use for the Radix data attributes? Are they only meant to be consumed for conditional styling?
5. Is there a consistent naming structure for naming Radix data attributes? If so, what is it?

Having answers to the questions above can help us better design our component libraries to work better with Radix. For example: Should we create custom modifiers in our Tailwind config for ARIA attributes and/or Radix data attributes?

It can also give users of Radix a better idea of what the best practice of using Radix looks like.

Edit: Oops, I missed an earlier discussion on this.

[andy-hook]

I agree we should do more, thanks for the helpful feedback.

We have an issue logged to improve this here radix-ui/website#224

[jjenzz]

@liaujianjie i agree it would be helpful to document expectations around data attributes and what they are, but the aria attributes are an implementation detail you should ignore. use data attributes for styling.

regarding the Toast points raised, they are documented here https://www.radix-ui.com/docs/primitives/components/toast#animating-swipe-gesture

[liaujianjie]

@liaujianjie i agree it would be helpful to document expectations around data attributes and what they are, but the aria attributes are an implementation detail you should ignore. use data attributes for styling.

Gotcha. I suggest making the note prominent in the docs. Perhaps we could add a disclaimer in the the Overview > Styling > Styling overview > Data attributes section? Maybe something like:

aria attributes are an implementation detail that should be treated as internal to Radix. It is not recommended to rely on the aria attributes for the conditional styling of components (e.g. via attribute selectors).

[liaujianjie]

regarding the Toast points raised, they are documented here radix-ui.com/docs/primitives/components/toast#animating-swipe-gesture

Ah yes, I am aware of that. I should have been clearer, my bad. I wanted to suggested that it will be awesome for discoverability if we displayed the data attributes together with the explanation. Perhaps they could just be link to the section explaining the usage in detail.

For example, we could include a table of all the data attributes under the Toast > API Reference > Root section:

Depending on the state of the toast, the following data attributes will be applied to Root:

Data attribute	When is it applied and how to use?
[data-state="open"]	When the toast is shown.
[data-state="closed"]	When the toast is dismissed.
[data-swipe="move"]	When the toast in the middle of a swipe gesture. See this section for usage examples.
[data-swipe="cancel"]	...
[data-swipe="end"]	...

[benoitgrelard]

Absolutely, we're planning to do something like that radix-ui/website#224. Love it 👍

[jjenzz]

i second that, love the table idea :)