expose as/ref utilities

[ianstormtaylor]

Hello, thank you for this awesome library! I love the direction it's going, and the simplicity of some of these headless components is really well done.

The problem I'm running in to is that there is a decent amount of boilerplate required to build a "proper" UI kit component that makes it slightly more work than just copy-pasting from Tailwind UI currently. (Although the current workflow with Tailwind CSS + Tailwind UI is already amazing!)

The boilerplate I'm talking about is pieces like ref forwarding, prop typing, and as handling.

I'd like to propose exposing some utilities that Headless UI defines internally, since it's something that is needed when building the JS/TS versions of lots of components. Specifically to expose a "factory" function that handles as= and ref= and all the associated complexity of typings for those two props.

---

For a specific example, consider copying an <input> component from https://tailwindui.com/components/application-ui/forms/input-groups and wanting to let it be one of three sizes.

In React you might write something like:

import React from 'react'

const SIZES = {
  sm: 'text-sm leading-8',
  md: 'leading-9',
  lg: 'leading-10',
}

export const Input = ({ className = '', size = 'md', type = 'text', ...rest }) => {
  return (
    <input
      {...rest}
      type={type}
      className={`
        ${className} 
        ${SIZES[size]} 
        py-0 rounded-md shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full border border-gray-300
      `}
    />
  )
}

This is easy to arrive at fairly quickly from copying the initial snippet from Tailwind UI.

But then if you're using TypeScript you need to write the correct types too. (And unfortunately it's non-trivial to figure out the exact right types to use for the given element.) But you end up with:

import React from 'react'
import { Assign } from 'utility-types'

const SIZES = {
  sm: 'text-sm leading-8',
  md: 'leading-9',
  lg: 'leading-10',
}

export const Input = ({
  className = '',
  size = 'md',
  type = 'text',
  ...rest
}: Assign<
  React.InputHTMLAttributes<HTMLInputElement>,
  { size?: keyof typeof SIZES }
>) => {
  return (
    <input
      {...rest}
      type={type}
      className={`
        ${className} 
        ${SIZES[size]} 
        py-0 rounded-md shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full border border-gray-300
      `}
    />
  )
}

And then you realize while hooking up some parts of your app that this isn't complete either, because you need to handle ref-forwarding to make it integrate properly with other UI pieces. So you do that:

import React from 'react'
import { Assign } from 'utility-types'

const SIZES = {
  sm: 'text-sm leading-8',
  md: 'leading-9',
  lg: 'leading-10',
}

export const Input = React.forwardRef<
  HTMLInputElement,
  Assign<
    React.InputHTMLAttributes<HTMLInputElement>,
    {
      size?: keyof typeof SIZES
    }
  >
>(({ className = '', size = 'md', type = 'text', ...rest }, ref) => {
  return (
    <input
      {...rest}
      ref={ref}
      type={type}
      className={`
        ${className} 
        ${SIZES[size]} 
        py-0 rounded-md shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full border border-gray-300
      `}
    />
  )
})

And a bit later, say you have a specific place in your app where you want to make use of a "currency input" (like react-currency-input-field), you realize that it's not simple to do with your component because you don't have the as= prop like other UI kits do.

So you try to add that, but it's extremely non-trivial to figure out... But I see that a lot of the complex logic is already written internally for @headless-ui, so it would be amazing to expose it for others to build with too.

---

It would be great to have a solution like:

import { forwardRef } from '@headless-ui/react'

const Input = forwardRef<'input', { size?: 'sm' | 'md' | 'lg' }>({
  as: Component = 'input',
  className = '',
  size = 'md',
  type = 'text',
}, ref) => {
  return (
    <Component
      {...rest}
      ref={ref}
      type={type}
      className={`
        ${className} 
        ${SIZES[size]} 
        py-0 rounded-md shadow-sm focus:ring-indigo-500 focus:border-indigo-500 block w-full border border-gray-300
      `}
    />
  )
}

Which handles three things for you:

• ref forwarding with the proper element type.
• props with the proper default props based on the element type.
• as prop with support for overriding and proper typings when overridden.

I think this is something that pretty much any component you define in your own personal UI kit after copying the snippets from Tailwind UI would need.

---

Hope that makes sense! Happy to give more details too if needed.

[RobinMalfait]

Hey! Thank you for your suggestion!
Much appreciated! 🙏

In Headless UI itself we have some helpers to make rendering components easier, currently it has these options built-in:

• provide a default tag, for example a div
• as prop to render a different low level component

Both of these will also ensure that TypeScript starts showing all the props available based on:

1. Which props the component requires
2. Which features the component exposes (as, unmount, static, ...)
3. Which low level component is used via as or via the default tag

We also have the functionality to write your component using a render prop:

<Menu.Button>
{({ open }) => (

)}
</Menu.Button>

Internally we call this a bag, so that you can expose data for each component if it is required.

We also override the className in React so that it can be a function, where you get access to the exact same bag that the component can expose.

We are also able to enable certain features per component:

1. In certain components, it should be possible to show/hide content, for example the Menu.Items component. We have an unmount prop, this means that when it is set to true (default value), the component will unmount. When it is set to false we will add a hidden prop and style={{ display: 'none' }}. This is nice for when your content contains form state so that all that state is not removed.
2. We also have a static prop, for a bunch of components. For example the Menu.Items will show/hide based on the internal state. However, when the static prop is passed, it will always be rendered. This means that you can wrap that component in a Transition component. (Which then controls when/how it should render)

---

Long story short we have bunch of features here. Would you imagine some API that allows you to create components yourself that expose all of this functionality? Or would you like a bit more control where you can enable/disable all these features?

[ianstormtaylor]

@RobinMalfait interesting! Good question. Makes me think two things…

1. I'm not sure if I'd ever need a few of those pieces—I haven't gotten far enough to have a use case yet for a custom component that uses unmount/hidden/static for example. Or the class names-specific bag function. Whereas I can definitely see a use case for children bags.

2. But that said, I also wouldn't mind if those features existing on the components even if I just didn't use them. (Being able to enable/disable them would be one step better, but I'd be happy to start with just everything enabled and me ignoring it.)

So not sure if that totally answers your question!

Overall though I trust you to figure out these useful abstractions across UI components, so I'm personally game for whatever other built-in features happen to come along with the custom component factory. For me so far the biggest issues have been as, refs, and typings, but I'll probably run into more as I go deeper.

I definitely think something in this realm would be very helpful though for generic components that are copy-pasted from Tailwind UI. Right now the stateful ones are nicely handled with things like Dialog, Menu, etc. But the non-stateful ones like Input, Button, etc. are harder to sort out.

[jokull]

I was looking for a way to bring focus to the select component. I guess a ref wouldn't be enough here because it's not a under the hood.

[RobinMalfait]

Hey! I converted the issue to a discussion since this is a cool idea but not really an issue.