These are the same components we use throughout Payload. If you’re building a Custom Component, a plugin, a custom dashboard, or a completely tailored Admin experience, you can use them to build interfaces that look, feel, and behave like the rest of Payload.

There was just one problem—we hadn't properly documented them.

The components were there but finding them was difficult

Developers have been able to import components from @payloadcms/ui for a long time. But figuring out what was available, how a component worked, and how to customize it often meant digging through the Payload codebase, finding an existing implementation, or hunting through examples and templates.

That’s not a great developer experience (and I have experienced this first-hand on more than one occasion).

As Payload has grown beyond the traditional CMS use case, it’s become increasingly important to fix. Developers are using Payload to build internal tools, custom dashboards, plugins, highly branded Admin Panels, and applications where the Admin Panel itself is an important part of the product experience.

So, we finally documented them

There’s now a dedicated UI Components section in the Payload Docs for exploring the components available through @payloadcms/ui.

We’ve started with a collection of the components that are most useful when building custom interfaces, including things like Buttons, Cards, Tables, Pills, Selects, Tooltips, Drawers, Date Pickers, and more.

For each component, you can see a working example directly in the docs, along with the code required to use it.

Where relevant, the docs also cover common props, accessibility considerations, required providers or setup, and the styles available when you want to customize how a component looks.

The goal is simple: you should be able to see what Payload gives you before you start building your own version of it.

See the component before you use it

One of the biggest parts of this work is making the documentation visual. When you’re choosing a UI component, an API signature only tells you so much. You want to know what it actually looks like.

The component docs render real Payload components directly on the page, including support for both light and dark mode. Alongside the rendered component, you can inspect the code needed to implement it and the relevant styling information for customizing it.

The docs follow your version of Payload

Much like the rest of our docs, the UI component examples are also version-aware.

When you switch between versions of the Payload docs, the examples, code, and styling guidance update to match the version you’re viewing. (for v3/v4 when released)

That’s particularly important as we continue evolving the Admin Panel and the ways developers can customize it. Instead of documentation slowly drifting away from the version you actually have installed, these examples can live alongside the version of Payload they describe.

A better foundation for building on top of Payload

Payload has always been built around giving developers ownership over their applications and the Admin Panel is no exception.

@payloadcms/ui gives you access to the same building blocks we use ourselves, so extending Payload doesn't have to mean recreating its interface from scratch.

With these docs, those building blocks are finally much easier to discover and understand.

This first release doesn't document every component in @payloadcms/ui, and that's intentional. We started with an initial set of the components we think will be most useful and will continue expanding the documentation from here.

We’ll follow this up with a guide focused less on what components are available and more on how to actually use them to build custom experiences in Payload.