DEV Community: Preet Suthar

How to build a shadcn/ui registry that Claude Code and Cursor can actually use

Preet Suthar — Fri, 16 Oct 2026 04:25:32 +0000

Most shadcn/ui components are now installed by an AI coding agent, not a person typing the command. If you publish a registry, the agent is your user. It needs to find your components, read their props without guessing, and run the right install command. A registry that only works for humans clicking through a docs site is a registry that gets misused.

I run HextaUI, a shadcn/ui registry, and I spent a chunk of this year making it work for Claude Code, Cursor and the shadcn MCP server. This is everything that turned out to matter, in the order I would do it again.

1. Ship a registry that passes validation

Start with the basics. Every item is a JSON file that follows the registry schema, with name, type, files, dependencies and registryDependencies. Put the index at a stable URL and every item at a predictable one:

https://your-site.com/r/registry.json
https://your-site.com/r/button.json
https://your-site.com/r/all.json

Run shadcn build to generate them from a registry.json source, and validate before you deploy. The CLI gained a registry validate step in May 2026. A registry that fails validation fails silently for agents, who will then write the component by hand and get it wrong.

Two details that make a real difference:

registryDependencies with full URLs. When your Dialog depends on your Button, point to https://your-site.com/r/button.json, not button, or the CLI pulls the shadcn/ui Button instead.
An all.json item that depends on everything. Agents asked to "set up the design system" will reach for it.

2. Register a namespace

Since the registry namespace feature landed, a user adds this to components.json:

{
  "registries": {
    "@hextaui": "https://hextaui.com/r/{name}.json"
  }
}

And then installs with a short name:

npx shadcn@latest add @hextaui/dialog

Document this snippet on your installation page and in your llms.txt. The short form is what the shadcn MCP server searches across, so a registry without a namespace is invisible to the one tool most agents use to browse registries.

If the registry is private, the object form takes headers with environment variables that the CLI expands and never logs:

{
  "registries": {
    "@acme-pro": {
      "url": "https://acme.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    }
  }
}

3. Give every docs page a Markdown twin

Agents fetch HTML badly. They fetch Markdown well. Make every docs URL answer at .md with the same content: description, install command, full source, usage, examples, keyboard support and the API table.

https://hextaui.com/docs/button      -> HTML for people
https://hextaui.com/docs/button.md   -> Markdown for agents

Do not hand-write the Markdown. Generate it from the same source as the page so the two never drift. On HextaUI the .md route walks the page's React tree and serializes it, so adding an example to the page adds it to the Markdown for free.

The API reference matters most here. An agent that can read a props table does not hallucinate a size="xl" that does not exist.

4. Publish llms.txt and llms-full.txt

llms.txt is a Markdown index at your site root: what the project is, when to use it, when not to, how to install, and one line per docs page with its .md link. llms-full.txt is every docs page concatenated, for agents that want to load everything once.

The "when not to use it" section is the part people skip and the part that saves you support tickets. If your registry is React and Tailwind only, say so, or an agent will try to install it into a Vue project.

Keep the install command in the first ten lines. Agents read the top.

5. Run an MCP server, read-only, no key

The shadcn CLI has its own MCP server (npx shadcn@latest mcp) that searches any registry in components.json. That covers installs. It does not cover docs, keyboard maps or examples.

So I run a second one at https://hextaui.com/mcp, Streamable HTTP, read-only, no API key, with five tools: search_docs, get_component, get_component_api, get_examples and get_install_command. Claude Code connects with one line:

claude mcp add --transport http hextaui https://hextaui.com/mcp

Cursor and VS Code take the same URL in their MCP config. Once connected, "add a HextaUI combobox with async results" turns into a docs search, an API read and the right install command, with no guessing in between.

Make it discoverable too. Publish a server card at /.well-known/mcp/server-card.json and a server.json in the MCP registry format. Agents and the tools around them are starting to look there first.

6. Describe the HTTP surface with OpenAPI and real errors

Everything above is also plain HTTP, and agents increasingly call HTTP directly. Publish an openapi.json with operation ids and typed responses. Return errors as RFC 9457 application/problem+json with a resolution field that says what to do next:

{
  "type": "https://hextaui.com/docs/api#not-found",
  "title": "Component not found",
  "status": 404,
  "detail": "No component named 'modal'.",
  "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json."
}

An agent that gets a 404 with a hint recovers. An agent that gets an HTML error page writes the component from memory.

7. Ship a skill file

Claude Code and a growing list of agents read SKILL.md files that explain how to use a tool. Put one at /.well-known/agent-skills/<name>/SKILL.md: how to find a component, read its docs, and install it, with the exact commands. It is a page of Markdown and it is the highest-leverage page on the site.

8. Test with the agents, not with yourself

Open a fresh Next.js project in Claude Code with your MCP server connected and no other context. Ask it to "add a date picker from with a range and a disabled weekend rule". Watch what it does. Every wrong guess is a gap in your .md docs or your llms.txt.

Then do the same in Cursor with only llms.txt and no MCP. Then with nothing but the URL. The registry should degrade gracefully through all three.

What this gets you

An agent with the MCP server or the .md docs connected reads the props table instead of guessing it, runs the install command instead of rewriting the component, and installs the dependencies in the right order. The registry side of HextaUI was about a week of work. The agent side took longer, and it is the part that made the registry usable by the people who now do most of the installing.

If you want to see all of it live: hextaui.com/llms.txt, any docs page with .md appended, the MCP docs, and the API docs with the OpenAPI spec.

FAQ

Do I need my own MCP server if the shadcn CLI has one? The shadcn MCP covers search and install across registries in components.json. Your own server covers docs, APIs and examples. Most registries benefit from both.

Should the MCP server require an API key? Not for public docs. Every key you require is an agent that gives up. Keep auth for private items and use bearer tokens through components.json headers.

How do I generate the Markdown docs without duplicating content? Render the same component tree the page uses and serialize it to Markdown. One source, two formats.

What goes in llms.txt? A description, when to use and when not to, the install command, the namespace snippet, and one line per docs page linking to its .md.

The states shadcn/ui leaves to you: loading, success, error, empty and reduced motion

Preet Suthar — Fri, 16 Oct 2026 04:25:10 +0000

Search "shadcn button loading state" and you will find a hundred snippets that do the same thing: add an isLoading prop, swap the label for a spinner, disable the button. Ship that and your app will feel worse than before you added it.

That is not a knock on shadcn/ui. It gives you a clean starting point and leaves the states to you, on purpose. But "the states" are where most of the feel of an interface lives, and almost nobody budgets time for them. This is the list of states I handle in every component I ship, and the specific timings that separate "finished" from "works".

1. Loading that does not flicker

The naive loading button shows a spinner the instant you click. Most requests finish in under 200ms, so what the user sees is a flash of spinner and then the result. It reads as jitter.

Two rules fix it:

Wait before you show the spinner. If the request finishes within about 150ms, never show it at all.
Once shown, keep it up for a minimum time. Around 400ms. A spinner that appears for 30ms is worse than no spinner.

const spinnerDelay = 150
const minimumSpinnerTime = 400

That is a hook, not a prop. Here is the shape:

const { buttonProps, track } = useButtonFeedback()

<Button {...buttonProps} onClick={() => track(save())}>
  Save
</Button>

track takes the promise. The hook decides whether the request was fast enough to skip the spinner, holds the spinner long enough not to flicker, and moves the button into success or error when the promise settles. The HextaUI useButtonFeedback hook and useDelayedLoading do exactly this, and they are small enough to read in one sitting.

The same delay rule applies to skeletons. A skeleton that appears for 50ms and gets replaced by the content is a flash of grey. Delay it by 150ms, and when the content arrives, fade it in without moving anything around it.

2. Success and error, in place

After a save succeeds, the button should say so. "Saved" with a check, for about two seconds, then back to idle. After it fails, the button should say that too, and hold the error longer, about four seconds, because people need time to read an error and decide what to do.

Two details that matter more than they sound:

Do not reset while the pointer is on the button. If someone is hovering, they are reading. Reset after they leave.
Ignore clicks while the request is in flight. Not with disabled, which removes the button from the tab order and makes screen readers skip it. Use aria-busy and ignore the click.

A Switch has the same problem in a smaller space. Flip it, send the request, and if the request fails, flip it back. The user needs to see the rollback, so animate it, and show a brief pending state while the save is out.

3. Invalid, without punishing typing

Shake the field when a submit attempt finds it invalid. Never shake while someone is still typing. The rule is the trigger: validation on submit or on blur gets the shake, validation on change does not.

The shake itself should be short, three or four oscillations in about 300ms, and under prefers-reduced-motion it becomes a color change on the border and nothing else.

Native :user-invalid helps here. It only matches after the user has interacted, so you can style the invalid state in CSS without a touched flag in React.

4. Empty is a state, not an absence

An empty list is where new users land first, and the default is a blank area with a header above it. Every empty state needs three things: an icon or illustration so the space reads as intentional, one sentence that says what will appear here, and the action that makes something appear.

This is cheap to build and almost always skipped because the person building the feature has test data. Clear your database once in a while.

5. Reduced motion is not "no motion"

prefers-reduced-motion: reduce is on for a meaningful share of users, and the lazy implementation is a global * { transition: none }. That removes the information motion was carrying. A dialog that snaps open with no fade is harder to parse than one that fades.

The rule I use: anything that moves across the screen becomes a fade. Anything that fades stays a fade. Anything that loops stops. Durations get shorter, not zero.

Put the check in one place so every component reads it:

export function prefersReducedMotion() {
  return window.matchMedia("(prefers-reduced-motion: reduce)").matches
}

And share the easing curves and durations too. If every component picks its own cubic-bezier, the app will feel like it was built by six people, because it was.

6. Motion you can interrupt

Open an accordion, then close it halfway through the opening animation. In a lot of implementations, it finishes opening and then closes, or it jumps. The right behavior is to reverse from wherever it is.

The Web Animations API makes this easy: keep a reference to the running animation, and on the next toggle, read its current time and animate from the current computed height. CSS transitions on height: auto cannot do this, and grid-template-rows: 0fr to 1fr can but is harder to reverse mid-way. Pick the approach that lets you interrupt.

7. Touch targets and the iOS zoom

Two things break on phones that you will never see on a laptop:

Inputs under 16px zoom the page on iOS Safari. Keep input text at 16px on coarse pointers even if your theme is 15px elsewhere. A single @media (pointer: coarse) rule covers it.
Tap targets under 44px miss. Buttons can be 32px tall on desktop and grow on touch screens through the same media query.

8. Right-to-left

If you ever ship to Arabic or Hebrew users, every ml- and pl- and left- in your components is a bug. Use logical properties: ms-, ps-, start-. shadcn/ui added RTL support in January 2026, so new components you pull are fine, but the ones you copied in 2024 are not.

Where this leaves you

None of these is hard. All of them together is a few weeks of work on a component set the size of shadcn/ui, and the work is invisible when it is done, which is why it gets cut.

I built HextaUI because I kept doing this work on every project. It is a free, MIT-licensed registry you add to a shadcn/ui project. Same CLI, same component names, same theme tokens, and every one of the states above already handled, down to the 150ms spinner delay. If you would rather own the code and write the states yourself, the hooks are standalone and you can install just those.

npx shadcn@latest add https://hextaui.com/r/use-button-feedback.json

FAQ

Should I disable a button while loading? Set aria-busy="true" and ignore clicks. disabled removes it from the tab order and hides it from screen readers mid-action.

How long should a success state show? About two seconds, longer if the pointer is still on the control. Errors about four seconds.

Is a skeleton always better than a spinner? A skeleton is better when you know the shape of what is coming. A spinner is better for actions. Both need the 150ms delay.

Does reduced motion mean I should remove all animation? No. Replace movement with fades, stop loops and shorten durations. Keep the information.

Vercel's AI Elements is being deprecated. Here are the alternatives for shadcn/ui AI chat UI

Preet Suthar — Fri, 16 Oct 2026 04:25:05 +0000

If you built an AI chat with Vercel's AI Elements this year, the repository now carries a notice: the library will be deprecated at the end of November 2026, replaced by AI Elements from shadcn/ui.

This post covers what that means for your code, what the replacement is, and the other options if you are starting an AI chat UI with shadcn/ui in late 2026. I maintain one of those options, HextaUI, so I will say where it fits and where it does not.

First: your code keeps working

AI Elements was a shadcn-style registry. The components were copied into your project. There is no package to stop receiving updates, so nothing breaks on 1 December. The deprecation means no new components and no fixes from Vercel, and the docs will eventually point elsewhere.

You have time. Do not rush a migration this week.

What replaces it

In October 2026 shadcn/ui published its own AI Elements: 21 patterns for agentic interfaces built from shadcn/ui components. Chat, Prompt Input, Reasoning, Tool, Plan, Subagent and more. Each pattern page shows how to render it from AI SDK message parts. There is no package. You copy each pattern in.

They ship alongside two new components, Trace and Code Block, that work across Base UI, React Aria and Radix.

Migration from the Vercel library is meant to be low-friction. Export names and props are kept where the pattern was rebuilt, and each pattern page includes a migration prompt you can hand to an AI coding agent. Elements that were not rebuilt are not covered, so check the list against what you use.

The honest difference between pieces and screens

Every option below falls into one of two camps, and knowing which you want saves a week.

Pieces give you a Message, a Prompt Input, a Tool component. You design the screen and decide what happens when a reply fails, when a stream is stopped, when a tool needs approval, when an upload dies. Both versions of AI Elements, and prompt-kit, are pieces.

Screens give you the chat thread, composer, tool call list and settings pages with those decisions already made. You wire data in and restyle with your theme tokens. HextaUI's blocks and complete apps like Vercel's AI Chatbot template are screens.

Pieces are free and flexible. Screens are faster and opinionated. Neither is wrong.

Five options compared

1. AI Elements from shadcn/ui

Free, MIT, maintained by the shadcn team, built for Base UI, React Aria and Radix. Pieces, not screens. The natural default if you want to compose your own and stay on the most-used registry. New as of October 2026, so expect the pattern list to grow and the rough edges to be sanded over the next few months.

2. prompt-kit

Free, MIT, installs with the shadcn CLI. Prompt Input, Message, Reasoning, Chain of Thought, Tool, File Upload and example blocks including a chat app with a history sidebar. Pieces, with good examples. Built on Radix, so a Base UI project carries both primitive layers while you use it.

3. assistant-ui

Free, MIT, with an optional paid cloud for saved threads. This one is different in kind: it is a chat framework with its own runtime that manages the conversation, plus headless primitives and styled components that read from it. Adapters for the AI SDK, LangGraph, LangChain, AG-UI and others. Pick it if you want the runtime to own the chat state. Skip it if your state already lives in useChat or your own store and you do not want anything wrapping your app.

4. shadcn-chatbot-kit and the AI Chatbot template

Blazity's shadcn-chatbot-kit is a smaller set of chatbot components. Vercel's AI Chatbot is a complete Next.js app with sign-in and a database, which is the canonical reference if you want to see every piece wired. Both are useful to read even if you do not adopt them.

5. HextaUI blocks

Screens. A Chat Thread where failed replies offer Try again, stopped replies say so, and edits and retries become versions you can switch between. Tool Calls with every AI SDK tool state including approvals with a "do this instead" reason. Streaming and Markdown that never show half-typed syntax. A Prompt Input that is safe with Japanese and Chinese input, shows upload progress and retry, queues messages typed during a reply and keeps drafts across reloads. Plus the screens around a chat product: settings, models, API keys, billing, team, security.

The components underneath are free and MIT. The AI blocks are HextaUI Pro, a one-time payment with every later block included, and Prompt Input is free. Built on Base UI, reads AI SDK message parts without importing the SDK. Not for you if you want everything free, or if you want Radix.

At a glance

	Camp	Price	Primitives	AI SDK
AI Elements (shadcn/ui)	Pieces	Free	Base UI, React Aria, Radix	Used in examples
AI Elements (Vercel)	Pieces	Free	Radix	Required by setup
prompt-kit	Pieces	Free	Radix	Optional
assistant-ui	Runtime	Free, paid cloud	Own	Adapter
HextaUI	Screens	Components free, blocks paid once	Base UI	Optional, same parts shape

How to decide

You are starting fresh and want to compose your own: AI Elements from shadcn/ui.
You already have Vercel's AI Elements in your tree: keep it until you need something new, then move pattern by pattern using the migration prompts.
You want a runtime to manage threads, branching and persistence for you: assistant-ui.
You want the chat and the product screens around it done, with the failure states handled, and you are fine paying once: HextaUI.

All of these copy source into your project and use the shadcn/ui theme tokens, so you can mix them one screen at a time. The one caution is primitives: mixing a Radix-based kit into a Base UI project works, but you ship both.

I keep a more detailed comparison with the full piece-by-piece mapping at hextaui.com/compare/ai-elements, and a seven-way look at shadcn AI chat templates.

FAQ

When exactly is Vercel's AI Elements deprecated? The repository says the end of November 2026.

Will my existing AI Elements components break? No. They live in your repository. They stop receiving updates.

Is the new AI Elements a package? No. It is a set of patterns you copy in with the shadcn CLI, the same model as shadcn/ui itself.

Can I use HextaUI blocks without the Vercel AI SDK? Yes. They take messages as props in the AI SDK's parts shape, and do not import the SDK.

How to build an AI chat UI with shadcn/ui and the Vercel AI SDK that survives real users

Preet Suthar — Fri, 16 Oct 2026 04:25:00 +0000

The demo takes an afternoon. useChat from the AI SDK, a list of messages, a textarea, and tokens stream onto the screen. Everyone on the team is impressed.

Then a real person uses it. They hit Enter while composing Japanese and send half a word. They stop a reply and the UI shows nothing. A tool call wants approval mid-stream and there is no UI for that. They scroll up to re-read something and the view yanks them back to the bottom with every token.

I have built this screen more times than I would like, most recently as the blocks behind HextaUI. This is the checklist of what a chat UI has to handle before it is done, with the shadcn/ui and AI SDK specifics for each.

Start from message parts, not strings

The AI SDK's useChat returns messages made of parts: text, reasoning, tool calls with their state, sources, files. Render the parts, not a concatenated string. Every feature below depends on it.

import { isToolUIPart } from "ai"

{message.parts.map((part, i) => {
  if (isToolUIPart(part)) return <ToolCall key={i} part={part} />
  switch (part.type) {
    case "text":
      return <Markdown key={i} text={part.text} />
    case "reasoning":
      return <Thinking key={i} text={part.text} />
    case "source-url":
      return <Source key={i} url={part.url} />
    default:
      return null
  }
})}

Tool parts are typed tool-<name>, so isToolUIPart is the reliable check.

Keep your blocks free of the SDK import. Take parts as props. Then the same components work with a LangGraph backend or your own server once you map its output to the same shape.

The composer

The textarea is where most of the bugs live.

Enter sends, Shift+Enter breaks a line. Everyone does this. Almost nobody handles composition. When someone types Japanese, Chinese or Korean, the IME is open and Enter confirms the candidate, not the message. Check event.nativeEvent.isComposing and bail:

function onKeyDown(event: React.KeyboardEvent<HTMLTextAreaElement>) {
  if (event.key !== "Enter" || event.shiftKey) return
  if (event.nativeEvent.isComposing) return
  event.preventDefault()
  submit()
}

Grow with the text, within limits. One line to start, up to about eight rows, then scroll. Animate the height change, and never through React state on every keystroke. Measure scrollHeight in a layout effect and set the height on the DOM node. Any setState in a native input listener will eventually drop or delay keys under load.

Drafts survive a reload. Save the draft to localStorage keyed by chat id, debounced. People lose long prompts to accidental refreshes and never forgive you.

Queue messages typed during a reply. If the model is still writing and the user sends another message, either disable sending or queue it and send when the stream ends. Silently dropping it is the worst option and it is the default.

Attachments show progress and retry. Uploads fail. Show the failure on the attachment card with a retry, not as a toast that disappears.

Streaming that reads well

Models emit tokens in bursts. If you render exactly what arrives, text stutters: nothing, then twelve words, then nothing. Smooth it. Reveal characters at a steady pace that speeds up when the buffer grows, so you never fall far behind the stream but never stutter either.

Markdown during streaming has its own trap: half-typed syntax. The model has written **bold and not yet closed it, so your renderer shows literal asterisks for a frame, then bold text. Hold back incomplete inline syntax until it closes, or until the stream ends.

Code blocks need the same care. Highlight incrementally and never re-highlight the whole block on every token.

Stop, retry, edit and versions

Stop should leave the partial reply on screen, with a visible "Stopped" marker so the user knows it is incomplete. Do not delete it.

Retry on a failed reply is a button on the message, not a hidden gesture. Connect it to regenerate().

Edit an earlier message creates a branch. Both the old and new reply exist. Show a small 1 / 2 switcher on the message so the user can flip between versions. This is where a lot of homegrown chat UIs give up, and it is the feature people miss most from ChatGPT and Claude.

Failed replies get a reason and a retry. "Something went wrong" with no action is a dead end.

Scrolling

Follow new tokens when the user is at the bottom. The moment they scroll up, stop following, and show a "jump to latest" button with a count of what they missed. When they jump, follow again.

Loading older history at the top must not move the view. Measure the scroll height before and after you prepend, and adjust scrollTop by the difference in the same frame.

If the user sends a message, scroll so their message pins to the top of the viewport and the reply streams below it. That is how the two big chat apps behave now and users expect it.

Tool calls and approvals

The AI SDK gives each tool part a state: input-streaming, input-available, output-available, output-error, and with human-in-the-loop, approval-requested, approval-responded and output-denied. Every state needs a look.

Reads and searches can fold into a one-line summary. Edits, commands and errors should stay expanded. Approvals block the stream and need a clear Allow and Deny, plus a way to say "do this instead" that sends text back to the model as the denial reason.

Show the result when it is useful. A file edit opens into a diff. A command opens into a terminal with the output. A search opens into results. A tool call that only says "Done" teaches users to ignore tool calls.

Thinking and sources

Reasoning parts should be collapsible and collapsed by default once the answer starts. While the model is still thinking, a live label that follows each step ("Searching docs", "Reading three files") is far more reassuring than a spinner.

Citations belong next to the claims they support, inline, not in a list at the bottom nobody reads.

Accessibility you cannot skip

New messages announce through a role="log" region, so screen reader users hear replies.
The stop button is reachable by keyboard and has a label.
Streaming text should not fire a hundred live-region announcements. Announce when the message completes, or at sentence boundaries.
Every icon-only button has aria-label.

Putting it together

If you want the pieces, shadcn/ui shipped AI Elements in October 2026: 21 patterns you copy into your project and compose yourself, including Chat, Prompt Input, Reasoning and Tool. Vercel's earlier AI Elements library is being deprecated at the end of November 2026 in favor of them.

If you want the screens already assembled with the states above worked out, that is what the HextaUI blocks are: a Chat Thread with stop, retry and versions, Tool Calls with every AI SDK state and approvals, Streaming and Markdown that never show half-typed syntax, and a Prompt Input that handles CJK input, uploads, queues and drafts. Prompt Input is free. The rest is a one-time purchase. All of it reads AI SDK message parts and none of it imports the SDK, so it works with any backend you can map.

You can try the whole thing assembled as a chat app at hextaui.com/blocks/hexta-ai before installing anything.

FAQ

Do I need the Vercel AI SDK to use these patterns? No. The message-parts shape is the useful part. Any backend works once you map its output to parts.

How do I handle Enter with an IME? Check event.nativeEvent.isComposing in your keydown handler and return early.

Should streaming text update a live region on every token? No. Announce at completion or at sentence boundaries, or screen readers become unusable.

What happens to a stopped reply? Keep the partial text and mark it as stopped. Never delete what the user has already read.

shadcn/ui switched to Base UI. Here is what actually changes in your code

Preet Suthar — Fri, 16 Oct 2026 04:24:28 +0000

On 3 July 2026, npx shadcn init started picking Base UI instead of Radix. If you have read the headlines and nothing else, you probably think one of two things: that Radix is dead, or that nothing changed. Neither is true.

I maintain HextaUI, a shadcn/ui registry built on Base UI, so I have spent most of this year inside both primitive layers. This is the guide I wished existed in July: what changed, what did not, every API difference you will hit, and the order to migrate in if you decide to.

What changed, in one paragraph

New shadcn/ui projects get Base UI primitives. Radix is still fully supported. The shadcn team said every update and new component ships for both libraries, unless a component only exists in Base UI. Existing projects are untouched. If you want Radix on a fresh project, you pass one flag:

npx shadcn@latest init -b radix

If you have CI or scripts that call init non-interactively and expect Radix, add that flag now, before a fresh checkout surprises you.

Why the default moved

Two reasons were given. Base UI had reached a stable 1.6.0 with over six million weekly downloads, and projects created through shadcn/create were already choosing Base UI over Radix about two to one. The default followed what people were picking.

Base UI is built by the people behind Radix, Material UI and Floating UI, and the lineage shows. It covers primitives Radix never shipped, such as Combobox, Autocomplete, Number Field, Toast and Preview Card. As of September 2026 it sits at 1.8.0.

Should you migrate an existing app?

Probably not this quarter, and not all at once.

Stay on Radix if the app is stable, you are not blocked on a missing primitive, and nobody on the team has a specific complaint. Nothing you depend on is going away.

Migrate if you need Combobox or Number Field without reaching for a second library, if you are already rewriting the components for Tailwind v4 anyway, or if you want to be on the layer that new shadcn/ui components target first.

Either way, read the next section before you decide, because the differences are not cosmetic.

Every API difference you will actually hit

I grouped these by how they fail. The first group breaks your build. The second group compiles fine and changes behavior silently, which is worse.

Build-breaking changes

asChild becomes render. This is the one everyone meets first.

// Radix
<DialogTrigger asChild>
  <Button>Open</Button>
</DialogTrigger>

// Base UI
<DialogTrigger render={<Button />}>Open</DialogTrigger>

The render prop takes an element or a function. The function form gives you the state, which is useful for things like a trigger that changes its icon when open.

Anchored popups gain a Positioner. Menu, Select, Popover and Tooltip go from Portal > Content to Portal > Positioner > Popup. Dialog has no Positioner; it uses Backdrop and Popup.

Overlay is now Backdrop. Rename and move on.

Select values are nullable. A controlled Select holds Value | null, not string. Your useState<string>("") becomes useState<string | null>(null), and every place that read the value as a string needs a guard.

Accordion and Toggle Group values are always arrays. Even in single mode, value="a" becomes value={["a"]}. Tabs keep a single value.

onOpenChange has a second argument. Radix lets you call event.preventDefault() to stop a close. Base UI passes (open, details) and you call details.cancel(). The details.reason field tells you whether it was the Escape key, an outside press or something else, which is handy for "unsaved changes" dialogs.

Open-state selectors change. data-[state=open]: variants become data-open:. This one hides in your className strings and in cva variants, so grep for data-[state= before you call the migration done.

Silent behavior changes

Tabs activate manually by default. In Radix, arrow keys move focus and activate the tab. In Base UI, arrow keys move focus and you press Enter or Space to activate. If your tests or users expect the Radix behavior, set activateOnFocus on the list.

Checkbox and radio menu items keep the menu open. closeOnClick defaults to false for CheckboxItem and RadioItem. Plain items still close. This is arguably the better default, but it is a change your users will notice.

Navigation menus open faster. Base UI's hover delay defaults to 50ms. Radix's delayDuration defaulted to 200ms. Fast menus feel great until someone sweeps their mouse across the header and three panels fire in a row. Tune it.

A migration order that does not hurt

Keep both libraries installed. Move one component per commit. Run your tests between each. In this order:

Leaf components with no popup: Switch, Checkbox, Slider, Toggle, Progress. Mostly rename work.
Tabs and Accordion. Fix the array values and decide on activateOnFocus.
Dialog and Alert Dialog. Learn the Backdrop and Popup structure and the details.cancel() pattern here, where there is no Positioner to confuse things.
Popover and Tooltip. Add the Positioner.
Select, Combobox, Dropdown Menu, Context Menu. Nullable values, closeOnClick, and the whole popup tree. Do these last, with the most tests.

Replacing a component with the Base UI version is one CLI command, and your source is in git, so review the diff rather than trusting it:

npx shadcn@latest add dialog --overwrite

Then git diff components/ui/dialog.tsx and read every line before you keep it.

What I would not do

I would not run a codemod across the whole tree and hope. The build-breaking changes are easy to find. The silent ones are not, and a codemod cannot tell you that your settings page now needs two keystrokes to switch tabs.

I would also not switch primitive layers and redesign the components in the same PR. The point of shadcn/ui is that you own the code. Owning it means reading the diff.

If you want the migration done for you

HextaUI is a registry you add to a shadcn/ui project. Every component is already written on Base UI, keeps the shadcn/ui names and props, and uses the same theme tokens, so npx shadcn@latest add https://hextaui.com/r/dialog.json --overwrite lands a Base UI Dialog in components/ui next to your other files. The components are MIT and free. The HextaUI vs shadcn/ui page lists what is different and when plain shadcn/ui is the better pick.

FAQ

Is Radix deprecated? No. shadcn/ui ships every component for both libraries, and the team still runs Radix in production.

Can I mix Radix and Base UI components in one project? Yes. You carry both dependencies while you migrate. Many projects will stay mixed for a long time and that is fine.

Do I need to change my theme tokens? No. --background, --primary, --radius and the rest are unchanged. The primitive layer is independent of the Tailwind side.

Does Base UI support React Server Components? Base UI primitives are client components, the same as Radix. Keep the "use client" directive where shadcn/ui puts it.

Where is the official change log? The July 2026 entry is at ui.shadcn.com/docs/changelog/2026-07-base-ui-default.

Typeform was too expensive so I built my own forms

Preet Suthar — Fri, 11 Jul 2025 05:56:24 +0000

I'm a solopreneur and run a web design agency.

I create open-source apps, but I also work as a freelancer and designer. I was accepting any new freelance project via forms on my agency website.

I was using Typeform, but as time went by and more people submitted forms, it got more and more expensive. That time, I thought to use Google Form, but it was way too blocky and looked very unprofessional on my agency website.

So I thought to build my own forms for my own usage, and it turns out it almost doubled form submissions and inquiry calls.

I was happy, so I thought to build it for everyone and make it open-source.

I added AI functionalities using Vercel AISDK. I can generate forms almost instantly using AI and also added analytics AI so that users can talk with their forms—more like talk with their analytics data.

[https://ikiform.com](https://ikiform.com

I've been building this publicly, sharing updates on my X account preetsuthar17

I hope this product will be as helpful to you as it was for me. Would love your feedback pls

Preet

Prevent Spam Bot Attacks in Form Submissions

Preet Suthar — Sat, 24 May 2025 08:18:18 +0000

Spam bot attacks on forms can be a nuisance, leading to spam submissions and potential security risks. Here's a simple method to prevent spam bot attacks in form submissions using a hidden field.

Step 1: Add a Hidden Field

Add a hidden field to your form. This field should be invisible to users but visible to bots. For example:

const [honey, setHoney] = useState("");

<input
  type="text"
  value={honey}
  onChange={(e) => setHoney(e.target.value)}
  tabIndex="-1"
  area-hidden="true"
/>;

Step 2: Validate the Hidden Field

When processing the form submission, check if the hidden field is empty. If it's not empty, it's likely a bot submission.

const handleSubmit = (e) => {
  e.preventDefault();

  if (honey) {
    // This is a bot submission
    console.log("Spam bot detected!");
    return;
  }

  // Process the form submission
  console.log("Form submitted successfully!");
};

Complete Example

import React, { useState } from "react";

const Form = () => {
  const [honey, setHoney] = useState("");

  const handleSubmit = (e) => {
    e.preventDefault();

    if (honey) {
      console.log("Spam bot detected!");
      return;
    }

    console.log("Form submitted successfully!");
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={honey}
        onChange={(e) => setHoney(e.target.value)}
        tabIndex="-1"
        area-hidden="true"
      />
      <button type="submit">Submit</button>
    </form>
  );
};

Actual users won't see the hidden field, but bots will fill it out, allowing you to filter out spam submissions easily. This method is simple and effective for preventing spam bot attacks in form submissions.

Actual Twitter thread: link

Add a badge to the filename in Fumadocs

Preet Suthar — Sat, 24 May 2025 08:16:58 +0000

This is the type of badge you can add to the filename in Fumadocs.

It is very easy to add a badge to the filename in Fumadocs.

first step is to extend the frontmatter schema.

go to source.config.ts file in root folder of fumadocs project and add the following code.

export const docs = defineDocs({
  docs: {
    schema: frontmatterSchema.extend({
      new: z.boolean().default(false),
    }),
  },
});

now we can basically add the frontmatter prop in lib/source.ts file.

Make sure to rename the lib/source.ts to lib/source.tsx

export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
  pageTree: {
    attachFile(node, file) {
      if (!file) return node;

      const data = file.data.data as {
        new: boolean;
      };

      // JSX nodes are allowed
      if (data.new) {
        node.name = (
          <>
            {node.name}
            <div className="bg-fd-primary">NEW</div>
          </>
        );
      }

      return node;
    },
  },
});

now to use this we can just use new prop in the frontmatter.

---
title: "File Upload"
description: "Animated and interactive file upload component."
new: true
---

final result would be like this.

Guide to minimal website design

Preet Suthar — Sat, 24 May 2025 08:15:51 +0000

Minimalist website design is a refined art form focused on simplicity, clarity, and functionality. By stripping away nonessential elements, it highlights what truly matters and creates a seamless experience for visitors.

7 Principles of Minimalist Web Design

Embrace Simplicity
Prioritize User Experience
Showcase Quality Visuals
Leverage Whitespace
Highlight Content
Ensure Fast Load Times
Implement Clear Calls to Action

1. Embrace Simplicity

At the heart of minimalist design is simplicity. A straightforward, uncluttered layout with a restrained color palette, fonts, and graphics creates an inviting environment. Generous whitespace not only enhances aesthetics but also improves readability, allowing your content to shine.

A good example is SquareSpace website, simple and clean showing only content that is important

2. Prioritize User Experience

A user-centric approach is essential in minimalist design. Your website should be intuitive, with streamlined navigation and legible typography. Given the increasing use of mobile devices, ensure that your site is responsive and offers a smooth experience on all screen sizes.

3. Showcase Quality Visuals

Minimalism does not equate to a lack of visual appeal. Instead, select high-caliber images or illustrations that resonate with your brand’s identity. Opt for unique visuals rather than generic stock photos to add a touch of personality and distinction.

4. Leverage Whitespace

Whitespace, or negative space, is a critical design element that lends structure and focus to your layout. It helps guide the visitor’s eye toward key content and creates a sense of balance and harmony throughout the site.

5. Highlight Content

In minimalist design, content remains the focal point. Employ concise and precise language to communicate your message effectively. Use headings and subheadings to break up text, making it both engaging and easy to navigate, while avoiding distractions that detract from your core message.

Stripe‘s website is both functional and visually appealing. The website features a clean white background, straightforward typography, and plenty of negative space, making it easy to navigate and understand. The design highlights the company’s products and services without distracting users with unnecessary graphics or information.

6. Ensure Fast Load Times

A hallmark of minimalist design is its ability to enhance performance. By using a lightweight theme, compressing images, and minimizing extraneous code, you can achieve faster load times, thereby improving overall user satisfaction and search engine performance.

7. Implement Clear Calls to Action

While the design is minimalist, your calls to action (CTAs) should be unmistakably clear and compelling. Use direct language and contrasting elements to ensure that your CTAs stand out, guiding visitors seamlessly toward the desired actions.

Conclusion

In summary, minimalist website design is both an art and a science—a pursuit of elegance through simplicity. By adhering to these seven principles, you can craft a website that not only captivates visually but also delivers a superb user experience.

A minimalist approach ensures that every element has a purpose, transforming your website into a sophisticated, efficient, and enjoyable digital space that leaves a lasting impression on visitors. Embrace simplicity, enhance functionality, and let your content take center stage while delighting your audience with a touch of fun and refinement.

Force refresh page in Next.js

Preet Suthar — Sat, 24 May 2025 08:13:50 +0000

If you’re inside a React component, grab the router instance with the useRouter hook:

import { useRouter } from "next/router";

function MyComponent() {
  const router = useRouter();

  // reload the current page
  router.reload(window.location.pathname);
}

If you need to trigger a reload from outside a component—for example, in a plain utility module—just import the singleton Router instead:

import Router from "next/router";

// reload the current page
Router.reload(window.location.pathname);

Prefetching content in Next.js

Preet Suthar — Wed, 23 Apr 2025 04:50:18 +0000

When linking two pages in a Next.js application, the built-in <Link> component allows for seamless client-side navigation. Instead of triggering a full page reload like traditional websites, Next.js uses frontend routing to display the new page instantly, making for a faster user experience.

But that’s not all—Next.js also prefetches linked pages automatically. As soon as a <Link> element enters the viewport (i.e., becomes visible on screen), Next.js begins preloading the linked page in the background—provided it’s an internal link within your site. This makes navigation nearly instant when users click the link.

However, this prefetching behavior only works in production mode. If you're running your app in development with npm run dev, prefetching won't be triggered. To see it in action, stop the dev server, run npm run build to generate your production bundle, and start the app with npm run start.

You can observe this behavior in your browser’s Network tab. Once the page finishes loading (after the load event fires), links that are already visible (i.e., above the fold) start prefetching. Links that are out of view will be prefetched as the user scrolls them into the viewport.

Prefetching happens automatically on fast internet connections (like Wi-Fi or 3G+), unless the browser sends a Save-Data header indicating a preference for reduced data usage.

If you want to disable prefetching for a specific link, you can do so by passing prefetch={false} to the <Link> component:

<Link href="/contact" prefetch={false}>
  Contact
</Link>

How User Feedback Can Transform Your SaaS Product

Preet Suthar — Thu, 02 Jan 2025 04:40:52 +0000

Your product’s success doesn’t come from guessing what users want—it comes from listening to what they actually need. Let’s explore how you can turn user feedback into your secret weapon.

Why User Feedback is a Game-Changer

Imagine this: you spend months building what you think is the perfect SaaS product. It looks great, it works flawlessly, but after launch, users aren’t as thrilled as you hoped. That’s when feedback becomes your guiding star.

How to Collect Useful Feedback

Pro Tip: Don’t sit back and wait. Go out and ask your users for their thoughts.

Here are some effective ways to gather feedback:

In-app Surveys: Add short surveys that pop up at the right time—like right after users try a new feature. Ask something simple, like, “Did this feature solve your problem?” Fresh experiences lead to honest answers.
User Interviews: Chat directly with users, both happy and unhappy ones. These conversations often uncover issues that numbers alone can’t. One founder completely revamped their onboarding process after learning users felt overwhelmed in the first 10 minutes.
Usage Data: Pay attention to how users interact with your product. If a feature you thought was a must-have barely gets used, that’s valuable information.

Managing Feedback Without Losing Your Mind

The Challenge: Juggling feedback from emails, chats, surveys, and more can feel chaotic.

Here’s a simple solution: Rate This Tool. It’s a platform where you can:

Collect all your feedback in one place
Spot trends across platforms
Rank feature requests by priority
Make smarter decisions based on real data

Turning Feedback into Real Improvements

Here’s how top SaaS companies use feedback to stay ahead:

Prioritize Smartly: Not all feedback is created equal. Use a scoring system to rank requests based on how often they come up, how much impact they’ll have, and how hard they are to implement. If lots of users mention the same issue, it’s probably worth tackling.
Start Small: Instead of rolling out huge changes, test small tweaks first. One SaaS company simplified their settings page after users complained it was confusing—and saw a 25% boost in user retention.

What to Do When Things Don’t Go as Planned

Lesson Learned: Feedback can guide your next big idea Even if your product doesn’t take off.

Document Everything: Record all feedback, including the context. Sometimes a failed idea plants the seed for a successful one. For example, Slack grew out of feedback from a failed gaming project.
Find the Patterns: Look for common threads in feedback from different users. Sometimes, the problem worth solving isn’t the one you originally set out to fix.

Closing the Loop with Your Users

Always let your users know their voices matter:

Thank them for their feedback
Update them on what you’ve changed because of it
Be transparent about why some suggestions might not work
Keep them involved in your journey

The takeaway: You don’t need to get everything right on day one. Success comes from creating a feedback loop that helps you keep improving.

Ready to Take Action?

Start managing your feedback better today with Rate This Tool. When all your user insights are in one place, spotting what matters, making better decisions, and building a product your users love is easier.

Remember, your users are your best product advisors. All you have to do is listen.