Mastering Headless UI in React with TypeScript

In the modern web development landscape, creating user interfaces that are both accessible and customizable is of utmost importance. Headless UI in combination with React and TypeScript offers a powerful solution to achieve this. Headless UI provides a set of unstyled, fully accessible UI components that can be integrated into React applications. When paired with TypeScript, it adds type safety and enhanced developer experience. This blog post will explore the fundamental concepts, usage methods, common practices, and best practices of using Headless UI in React with TypeScript.

Table of Contents#

  1. Fundamental Concepts
  2. Installation and Setup
  3. Usage Methods
  4. Common Practices
  5. Best Practices
  6. Conclusion
  7. References

Fundamental Concepts#

What is Headless UI?#

Headless UI is a library that provides a collection of unstyled, accessible UI components. These components come with all the necessary keyboard navigation, ARIA roles, and other accessibility features out - of - the - box. The "headless" nature means that they don't have any predefined styles, allowing developers to fully customize the look and feel of the components according to their application's design requirements.

Why Combine with React and TypeScript?#

React is a popular JavaScript library for building user interfaces. It provides a component - based architecture that makes it easy to manage and reuse UI elements. TypeScript, on the other hand, adds static typing to JavaScript, which helps catch errors early in the development process and provides better code intelligence. When combined with Headless UI, React and TypeScript offer a robust environment for building high - quality, accessible, and maintainable user interfaces.

Installation and Setup#

First, create a new React project with TypeScript using Create React App:

npx create-react-app my-headless-ui-app --template typescript
cd my-headless-ui-app

Then, install the Headless UI library:

npm install @headlessui/react

Usage Methods#

The dropdown component is a common UI element used to display a list of options. Here is an example of using the dropdown component in a React TypeScript application:

import React from 'react';
import { Transition, Dropdown } from '@headlessui/react';
 
function DropdownExample() {
    return (
        <Dropdown>
            {({ open }) => (
                <>
                    <Dropdown.Button>Open Dropdown</Dropdown.Button>
                    <Transition
                        show={open}
                        enter="transition ease-out duration-100"
                        enterFrom="transform opacity-0 scale-95"
                        enterTo="transform opacity-100 scale-100"
                        leave="transition ease-in duration-75"
                        leaveFrom="transform opacity-100 scale-100"
                        leaveTo="transform opacity-0 scale-95"
                    >
                        <Dropdown.Menu>
                            <Dropdown.Item>Option 1</Dropdown.Item>
                            <Dropdown.Item>Option 2</Dropdown.Item>
                        </Dropdown.Menu>
                    </Transition>
                </>
            )}
        </Dropdown>
    );
}
 
export default DropdownExample;

The menu component is another useful UI element for creating navigation menus. Here is an example:

import React from 'react';
import { Menu } from '@headlessui/react';
 
function MenuExample() {
    return (
        <Menu as="div" className="relative inline-block text-left">
            <Menu.Button>Open Menu</Menu.Button>
            <Menu.Items>
                <Menu.Item>
                    <a href="#">Home</a>
                </Menu.Item>
                <Menu.Item>
                    <a href="#">About</a>
                </Menu.Item>
            </Menu.Items>
        </Menu>
    );
}
 
export default MenuExample;

Common Practices#

Styling Headless UI Components#

Since Headless UI components are unstyled, you need to add your own styles. You can use CSS classes directly in the components or use a CSS - in - JS solution like styled - components. Here is an example of styling the dropdown component using CSS classes:

/* styles.css */
.dropdown-button {
    background-color: #f3f4f6;
    border: 1px solid #d1d5db;
    padding: 0.5rem 1rem;
    border-radius: 0.25rem;
}
 
.dropdown-menu {
    background-color: #ffffff;
    border: 1px solid #d1d5db;
    border-radius: 0.25rem;
    padding: 0.5rem;
}
import React from 'react';
import { Transition, Dropdown } from '@headlessui/react';
import './styles.css';
 
function StyledDropdownExample() {
    return (
        <Dropdown>
            {({ open }) => (
                <>
                    <Dropdown.Button className="dropdown-button">Open Dropdown</Dropdown.Button>
                    <Transition
                        show={open}
                        enter="transition ease-out duration-100"
                        enterFrom="transform opacity-0 scale-95"
                        enterTo="transform opacity-100 scale-100"
                        leave="transition ease-in duration-75"
                        leaveFrom="transform opacity-100 scale-100"
                        leaveTo="transform opacity-0 scale-95"
                    >
                        <Dropdown.Menu className="dropdown-menu">
                            <Dropdown.Item>Option 1</Dropdown.Item>
                            <Dropdown.Item>Option 2</Dropdown.Item>
                        </Dropdown.Menu>
                    </Transition>
                </>
            )}
        </Dropdown>
    );
}
 
export default StyledDropdownExample;

Managing Component State#

Headless UI components often rely on internal state to manage their open/closed state. However, you may need to manage additional state in your application. For example, you can use the useState hook in React to keep track of the selected option in a dropdown:

import React, { useState } from 'react';
import { Transition, Dropdown } from '@headlessui/react';
 
function StatefulDropdownExample() {
    const [selectedOption, setSelectedOption] = useState<string | null>(null);
 
    return (
        <Dropdown>
            {({ open }) => (
                <>
                    <Dropdown.Button>{selectedOption || 'Select an option'}</Dropdown.Button>
                    <Transition
                        show={open}
                        enter="transition ease-out duration-100"
                        enterFrom="transform opacity-0 scale-95"
                        enterTo="transform opacity-100 scale-100"
                        leave="transition ease-in duration-75"
                        leaveFrom="transform opacity-100 scale-100"
                        leaveTo="transform opacity-0 scale-95"
                    >
                        <Dropdown.Menu>
                            <Dropdown.Item onClick={() => setSelectedOption('Option 1')}>Option 1</Dropdown.Item>
                            <Dropdown.Item onClick={() => setSelectedOption('Option 2')}>Option 2</Dropdown.Item>
                        </Dropdown.Menu>
                    </Transition>
                </>
            )}
        </Dropdown>
    );
}
 
export default StatefulDropdownExample;

Best Practices#

Type Definitions for Headless UI Components#

When using TypeScript with Headless UI, it's important to define the types correctly. For example, if you are passing custom props to a Headless UI component, you can create an interface to define the prop types:

import React from 'react';
import { Menu } from '@headlessui/react';
 
interface CustomMenuProps {
    menuItems: string[];
}
 
function CustomMenu({ menuItems }: CustomMenuProps) {
    return (
        <Menu as="div" className="relative inline-block text-left">
            <Menu.Button>Open Menu</Menu.Button>
            <Menu.Items>
                {menuItems.map((item, index) => (
                    <Menu.Item key={index}>
                        <a href="#">{item}</a>
                    </Menu.Item>
                ))}
            </Menu.Items>
        </Menu>
    );
}
 
export default CustomMenu;

Testing Headless UI Components#

Testing is an important part of the development process. You can use testing libraries like Jest and React Testing Library to test Headless UI components. Here is an example of testing the dropdown component:

import React from 'react';
import { render, fireEvent, screen } from '@testing-library/react';
import { DropdownExample } from './DropdownExample';
 
test('dropdown opens and closes', () => {
    render(<DropdownExample />);
    const dropdownButton = screen.getByText('Open Dropdown');
    fireEvent.click(dropdownButton);
    expect(screen.getByText('Option 1')).toBeInTheDocument();
    fireEvent.click(dropdownButton);
    expect(screen.queryByText('Option 1')).toBeNull();
});

Conclusion#

Headless UI in combination with React and TypeScript provides a powerful and flexible solution for building accessible and customizable user interfaces. By understanding the fundamental concepts, usage methods, common practices, and best practices, you can create high - quality applications that meet the needs of your users. Whether you are building a simple dropdown or a complex navigation menu, Headless UI and TypeScript in a React environment offer a robust set of tools to help you succeed.

References#

2025-10