[useRender] Add public hook

[mnajdova]

Closes #1315

Added a public useRender hook as an simpler adapter that uses the useComponentRenderer hook. I intentionally copied the types, so we make sure we don't break them if we ever change the internal useComponentRenderer hook.

The hooks receives the following settings:

• className
• render
• state
• props (passed as extraProps)
• stateAttributesMap (alias for customStyleHookMapping)

Documentation page: https://deploy-preview-1418--base-ui.netlify.app/react/utils/use-render

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	3340a4e
🔍 Latest deploy log	https://app.netlify.com/sites/base-ui/deploys/67bde59c58d2840008cff0de
😎 Deploy Preview	https://deploy-preview-1418--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mj12albert]

Nice ~ I imagine the use-case is something like this: https://codesandbox.io/p/sandbox/flamboyant-fog-9x266p?file=%2Fsrc%2FApp.tsx%3A29%2C63
(for some reason importing the hook in CSB doesn't work, this works fine locally in a playground though)

This feels more intuitive to me (biased though because I never used asChild extensively) to use than a Slot component

[mnajdova]

for some reason importing the hook in CSB doesn't work, this works fine locally in a playground though

I haven't updated the exports field, will fix it. Here is the updated sandbox: https://codesandbox.io/p/sandbox/exciting-paper-9x266p-use-renderer-forked-ry269y?file=%2Fpackage.json

[mj12albert]

I removed only the customStyleHookMapping setting from the original hook

It may be useful to provide a (alternative) way to opt-out individual props placed in state from generating a corresponding data attribute

[mnajdova]

Thanks for the initial review, I updated the API to include:

• className
• render
• state
• ref
• props (passed as extraProps)
• excludedStyleHookStates [string[]] - list of state keys that should not be generated as a styled hooks (data-attributes) - based on these I am creating a customStyleHookMapping that is passed in the internal hook. I've also added usage example under: https://deploy-preview-1418--base-ui.netlify.app/experiments/custom-components

[michaldudak]

I'd leave customStyleHookMapping as in useComponentRenderer. It should be quite common to customize the data attributes (we do this often).

[mnajdova]

I'd leave customStyleHookMapping as in useComponentRenderer. It should be quite common to customize the data attributes (we do this often).

Yeah, fair enough, ok I was thinking initially to make the API simpler. I've changed it back to use the customStyleHookMapping and added a test for it.

[mnajdova]

I've resolved all feedback and added a docs page: https://deploy-preview-1418--base-ui.netlify.app/react/utils/use-renderer

[aarongarciah]

Why useRender is not inside /utils?

[mnajdova]

@michaldudak @atomiks what are your thoughts? I though it as a "first class export" similar to the components, but having it in the utils makes sense as well, especially if we want to publicly make available more of the hooks.

[aarongarciah]

Docs updated. Highlights:

• The basic render prop demo has been simplified.
• The data-attrs and className demos are now two separate demos, for better discoverability. The end result in both demos is the same, but achieved differently.
• The data-attrs and className use a Counter button instead of a clickable Text component. Not my favorite example but I think it's better than the previous one.
• New "Migrating from Radix" section added.
• Other copy updates e.g. replacing the "Usage" headline with "Examples", which we use in all components.

---

I'm still not happy with the subtitle ("Utility for adding Base UI-like features to custom components") and the intro bullet points below. I think 99% os users will use useRender only to implement their own render prop, and the state-based data-attrs and className callback are only nice to have features for a minority of users i.e. only useful for users building unstyled primitives, which are not very numerous? The subtitle and bullet points probably makes useRender look more complex that it should because of this.

One of the reasons why it's so hard to come up with simple examples for the data-attrs and className callback demos is because it's mostly useful for unstyled primitives, and unstyled primitives already exist on Base UI, and tend to be complex (or at least require a lot of boilerplate to be fully accessible).

Note: state-based data attributes can be useful for styled components that want to have self-contained styles based on data attributes (.Text[data-size="large"]), but IMO that doesn't justify such a feature in useRender.

After having though about useRender for a while, shipping useRender without data-attrs and className callback could be an option. I'm curious to know your thoughts cc @mnajdova @michaldudak @colmtuite

[mj12albert]

I'm still not happy with the subtitle ("Utility for adding Base UI-like features to custom components")

How about "Utility for creating custom components that support a render prop"?

[michaldudak]

After having though about useRender for a while, shipping useRender without data-attrs and className callback could be an option.

It's not a bad idea, especially considering that state attributes and class names implementation is pretty simple and should be easily done in userland if needed (or we could provide separate utilities for them if devs want them).

[aarongarciah]

AFAIK StateAttributes is not exposed to users so not sure if having it here is helpful.

[mnajdova]

After having though about useRender for a while, shipping useRender without data-attrs and className callback could be an option.

It's not a bad idea, especially considering that state attributes and class names implementation is pretty simple and should be easily done in userland if needed (or we could provide separate utilities for them if devs want them).

Yeah, we can do this in the first iteration. @aarongarciah I will do the change on the hook & docs, if we decide to extend it in the future, we can use your examples.

[mnajdova]

I've simplified the hook & the docs page to only cover the render prop, we can add more utils in the future if people ask for them.

[aarongarciah]

off-topic: I wonder if state should be optional in useComponentRenderer

[mnajdova]

We probably didn't have use-case for it so far, as all components have some state, but we could consider it if we hit this need again.