website Dedicated `asChild` page

We have had a few reports that have been assumed to be an issue with the new asChild API but also will have been an issue with the as prop. It seems the explicitness of the asChild API has made some of these issues more apparent for people so it might be useful to provide some documentation on these pitfalls and the solutions to them.

The most recent report we had was here https://github.com/radix-ui/primitives/issues/953

It's not clear what props the child should accept (or that props need to be forwarded). For now we're saying it should always accept DOM props. Ideally we would improve the DX with TS but TS doesn't currently support the ability to type the props of the child React Element.

Nov 03 '21 13:11 jjenzz

Yeah I agree a dedicated page would be good, we could flesh it out more than the tiny mention we have in the docs and point people to it at the very least.

Nov 03 '21 13:11 benoitgrelard

Makes sense. Let me have a think and add it to my list.

Nov 03 '21 14:11 peduarte

I spent some hours today struggling with this as well, as I couldn’t find any hint on the documentation page that the React component supplied as the child has to forward a ref to its DOM element. Only after looking at some bug reports did I see that this is necessary. This doesn’t seem self-explanatory to me (though it makes sense, of course), so a documentation page on how to use asChild would be awesome.