DEV Community: Urvish

Forms That Feel Like Progress: Building Multi-Step Registration That Doesn't Feel Like Paperwork

Urvish — Thu, 08 Oct 2026 04:51:55 +0000

Nobody wakes up excited to fill out a form.

I think that's the most honest starting point for this post. Forms are the part of every product that's standing between a person and the thing they actually wanted. They want to use your app. You want their email, their name, their team size, their preferences, their credit card. The form is the toll booth.

And for a long time I treated forms like a solved problem. You have inputs, you have labels, you have a submit button. Done. Ship it. Maybe add some validation messages in red.

Then I watched myself sign up for a bunch of products in one weekend (I was researching onboarding flows, which is a very normal thing to do on a Saturday) and I noticed something. The forms that felt worst weren't the longest ones. They were the ones that felt like they weren't going anywhere. One giant page of fields with no sense of where you were. Or multi-step flows where every "Next" click just snapped to a new screen with no connection to the last one, so you felt like you were being teleported around a government building.

The forms that felt good, even long ones, felt like progress. Every step felt like moving forward. You knew where you were, you knew roughly how much was left, and going back didn't feel like losing anything.

That feeling is what I tried to build into the Multi-Step Form in useLayouts. This post is about how it works, why it's built the way it is, what I'd change for a real registration flow, and all the stuff that went wrong along the way.

I'm Urvish, by the way. I build useLayouts, an open source MIT licensed collection of animated React components. It's built on Next.js, TypeScript, Tailwind CSS, Motion, and it plugs straight into the Shadcn CLI as a registry. The source goes into your project and you own it. Copy, customize, ship.

Why multi-step at all?

Let me argue against myself for a second, because multi-step forms aren't always the answer.

If your form has three fields, it should be one step. Please don't make someone click "Next" to go from their email to their password. That's not progress, that's just extra clicks.

Multi-step makes sense when:

The form is long enough that one page would feel overwhelming.
The questions naturally group into topics (about you, about your team, about your preferences).
Later questions depend on earlier answers.
You want people to feel committed after the first step, so they finish the rest.

That last one is a bit of a psychology thing and I want to be careful with it, because it can be used in manipulative ways. But in a good way, it's just this: once someone has typed their project name, they've started. Making that first step small and easy means they're past the hardest part, which is deciding to begin.

The Multi-Step Form demo in useLayouts is a "Create New Project" flow. Three steps:

Create New Project. Project name, due date, description.
Configuration. Team size, priority, tags.
Project Kickoff Mood. An emoji mood picker and a comment box.

It's not literally a registration form, but the structure is the same as most onboarding flows. Basics first, configuration second, something more personal or optional at the end. I'll show you how to turn it into an actual sign up later in this post.

Installing it

If you've already got the useLayouts registry in your components.json, you can skip this part:

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

Then:

npx shadcn@latest add @uselayouts/multi-step-form

Or with your package manager of choice:

pnpm dlx shadcn@latest add @uselayouts/multi-step-form
yarn dlx shadcn@latest add @uselayouts/multi-step-form
bunx --bun shadcn@latest add @uselayouts/multi-step-form

This one has more dependencies than most useLayouts components, and that's on purpose. It installs motion, react-hook-form, @hookform/resolvers, zod, date-fns, sonner, lucide-react, and react-use-measure. It also pulls in a bunch of Shadcn UI components as registry dependencies: card, button, input, textarea, select, badge, calendar and popover.

I know that's a long list. I went back and forth on it. The alternative was writing my own form state management, my own date picker, my own select. And that would've been worse in every way. Forms are a place where you really want battle tested pieces. React Hook Form and Zod are what a lot of people already use. Shadcn's form primitives are built on Radix, so the accessibility basics are handled by people who've thought harder about it than I have.

useLayouts isn't trying to replace those. It's trying to be the layer on top that makes the whole thing feel good to move through.

The core idea: one card, sliding content, animated height

If I had to explain the Multi-Step Form in one sentence: it's a single card that stays put, while the content inside slides left and right between steps, and the card smoothly grows or shrinks to fit whatever step you're on.

Each of those three parts matters, so let me go through them.

The card stays put

This is the most important decision and it's kind of invisible. The card, with its header and footer, never leaves the screen. The title changes, the description changes, the step indicator updates, the buttons update. But the frame is stable.

Why does that matter? Because it gives you an anchor. When everything on the screen changes at once, your brain has to re-orient. "Where am I? What is this? Is this still the same thing?" When the frame stays and only the content changes, your brain goes "same form, next part." It's the difference between turning a page in a book and being handed a different book.

A lot of multi-step forms I looked at would transition the entire screen. The whole card would slide out and a new card would slide in. It looks dramatic, but it actually makes the steps feel more disconnected, not less.

The content slides, and it knows which way

Here's the slide logic. It uses Motion's custom prop to pass a direction into the variants:

const variants = {
  initial: (direction: number) => {
    return { x: `${110 * direction}%`, opacity: 0 };
  },
  animate: { x: "0%", opacity: 1 },
  exit: (direction: number) => {
    return { x: `${-110 * direction}%`, opacity: 0 };
  },
};

When you click Continue, direction is 1. The new step enters from the right (110 percent to the right) and the old step exits to the left. When you click Back, direction is -1, and everything flips. The previous step comes back in from the left, and the current one leaves to the right.

That direction is set right before the step changes:

const nextStep = () => {
  if (currentStep === 2) {
    form.handleSubmit(onSubmit)();
    return;
  }
  if (currentStep < 2) {
    setDirection(1);
    setCurrentStep((prev) => prev + 1);
  }
};

const prevStep = () => {
  if (currentStep > 0) {
    setDirection(-1);
    setCurrentStep((prev) => prev - 1);
  }
};

This seems like such a small thing but it's honestly the core of the "progress" feeling. Moving forward literally moves forward, in the reading direction. Moving back literally moves back. It builds a spatial map in your head. Step 1 is over there on the left, step 3 is over there on the right, you're in the middle. You can feel where you are.

My first version always slid left, no matter which button you pressed. And going back felt so wrong. Like you clicked "Back" and the form went "okay, forward to the past." It was disorienting in a way I couldn't explain until I watched it in slow motion and realized the direction was lying.

Why 110 percent and not 100? Because at exactly 100 percent, there were moments where the edges of the old and new content would kind of touch and overlap visually, especially with the padding. 110 gives a little gap so they feel like separate pages sliding past each other, not one long strip.

The height animates to fit

This is the trickiest part technically, and it's the one that makes the biggest difference.

Each step has different content, so each step is a different height. Step 1 has three fields including a textarea. Step 2 has a two column row of selects plus a tags input. Step 3 has the mood picker and a big comment box. If you just swap the content, the card height snaps. And when the card snaps, the footer with the buttons jumps up or down. Which means the Continue button, the thing your mouse is sitting on, suddenly moves away from your mouse.

That's awful. Imagine pressing an elevator button and having the button move.

So the content area measures itself and animates its height:

const [ref, bounds] = useMeasure();

<motion.div
  animate={{ height: bounds.height > 0 ? bounds.height : "auto" }}
  className="relative overflow-hidden"
  transition={{ type: "spring", bounce: 0, duration: 0.5 }}
>
  <div ref={ref}>
    <CardContent className="px-6 py-2 relative">
      {/* sliding steps go here */}
    </CardContent>
  </div>
</motion.div>

useMeasure from react-use-measure watches the inner div's size. Whenever the content changes, the measured height changes, and the outer motion.div springs to the new height. The overflow-hidden means the sliding content gets clipped cleanly at the card edges while it's moving.

The bounds.height > 0 check is there for the first render. Before measurement happens, the height is zero, and if you animate to zero, the card collapses for a frame and then pops open. Falling back to "auto" until there's a real measurement avoids that.

bounce: 0 on the spring is deliberate. A bouncy height change on a form would feel like the card was made of jelly. You want it to feel solid. It moves, it stops. No wobble.

popLayout is doing a quiet job

The steps are wrapped in AnimatePresence with mode="popLayout":

<AnimatePresence mode="popLayout" initial={false} custom={direction}>
  <motion.div
    key={currentStep}
    variants={variants}
    initial="initial"
    animate="animate"
    exit="exit"
    className="w-full"
    custom={direction}
  >
    {content}
  </motion.div>
</AnimatePresence>

popLayout takes the exiting element out of the layout flow while it animates away. So the old step and new step can both be on screen at once, sliding past each other, without stacking on top of each other vertically and making the card temporarily twice as tall.

If you've ever tried to build this with the default mode, you've seen the bug: during the transition, both steps are in the document flow, the card measures the combined height, and it spikes up for a moment before settling. popLayout fixes that. Took me a whole evening to figure out that's what was going on.

The custom={direction} on AnimatePresence itself matters too, and it's easy to miss. The exiting element needs to know the current direction when it exits, but it was rendered with the old direction. Passing custom to AnimatePresence lets it update the exiting child's direction so it leaves the right way. Without that, if you go forward then immediately back, the exiting step can slide out in the wrong direction.

One timing for everything

The whole form is wrapped in MotionConfig:

<MotionConfig
  transition={{
    duration: 0.5,
    type: "spring",
    bounce: 0,
  }}
>

So the slide and the height share the same feel by default. A half second spring with no bounce. That consistency matters. If the content slides at one speed and the height adjusts at another, you'll feel them as two separate things happening, and the form starts feeling busy. When they share a timing, they feel like one movement.

Half a second is slower than most of my micro-interactions. That's on purpose too. Moving between steps of a form is a bigger transition than a button press. It's a context change. A slightly longer, smoother motion gives your eyes time to track where the new content is coming from. Faster than about 0.35 and it started feeling like a snap with extra steps. Slower than 0.6 and it felt like the form was making me wait.

The step indicator: dots that stretch

In the top right of the card header there's a step indicator. It's just three little dots, but the active one stretches into a pill:

<div className="flex items-center gap-1.5 pt-1">
  {stepTitles.map((_, index) => (
    <div
      key={index}
      className={cn(
        "h-2 rounded-full transition-all duration-300",
        currentStep === index ? "w-8 bg-primary" : "w-2 bg-primary/20"
      )}
    />
  ))}
</div>

This is plain CSS transitions, not Motion. Not everything needs a spring. A width and color transition is plenty for this.

I like this pattern more than "Step 2 of 3" text, though both are valid. The dots tell you three things at a glance: how many steps there are total, which one you're on, and how many are left. And when you move forward, the pill visually travels to the right, which matches the content sliding. Everything is pointing in the same direction.

I did consider a progress bar instead. The problem with a progress bar on a three step form is it moves in big chunky jumps (33 percent, 66 percent, 100 percent), which feels less like smooth progress and more like a loading bar that keeps stalling. Dots feel more honest about the fact that there are discrete steps.

If your registration flow has more like six or seven steps, dots start getting crowded and I'd probably switch to "Step 4 of 7" text, or a segmented bar. Don't feel stuck with my choice. It's your file.

The steps themselves

Now let me walk through each step, because there are some small details in each one I'm kind of proud of.

Step 1: the easy start

"Create New Project. Start by providing the essential details for your workspace."

Three fields: project name, due date, description. The project name is a plain input. The description is a textarea. The due date uses the Shadcn calendar inside a popover, with the trigger button showing either the formatted date or "Pick a date":

<PopoverTrigger
  render={
    <Button
      variant={"outline"}
      className={cn(
        "w-full justify-start text-left font-normal",
        !watchedValues["due-date"] && "text-muted-foreground"
      )}
    >
      <CalendarIcon className="mr-2 h-4 w-4" />
      {watchedValues["due-date"] ? (
        format(watchedValues["due-date"] as Date, "PPP")
      ) : (
        <span>Pick a date</span>
      )}
    </Button>
  }
/>

date-fns's format with "PPP" gives you a nice readable date like "October 7th, 2026" instead of some ISO string. When nothing's picked, the text is muted, so it reads like a placeholder.

The whole point of step 1 is that it's easy. Things you already know the answer to. The project name is in your head. You don't need to think. Starting easy is a kindness.

Step 2: the thinking step

"Configuration. Define team access and project priority settings."

This is where you have to make some decisions. Team size and priority sit side by side in a two column grid, both using Shadcn selects. The options are defined at the top of the file:

const TEAM_SIZE_OPTIONS = [
  { label: "Select team size", value: null },
  { label: "1-5 Members", value: "1-5" },
  { label: "5-10 Members", value: "5-10" },
  { label: "10+ Members", value: "10+" },
];

const PRIORITY_OPTIONS = [
  { label: "Select priority", value: null },
  { label: "Low", value: "Low" },
  { label: "Medium", value: "Medium" },
  { label: "High", value: "High" },
  { label: "Critical", value: "Critical" },
];

The first option in each has a null value, which acts as the "nothing picked yet" state. That's why the schema allows nullable() on those fields.

Putting the two selects side by side was a deliberate layout call. They're short, they're related, and stacking them vertically made step 2 feel longer than it really was. Pairing short related fields in a row is one of the simplest ways to make a form feel lighter. It's the same number of questions, it just looks like less.

Then there's the tags input, which is my favorite little piece in the whole form. You type a tag, hit Enter, and it becomes a badge above the input:

<Input
  id="tag"
  placeholder="e.g. Design, Marketing"
  onKeyDown={(e) => {
    if (e.key === "Enter") {
      e.preventDefault();
      const val = e.currentTarget.value.trim();
      if (val) {
        const tags = form.getValues("tag") || [];
        if (!tags.includes(val)) {
          form.setValue("tag", [...tags, val]);
        }
        e.currentTarget.value = "";
      }
    }
  }}
/>

A couple of things in here that came from mistakes.

e.preventDefault() is critical. Without it, pressing Enter inside a form input submits the form. Which, on step 2 of a three step form, would be a disaster. You'd be trying to add a tag and suddenly the whole form submits half empty. I did that to myself during testing more than once before I added it.

.trim() and the if (val) check stop empty tags or tags that are just spaces. Small, but without them you could spam Enter and fill the list with blank badges.

The !tags.includes(val) check prevents duplicates. If you add "Design" twice, nothing happens the second time. I went back and forth on whether it should show some feedback in that case, like a little shake on the existing badge. I didn't add it in the demo, but if you want to, that's a great example of motion that's actually feedback: "hey, you already have that one, it's right here."

Each badge has a little × button to remove it, which filters that index out of the array. The button is type="button" so it doesn't submit the form either. Forms really want to submit. You have to keep telling them not to.

Step 3: the human step

"Project Kickoff Mood. How confident do you feel about this new project?"

This is the step I had the most fun with, and it's the one that people seem to remember from the demo.

It's a row of five emojis, from anxious to excited:

[
  { emoji: "😰", value: "anxious", label: "Anxious" },
  { emoji: "😟", value: "worried", label: "Worried" },
  { emoji: "😐", value: "neutral", label: "Neutral" },
  { emoji: "🙂", value: "good", label: "Good" },
  { emoji: "🤩", value: "excited", label: "Excited" },
]

Unselected emojis are grayscale. When you hover one, it gets its color back. When you select one, it stays in color with a soft primary tint behind it:

className={cn(
  "flex-1 p-3 md:p-4 text-2xl md:text-3xl transition-all hover:bg-muted focus:outline-none",
  watchedValues["mood"] === option.value
    ? "bg-primary/10 grayscale-0"
    : "grayscale-[1] hover:grayscale-0"
)}

Underneath, attached to the same bordered box, is a comment textarea with no border of its own, so the emojis and the comment feel like one component. "Add a comment..." And below that, a line of copy: "Your feedback helps us understand the project kickoff vibe."

I want to talk about why this step exists, because it's not really about emojis.

A lot of registration flows end on the most transactional step. Payment, or terms of service, or "confirm your email." So the last impression of the whole flow is a chore. I wanted the demo to show that the last step can be the warmest one. Something that's about the person, not about the product's data needs.

In a real sign up, maybe that's "What are you hoping to build?" or "How did you hear about us?" or literally just a mood picker for how they're feeling about trying a new tool. Whatever it is, ending on something human changes the emotional shape of the whole thing. The flow goes easy, then thinking, then personal. Not easy, thinking, bureaucratic.

The grayscale thing is a nice touch for this too. All five emojis in full color would be loud and kind of chaotic. In grayscale, the row is calm, and picking one "brings it to life." Your choice is literally the colorful thing. That's feedback.

Real talk on accessibility though: emoji buttons have a title attribute with the label, but I'd add proper aria-labels and an aria-pressed state in production so screen readers announce what each one is and which one's selected. And focus:outline-none removes the focus ring, which you should replace with a visible focus style if keyboard users are going to use this. I'll own that. The demo is optimized for showing the interaction, and the production version should be optimized for everyone.

The finish

On the last step, the Continue button turns into Finish with a check icon:

<Button type="button" onClick={nextStep}>
  {currentStep === stepTitles.length - 1 ? (
    <>
      Finish <Check className="h-4 w-4" />
    </>
  ) : (
    <>
      Continue <ChevronRight className="h-4 w-4" />
    </>
  )}
</Button>

And the Back button is disabled on step 1, since there's nowhere to go back to.

When you hit Finish, nextStep sees you're on the last step and calls form.handleSubmit(onSubmit)(). In the demo, onSubmit just logs the values and pops a Sonner toast showing the JSON:

toast(
  <pre className="mt-2 w-[340px] rounded-md bg-slate-950 p-4">
    <code className="text-white">{JSON.stringify(values, null, 2)}</code>
  </pre>
);

This is obviously a placeholder. You'll swap it for an API call or a server action. But I kept the JSON toast because it's really useful while you're customizing. You can see exactly what shape your data is in when it comes out the other end. When you add a field, you immediately see whether it made it into the payload.

The thing about validation (please read this part)

Okay, here's the honest bit. In the demo, every field in the Zod schema is optional:

const formSchema = z.object({
  "project-name": z.string().optional(),
  "due-date": z.date().optional(),
  description: z.string().optional(),
  "team-size": z.string().nullable().optional(),
  priority: z.string().nullable().optional(),
  tag: z.array(z.string()).optional(),
  mood: z.string().optional(),
  comment: z.string().optional(),
});

That's so you can click through the demo without filling anything in and actually see the transitions. If everything was required, you'd hit a wall on step 1 every time you just wanted to see how it moves.

But in your app, you'll want real validation. And with multi-step forms, there's a specific trap here.

If you just make fields required and keep the same nextStep logic, the user can click Continue on step 1 without filling the project name, move to step 2, step 3, and then hit Finish. Only then does handleSubmit run validation. And the error is for a field on step 1, which isn't even on screen anymore. So they click Finish and... nothing happens. Or an error appears somewhere they can't see.

That's one of the worst feelings a form can give you. "I did everything and it didn't work and I don't know why."

The fix is to validate each step before moving forward. React Hook Form has trigger, which validates specific fields:

const stepFields: (keyof FormValues)[][] = [
  ["project-name", "due-date", "description"],
  ["team-size", "priority", "tag"],
  ["mood", "comment"],
];

const nextStep = async () => {
  const valid = await form.trigger(stepFields[currentStep]);
  if (!valid) return;

  if (currentStep === stepFields.length - 1) {
    form.handleSubmit(onSubmit)();
    return;
  }
  setDirection(1);
  setCurrentStep((prev) => prev + 1);
};

Now Continue checks only the current step's fields. If something's wrong, you stay on that step and the FieldError components (which are already wired up under every field in the demo) show the messages right where you're looking.

Back should not validate. If someone wants to go back and fix something, let them. Blocking "Back" because the current step is incomplete is a special kind of frustrating.

And then make the schema real:

const formSchema = z.object({
  "project-name": z.string().min(1, "Give your project a name"),
  "due-date": z.date().optional(),
  description: z.string().optional(),
  "team-size": z
    .string()
    .nullable()
    .refine((v) => v !== null, "Pick a team size"),
  // ...
});

Notice the error message. "Give your project a name" instead of "Required" or "String must contain at least 1 character(s)". Error copy is part of the interaction. It's feedback. The default Zod messages are written for developers. Rewrite them for humans. It takes ten minutes and it changes how the whole form feels when something goes wrong.

Turning it into a real registration flow

Let me walk through how I'd actually adapt this for a sign up, because "Create New Project" is close but not quite.

Say you're building a SaaS and the sign up needs: email, password, name, workspace name, team size, role, and how they heard about you.

That's seven fields. On one page, it's a wall. As three steps, it can feel like a conversation.

Step 1: "Let's get you in." Email and password. That's it. This is the minimum to create an account. If someone bails after this, you at least have an account you can follow up on (with their permission, obviously).

Step 2: "Tell us about your workspace." Name, workspace name, team size. Workspace name and team size could be side by side, same as the selects in the demo.

Step 3: "One last thing." Role and how they heard about you. Both optional. Maybe the role is an emoji style picker like the mood step, or a set of chips. And a "Skip" option alongside Finish.

Here's the shape of the changes in the actual file:

// Change Here
const stepTitles = [
  {
    title: "Let's get you in",
    description: "Just your email and a password to start.",
  },
  {
    title: "Your workspace",
    description: "This is where your team will work together.",
  },
  {
    title: "One last thing",
    description: "Totally optional, but it helps us help you.",
  },
];

That // Change Here comment sits right above stepTitles in the real component, same as other useLayouts components, so you know where to start editing.

Then you'd update the switch (currentStep) cases with your fields, update the schema, add the per step validation from above, and replace the toast with your actual sign up call.

The motion stuff, the sliding, the height, the direction, the dots, all keeps working without you touching it. That's the part I want useLayouts to handle so you don't have to. You bring the fields and the copy. The flow already feels right.

Also, if you have more than three steps, a few things in the demo are hardcoded to three, like currentStep === 2 and currentStep < 2 in nextStep. Swap those for stepTitles.length - 1 and you're good for any number of steps. I'd honestly make that change even if you stay at three, just so it's not a trap later.

Failure modes I've hit (or seen coming)

Here's the list of stuff that can go wrong with multi-step forms in general, and how I think about each one with this component.

Focus gets lost between steps

When you click Continue, the step content changes, but keyboard focus stays on the Continue button. That's actually fine for mouse users. For keyboard and screen reader users, though, the new step's content is now above them, and they have to tab backwards to reach it, or they might not even know the content changed.

What I'd do in production: after the step changes, move focus to the first input in the new step, or to the step's title. You can do this with a ref and an effect that runs when currentStep changes. Be a bit careful with timing, because the new content is animating in. Focusing an element that's mid-slide is fine functionally, but some browsers will scroll to it, which can look weird. Using focus({ preventScroll: true }) helps.

Also, consider announcing the step change for screen readers. An aria-live="polite" region with the step title is a simple way.

The Enter key

I talked about this with tags, but it applies generally. In a multi-step form, pressing Enter in a text input will try to submit the form. Which in this component isn't wired to a native form submit by default (the buttons are type="button" and Finish calls handleSubmit directly), so it's less of a risk. But if you wrap it in a <form> element yourself, which you might want for things like password managers, remember that Enter will submit. You might want Enter to mean "Continue" on intermediate steps instead. That's a nice touch, honestly. It lets people fly through the form without touching the mouse.

Browser back button

This one's sneaky. The steps are local component state, not URL state. So if someone is on step 3 and presses the browser back button, they don't go to step 2. They leave the page entirely. And lose everything.

For a short form that's arguably fine. For a long registration, that's a real way to lose people. Options: sync the step to a query param (?step=2) so the browser back button moves between steps, or warn before unload if the form is dirty. Neither is in the demo because both depend heavily on your routing setup. But think about it.

Data on unmounted steps

When you move from step 1 to step 2, step 1's inputs unmount. Will their values survive? With React Hook Form's default settings, yes, because shouldUnregister defaults to false, so values stay in the form state even after the field unmounts. That's why going Back in the demo shows what you typed earlier.

But if you ever flip that setting, or move some field into local useState instead of the form, you'll lose data when switching steps. I've done it. I put a field in local state "just to test something quickly," forgot about it, and then couldn't understand why it kept resetting. If going back loses data, the whole "progress" feeling collapses. People will not fill something out twice.

The tags input is a good example to look at here. It doesn't use register because it's not a simple value. It reads and writes the array with getValues and setValue. That keeps it in form state even though it's a custom control.

The height animation and dynamic content

The height animation works great when step content is static. But what if content changes height within a step? Like when a validation error appears under a field, or when someone adds five tags and the badge row wraps to two lines?

The good news is useMeasure keeps watching, so the card grows smoothly when errors appear or tags wrap. That's actually a nice side effect. Error messages sliding the card open is gentler than error messages shoving everything down.

The thing to watch for is popovers. The calendar is in a popover that renders outside the card, so it doesn't affect the height. If you add your own dropdown or expanding thing inline inside a step, it will make the card animate, which may or may not be what you want.

Mobile keyboards

On a phone, when the on screen keyboard opens, the viewport shrinks. If your multi-step form is vertically centered, the Continue button might end up under the keyboard. The card being a fixed frame with the footer at the bottom helps a bit, but test it on a real phone. Not just a desktop browser resized narrow. A real phone, with a real keyboard, with your real thumb.

Reduced motion

With MotionConfig, you can add reducedMotion="user":

<MotionConfig
  reducedMotion="user"
  transition={{ duration: 0.5, type: "spring", bounce: 0 }}
>

And Motion will skip the transform based slide for people who've asked for reduced motion, while still letting opacity changes happen. The steps will still change, the card will still adjust. They just won't fly in from the side. The step dots and titles still tell you where you are, so the form stays clear. That's a good sign. It means the motion was helping, but wasn't the only thing communicating progress.

What makes a form feel "human"

I've been throwing this word around so let me try to pin it down. Here's what I think makes a form feel human instead of bureaucratic, from building this and from going through way too many onboarding flows.

It talks like a person. "Let's get you in" instead of "Account Registration." "Give your project a name" instead of "Field required." Every bit of copy in a form is part of the interaction.

It doesn't ask for things it doesn't need yet. If you don't need their phone number to create an account, don't ask during sign up. Every field is a small cost you're asking someone to pay.

It shows you where you are. Step dots, a progress label, a title per step. You should never wonder how much is left.

It never loses your work. Going back keeps your data. Errors don't wipe fields. Accidentally leaving the page warns you.

It responds to you. Selections light up. Tags appear when you add them. The card grows when there's more to show. Errors appear right where you're looking.

It moves in a direction that makes sense. Forward is forward. Back is back. The space is consistent.

It ends warmly. The last step is the last impression. Make it about them.

None of these are about animation, really. Most of them are about copy and structure and care. Animation is what makes the transitions between those caring moments feel continuous instead of choppy. That's the role motion plays here. It connects the dots.

A shipping night

Let me tell you about the night the Multi-Step Form almost broke me.

I had the basic structure working pretty fast. Three steps, Continue and Back, React Hook Form wired up. Took maybe an hour and a half. I was like, this is going to be an easy one.

Then I added the slide animation. And the card height went crazy. Every transition, the card would shoot up to about double height and then snap back down. I spent an hour thinking it was the measurement library. Then another half hour thinking it was the spring. It was neither. It was that both steps were in the layout flow at the same time during the transition, so the measured height was the sum of both. mode="popLayout". One prop. I was so relieved and so annoyed at the same time.

Then the direction thing. I had a single slide direction and Back felt wrong, so I added the custom direction prop. Except I only added it to the motion.div, not to AnimatePresence. So going forward was fine, going back was fine, but going forward and then back quickly would make the exiting step leave the wrong way. That took me a while to even reproduce reliably, because you had to click pretty fast. Once I added custom to AnimatePresence too, it was solid.

Then I found the tags Enter bug. I was testing tags, hit Enter, and the form submitted with a toast full of empty values. I sat there staring at the toast for a second like, why is my form done. preventDefault.

Then I spent way too long on the emojis. I tried a version where the selected emoji scaled up and bounced. It was cute for about four clicks and then really annoying. I tried a version where all of them were in color. Too loud. Grayscale with color on hover and selection is what stuck. It's quiet until you make a choice.

By around 3am the form felt the way I wanted. You could fly through it and it felt like turning pages. Going back felt like going back. The card breathed with the content.

And looking at the final code, the motion part is maybe twenty or thirty lines. The variants, the AnimatePresence, the measured height, the MotionConfig. Everything else is just a good form. Which I think is the right ratio. The animation should be a small layer that makes a solid thing feel better, not the foundation.

An idea I keep coming back to: the review step

One thing the demo doesn't have, and that I think a lot of real flows should, is a review step. Right before Finish, a quick summary of everything you entered. Project name, date, team size, priority, tags, mood. All on one screen.

Why bother? Because by step 3, step 1 is out of sight. You typed the project name a minute ago and you probably don't remember if you typo'd it. A review step gives people one calm moment to check before committing. It's the form version of reading your email once before hitting send.

The nice part is how little it takes with this component. Add a fourth entry to stepTitles ("Look good?" or something like that), add a case to the switch that reads from watchedValues and renders the values as plain text, and you're done. The slide, the height animation and the dots all just work, because they don't care what's inside a step.

And here's where other useLayouts pieces fit in nicely. Instead of making people click Back three times to fix a typo, you could make each line in the review step editable in place. That's basically what Inline Edit is for: a value that looks like text until you click the pencil, then becomes an input, then goes back to text with a check. Wire its value to form.setValue and the fix happens right there, no step hopping.

npx shadcn@latest add @uselayouts/inline-edit

I haven't shipped a combined "review step with inline edits" demo, so treat this as a recipe, not a component. But it's a good example of what copy, customize, ship actually means in practice. The components are pieces. You put them together into the flow your product needs. Nobody's registration flow looks exactly like my demo, and it shouldn't.

One more small thing if you do add a review step: make the Finish button live there, not on the step before. The moment someone sees everything they entered is the moment they're most ready to commit. Put the commit button right where that confidence is.

Where Vercel's program fits in

useLayouts is part of the Vercel Open Source Program Winter 2026 cohort, and Vercel wrote about the whole cohort here: https://vercel.com/blog/vercel-open-source-program-winter-2026-cohort

For something like the Multi-Step Form, the live demo on the site is the whole pitch. You can't really judge whether a form "feels like progress" from reading about it, even a post this long. You have to click Continue and Back and watch the card breathe. So keeping every demo live and fast matters a lot to me, and the credits and support from the program take a real worry off my plate while I focus on the components.

Also, just being picked for it was a nice reminder that the boring sounding stuff (like making forms feel good) is worth caring about. Forms aren't flashy. They're what people actually use.

Quick clarification since it comes up a lot: useLayouts (uselayouts.com) isn't the same project as UI Layouts (ui-layouts.com). Different people, different libraries, and yes we're both in Vercel's open source program, which makes it extra confusing. This post is about useLayouts.

FAQ

Can I use the Multi-Step Form without React Hook Form?

You could, since you own the code. But I'd recommend keeping it. A lot of the tricky stuff, like keeping values across unmounted steps and per field validation, comes basically for free with React Hook Form plus Zod. Replacing it means rebuilding that.

Does it work with server actions in Next.js?

Sure. Replace the body of onSubmit with a call to your server action. The form doesn't care where the data goes. Just make sure you handle loading and error states on the Finish button, so the last click gives honest feedback, not a fake success.

Can I add more steps?

Yes. Add entries to stepTitles, add cases to the content switch, and replace the hardcoded 2s in nextStep with stepTitles.length - 1. The animation and the dots adapt automatically.

Can steps be conditional? Like skip step 2 if they pick "solo"?

Yep, but you'll need to change how nextStep and prevStep compute the next index, instead of just adding or subtracting one. Keep the direction logic the same though. Skipping forward should still slide forward.

Why are all the fields optional in the demo?

So you can click through and see the transitions without filling anything in. For your app, make the schema real and add per step validation with trigger, like I showed above.

Why the emoji mood step? Isn't that a bit silly for a real app?

Maybe! For some products it's perfect, for others it's not. The point is the pattern: end with something light and human. Swap the emojis for whatever fits.

Is it free to use commercially?

Yes, MIT licensed. Use it in client projects, in your startup, wherever. Sponsorships from companies who get value out of it are welcome and help keep things going, but there's no catch.

The end (you made it through the whole form)

If there's one thing I hope you take from this, it's that progress is a feeling you can design. Direction, continuity, a stable frame, honest feedback, words that sound like a person. A multi-step form that gets these right can ask for a lot of information and still feel easy.

If you want to see it in action, go to the site and click through the Multi-Step Form demo. Go forward, go back, add some tags, pick a mood, watch the toast. Then pull it into your project and make it yours:

npx shadcn@latest add @uselayouts/multi-step-form

And if it helps you ship a sign up flow that people actually finish, a star on GitHub would mean a lot. We're at hundreds of stars and climbing, and every one helps other devs find this.

Site: https://uselayouts.com/
Docs: https://uselayouts.com/docs/introduction
GitHub: https://github.com/iurvish/uselayouts

Thanks for reading. Go make a form someone actually enjoys.

Urvish

Copy, Customize, Ship: Why useLayouts Isn't a Locked npm UI Kit

Urvish — Wed, 07 Oct 2026 18:09:26 +0000

There's a specific kind of frustration I think every frontend dev has felt at least once.

You install a UI library. It's great for the first week. Everything looks consistent, the docs are nice, you're moving fast. Then your designer, or your own brain, asks for one small change. The dropdown should open a little slower. The tab indicator should be rounder. The button shouldn't scale on hover, it should do this other thing.

And you go looking for the prop. There's no prop. You look for a theme override. There's a theme override, but it only covers colors. You look at the source on GitHub and find the animation is hardcoded three components deep. You think about forking. You think about !important. You think about wrapping it in a div and fighting it with CSS.

An hour later you've written forty lines of override code to change one number.

That experience is a big part of why useLayouts works the way it does. When you add a component, you don't install a package. You get a file. It's yours. Change the number.

I'm Urvish, I make useLayouts. It's a free, MIT licensed collection of animated React components built with Tailwind and Motion, distributed as a shadcn registry. It got picked for the Vercel Open Source Program Winter 2026 cohort, which I'm still kind of processing. This post is about one specific idea: copy, customize, ship. Why I chose it over the traditional npm package model, what it's actually like to live with, where it's worse, and how I'd recommend using it so you don't end up with a mess.

I'm going to try to be fair here. Locked packages aren't evil. There are real reasons they exist. But for the kind of components I make, I think owning the source is the better deal, and I want to show you why with real examples instead of vibes.

The two models, plainly

Let's define terms so we're talking about the same thing.

The package model. You run npm install some-ui-kit. The library lives in node_modules. You import components from it. You configure them through props, theme objects, or CSS variables the library chose to expose. When the library updates, you bump the version and get the new behavior. You don't really own the code. You rent it.

The copy model. You run a command, or literally copy paste, and the component's source code ends up in your project. Usually in something like components/ui/. It's a normal file. It imports its dependencies like any other file. You can edit it directly. When the original author updates it, nothing changes in your project unless you go get the new version yourself.

Shadcn/ui made the copy model mainstream. Before that, a lot of people were doing it informally, copying snippets from blog posts and CodePens. Shadcn turned it into a real workflow with a CLI and a registry format. And now other people, like me, can publish registries that plug into the same CLI.

For useLayouts, it looks like this. You add the registry once in components.json:

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

Then you add components by name:

npx shadcn@latest add @uselayouts/discrete-tabs

The file lands in your project. Motion and whatever else it needs get installed for you as regular dependencies. That's it. There's no uselayouts package in your package.json. There's no runtime that belongs to me.

Why motion components specifically want to be owned

I think the copy model is good in general, but I think it's especially good for animated components. Here's my argument.

A regular button is mostly structure and accessibility. It needs to be a real button element, it needs focus styles, it needs disabled states, it needs to handle keyboard input. Those things have right answers. There's a correct way to do them, and a library that does them correctly is genuinely valuable, because you probably don't want to reinvent that.

Motion is different. Motion is taste.

What's the right spring stiffness for a tab indicator? There isn't one. It depends on your brand. A meditation app and a trading dashboard should not have the same tab animation. It depends on your users' devices. It depends on how much else is moving on the page. It depends on whether your designer likes things snappy or soft.

If I ship a locked component with a hardcoded spring, I'm forcing my taste on your product. If I expose the spring as a prop, okay, now you can change stiffness. But what about damping? Mass? What about the blur on the label? What about the fact that you want the icon to move but not the text? What about the fact that you want the label to just appear, no blur at all?

Every one of those becomes a prop. The API balloons. And it's still never enough, because the one thing you want to change is always the one thing I didn't think to expose.

With the copy model, I don't have to predict what you'll want. You open the file and change it. The spring is right there. The blur is right there. Delete it. Done.

That's why I say, half seriously, that the components are a starting point you can ruin on purpose. I'm not giving you a finished product. I'm giving you a really good first draft that you finish.

A real example: Discrete Tabs out of the box

Let's look at an actual component so this isn't abstract. Discrete Tabs is probably the one people add most, and it's a good one to show because it's short.

When you add it, the file has a few icon components at the top, then this:

// Change Here
const TABS = [
  { id: "Inbox", title: "Inbox", icon: Inbox },
  { id: "Planner", title: "Planner", icon: Calendar },
  { id: "Alerts", title: "Alerts", icon: Alert },
];

That // Change Here comment is very intentional. It's the first thing you'll want to edit, so I put a sign on it.

Then the main component, which is just state and a map:

export default function DiscreteTabs() {
  const [activeButton, setActiveButton] = useState(TABS[0].id);
  return (
    <div className="flex gap-4 items-center">
      {TABS.map((tab) => (
        <Button
          key={tab.id}
          title={tab.title}
          ButtonIcon={tab.icon}
          isActive={activeButton === tab.id}
          setActiveButton={setActiveButton}
        />
      ))}
    </div>
  );
}

And then a Button function that does the actual motion work. Each tab is a pill. Inactive tabs show just the icon. The active tab opens up to show the icon plus the label. When you switch, the pills resize and slide using Motion's layout animations, and the label fades in with a quick blur.

The spring looks like this:

transition={{
  layout: {
    type: "spring",
    damping: 20,
    stiffness: 230,
    mass: 1.2,
  },
}}

Notice what's not there. There's no <DiscreteTabs springConfig={...} labelAnimation={...} labelBlur={false} /> API. There's no config object. It's just the code that does the thing, written as plainly as I could.

Some people look at that and think it's less "professional" than a configurable component. I think it's more honest. You can read the whole thing in a couple of minutes, and then you know exactly what you're shipping.

Customizing it: five real edits

Okay, so you've added Discrete Tabs. Here's what customizing actually looks like. These are edits I've made myself in real projects, or that people have asked me how to do. None of them need anything from me. That's the point.

Edit 1: Make it calmer

Say your product is calmer than my demo. Maybe it's a writing app, or something people use for hours and you don't want the UI feeling bouncy.

Open the file, find the spring, and change it. Lower stiffness makes it slower to get going. Higher damping makes it settle without overshoot.

layout: {
  type: "spring",
  damping: 30,
  stiffness: 180,
  mass: 1,
}

Try it, click around, adjust. There's no right answer, there's just "does this feel like my product." I'd recommend changing one number at a time, because if you change all three at once you won't know which one made it feel better or worse.

With a locked package, this edit either needs a prop that may not exist, or a fork. Here it's a ten second change.

Edit 2: Make it controlled and hook it to your router

The default version keeps its own state with useState. That's great for a demo, but in a real app your tabs probably need to match the URL, or a parent component needs to know which tab is active.

So you change the main component to take props:

type DiscreteTabsProps = {
  value: string;
  onValueChange: (id: string) => void;
};

export default function DiscreteTabs({ value, onValueChange }: DiscreteTabsProps) {
  return (
    <div className="flex gap-4 items-center">
      {TABS.map((tab) => (
        <Button
          key={tab.id}
          title={tab.title}
          ButtonIcon={tab.icon}
          isActive={value === tab.id}
          setActiveButton={() => onValueChange(tab.id)}
        />
      ))}
    </div>
  );
}

And now the parent owns the state. You could wire that to a search param, a route segment, or whatever store you use. You'd also want to tidy up the Button prop types so setActiveButton is just a function that takes no arguments, but that's a two line change.

This is a really common edit and it's a good example of why I don't try to make the defaults do everything. If I'd shipped a controlled and uncontrolled API with every possible integration, the file would be three times longer and harder to read. Instead, it's short, and you add the shape your app needs.

Edit 3: Clean out what you don't use

If you read the Button function closely, you'll find a showShine state and a useEffect that flips it on for 800ms whenever a tab becomes active after you've interacted. Then you'll notice nothing in the render actually reads showShine. It's a hook for a shine effect that isn't drawn in the current file. Honestly, it's leftover scaffolding from me experimenting.

In a package, that kind of thing would just sit in node_modules forever and you'd never know. Here, you can see it. So you get to choose. Either use it, like conditionally rendering a little highlight sweep while showShine is true, or delete the state and the effect. It's a useState and a useEffect with a timeout. Remove them and you're done.

Same goes for the label blur. If your product wants the label to just appear, remove the filter values from initial and animate. You don't need to set labelBlur={false}. You don't need to file a feature request asking me to make it optional. You just delete the lines.

I kind of like that this example is a little embarrassing for me. It's the most honest demo of the copy model I can give you. You see everything, including my leftovers.

I know that sounds obvious, but I think a lot of developers are trained by package culture to not touch the component. It feels like you're breaking something. You're not. It's your file now.

Edit 4: Use your icons

The default file defines a few small SVG icon components at the top, so it doesn't force an icon library on you. But a lot of projects already use Lucide, and Lucide fits shadcn projects really naturally.

The Button expects an icon component that accepts a size prop. Lucide icons accept size. So you can basically swap:

import { Inbox, Calendar, Bell } from "lucide-react";

const TABS = [
  { id: "Inbox", title: "Inbox", icon: Inbox },
  { id: "Planner", title: "Planner", icon: Calendar },
  { id: "Alerts", title: "Alerts", icon: Bell },
];

Then delete the inline SVG components you're not using anymore. The file gets shorter and it matches the rest of your app.

Edit 5: Match your design system

The pills use theme classes like bg-secondary, outline-border, and text-primary for the active state. If you're on a standard shadcn theme, those already pick up your colors, which is why I use them.

But maybe your design system has its own rules. Maybe your tabs aren't pills, they're more rectangular. Maybe you don't use monospace uppercase labels, because that's a pretty specific look I like and you might not.

The border radius is set inline as borderRadius: "25px". Change it. The label has font-mono uppercase. Remove those classes and it'll use your normal font. The shadow is shadow-md. Swap it for whatever your system uses, or drop it.

Fun detail on the radius: it's set as an inline style instead of a Tailwind class on purpose. Motion's layout animations can correct border radius during the animation when it's set that way, so the corners don't look stretched while the pill resizes. If you move the radius into a class and the corners start looking weird mid animation, that's why. This is exactly the kind of thing that's easy to understand when you can read the file, and really confusing when it's buried in a package.

After those five edits, the component might look nothing like my version. Good. That's what I wanted.

The night I fought a library

I want to tell a story about the package model going wrong for me, because I think it explains why I care about this so much.

A while back, before useLayouts was a real thing, I was building a dashboard for a project. I was using a popular component package for a lot of the UI. I'm not going to name it, because it's a good library and this isn't its fault. It just wasn't built for what I wanted.

The dashboard had a sidebar with sections, and I wanted the active section indicator to slide between items instead of jumping. Pretty normal request.

The library's nav component didn't support that. It had an active state, and you could style it with a class, but the indicator was just a background on the active item. No shared element, no transition between items.

So I tried to add it myself. I wrapped the nav items, measured their positions with refs, and absolutely positioned a separate indicator element behind them. Then I animated that element's position when the active item changed.

It kind of worked. Then I resized the window and the measurements went stale. So I added a resize observer. Then the library's own focus ring started rendering on top of my indicator in a weird way. So I overrode the focus styles. Then I realized the library re-rendered the items in a way that occasionally reset my refs. So I added some janky effect logic to re-measure.

By around 2am I had something like a hundred lines of code whose only job was to fight the library into doing a slide animation. And it was fragile. Every time the library updated, I was scared it'd break.

If I'd owned the nav component's source, the whole thing would have been: add layoutId to the active indicator, done. Motion handles the shared layout animation. Maybe ten lines.

That's the core of my argument. The package model is great when the package does what you want. When it doesn't, the cost of bending it can be way bigger than the cost of just owning the code from the start.

What you give up

I promised to be fair, so here's the real list of downsides. If someone tells you the copy model has no tradeoffs, they're selling something.

Updates don't come to you

If I fix a bug in a component, or improve it, your copy doesn't change. You have to go get it.

For some people that's a dealbreaker. They want npm update and done. I get it.

My take is that for this specific kind of component, it's actually a feature. Motion is something you tuned. If I could push an update that silently changed your spring, or your timing, or removed an effect, I could change how your product feels without you knowing. That seems worse than missing a fix.

But it does mean you have to care a little. More on how to handle that below.

You can break it

When you own the file, nothing stops you from making it worse. You can delete the "use client" directive and get confused errors in the App Router. You can remove something that looked unnecessary but was doing important work, like that isLoaded flag that stops the component animating on first render. You can introduce bugs.

That's the cost of freedom. I try to make the files readable so you can understand what each piece is for before you remove it. But I can't stop you, and I wouldn't want to.

Drift across projects

If you use useLayouts in five projects and customize it differently in each, you now have five versions. Some will have fixes the others don't. This is exactly the copy paste problem I had before useLayouts existed, when I was dragging a folder between repos.

On a team, this can get messy if nobody owns it. Two developers each add the same component to different parts of the app and tweak it differently, and now your app has two slightly different tab animations.

More code in your repo

Your project gets bigger. Each component is a real file you have to maintain, lint, type check, and review. With a package, that code is in node_modules and it's somebody else's problem.

For most useLayouts components this is pretty small, a single file, but it's still real. If you add twenty components you have twenty files you're responsible for.

You need to read the code

This is a soft one but it matters. The copy model works best when you actually open the file and understand it. If you're the kind of developer who wants to never look inside a component, a package might suit you better.

How to live with it without making a mess

So, given those tradeoffs, here's how I'd actually recommend working with copy model components. This is what I do in my own projects.

Commit the pristine version first

When you add a component, commit it immediately, before you change anything.

npx shadcn@latest add @uselayouts/discrete-tabs
git add -A && git commit -m "add discrete-tabs from uselayouts"

Then make your edits and commit those separately. Now your history has a clean record of what came from the registry and what you changed. When you want to pull an update later, this makes it way easier to see what's mine and what's yours.

Pulling an update

When there's a newer version of a component you want, the CLI can add it again. It'll ask before overwriting an existing file. My workflow is:

Make sure my working tree is clean.
Re-add the component and let it overwrite.
Look at the git diff. Now I can see exactly what changed between my version and the new one.
Keep the upstream changes I want, restore my customizations, commit.

It's more manual than a version bump, yeah. But it's also way more transparent. You see every single line that changes. Nothing sneaks in.

Honestly for a lot of components you'll never need to do this. If it works and it feels right in your product, there's no reason to update it.

Keep one copy per app

On a team, agree on one location and one version of each component. If the dashboard and the settings page both need Discrete Tabs, they should import the same file, not each have their own. If one needs different behavior, add a prop or a variant to the shared file. That's normal component hygiene, it just matters more when the component didn't come from a package.

Rename it if you changed it a lot

If you've customized a component so much it's basically a different thing, rename it. discrete-tabs.tsx becomes section-switcher.tsx or whatever it actually is in your app. That way nobody on your team thinks it's the stock version, and nobody accidentally overwrites it by re-adding from the registry.

Leave a note about where it came from

A one line comment at the top of the file saying it started as a useLayouts component is nice. It helps future you remember where to look for updates, and it helps teammates understand why it's written the way it is. MIT doesn't make you do this in a comment specifically, but keeping the attribution around is good practice and I appreciate it.

When a locked package is actually the better choice

I don't want to pretend the copy model wins every time. There are cases where I'd reach for a regular package myself.

Hard, correctness heavy primitives. Things like a fully accessible combobox, a date picker with keyboard navigation and screen reader support, focus trapping in dialogs. These have a lot of edge cases and a "right" answer. You want those to be maintained centrally by people who've thought about every weird assistive tech quirk. That's what Radix is great at. Even shadcn components that you copy into your project usually wrap Radix primitives that stay as a package dependency. The copy layer is the styling and composition. The hard behavior stays in a maintained package.

Huge surface area you'll never customize. If you need fifty basic components and you're happy with how they look, a package is less code in your repo.

Teams with zero appetite for owning UI code. If nobody on the team wants to read component source, ever, the copy model will slowly rot. A package with a stable API might be a better fit.

Things with security or protocol implications. Auth flows, payment widgets, anything where you really want the vendor's fixes to arrive automatically.

So the way I think about it: the deep, correctness heavy stuff can live in packages. The surface layer, the part that defines how your product feels, should live in your code. useLayouts is entirely that surface layer. It's tabs, buttons, cards, galleries, small interactions. It's the feel. That's exactly the part you should own.

You can actually see what you're shipping

This one's underrated. When a component is a file in your project, you can read every line of it before it ships to your users.

With a package, you usually trust it. You check that it's popular, maybe glance at the GitHub, and import it. What's actually inside? Its own dependencies, its own effects, maybe some global CSS it injects, maybe a polyfill. You probably never look.

With a useLayouts component, the whole thing is right there. You can see which dependencies it pulls in, because the registry item declares them. For Discrete Tabs that's motion, clsx, and tailwind-merge. You can see every effect, every timeout, every style. Nothing hidden.

I also put the source on every component's docs page, so you can read it before you even run the CLI. I really don't want anyone to be surprised by what lands in their project. If you read the file and something seems off, you can not add it. That's a level of control you just don't get with a black box.

What "ship" actually means here

The name is copy, customize, ship. I've talked a lot about copy and customize. Let me talk about the ship part, because that's the part that matters.

The whole reason this model exists is so you can ship faster without shipping something dead. Not so you can spend a week tuning springs. If copying a component turns into an endless customization rabbit hole, that's a failure too.

So here's a real shipping night, or close to one, to show how it plays out.

I was helping out on a small project that needed an admin table where you could delete rows. It was late, the deadline was the next morning, and the delete action was just a red button with a browser confirm dialog. It worked. It felt like 2009.

Here's what I did.

npx shadcn@latest add @uselayouts/delete-button

Commit. Then I opened the file and did three things.

First, I changed the copy. My demo text didn't match their product's voice, so I rewrote the labels to match what they used everywhere else.

Second, I hooked up the actual delete. The demo version counts down and gives you a cancel option, but it doesn't actually delete anything, because there's nothing to delete on a docs page. I made the real mutation fire when the countdown finishes, and made cancel actually cancel.

Third, I shortened the countdown. The timing values all sit in one config object at the top of the file, which made this a one number change. In a table with lots of rows, you see the delete button a lot, and anything long starts to feel slow when you're deleting five things in a row.

That's it. Maybe forty minutes including testing. The browser confirm was gone, deleting felt deliberate, and the table still felt fast. Shipped it, went to bed.

The key thing: I didn't redesign the component. I didn't try to make it perfect. I copied it, made the three edits that mattered for that product, and shipped. The customization was in service of shipping, not a hobby.

I think that's the healthy way to use this stuff. Make the edits that make it yours. Stop there. You can always come back to it.

Bundle size and dependencies

People sometimes ask whether adding a bunch of animated components will bloat their app. Fair question.

The main dependency is Motion. If your project already uses it, adding useLayouts components barely changes anything, because they all share it. If it doesn't, you're adding Motion once, and every component after that reuses it.

Beyond that, the components themselves are small files. And because they're your code, your bundler treats them like any other component. Tree shaking works normally. If you add a component and never import it, it doesn't end up in your bundle. If you only use it on one page, code splitting can keep it on that page.

That's actually another quiet advantage over some packages. With a big monolithic UI package, you're sometimes at the mercy of how well it's set up for tree shaking. With source in your project, the bundler sees exactly what you use.

And if you're worried about a specific component, you can open it and see what it imports. No guessing.

How this plays with shadcn and Radix

useLayouts isn't trying to replace shadcn/ui. It sits next to it.

A typical setup I'd recommend: use shadcn for your base components. Buttons, inputs, dialogs, dropdowns, the stuff every app needs. Those give you solid structure and accessibility, often through Radix under the hood. Then use useLayouts for the moments you want to feel special. The main nav tabs. The delete action. The save button. The pricing card on your landing page. The gallery on your portfolio.

Because useLayouts components follow the same conventions, they fit right in. Same components.json. Same CLI. Same cn helper from @/lib/utils. Same theme tokens. They don't feel like a foreign library dropped into your app. They feel like more of your components, because they are.

It's also why I kept the "add the registry once" setup so short. You've probably already got a components.json from shadcn. Adding useLayouts is one more line in it.

On teams: who owns the motion

Something I've seen when teams use copy model components: the question of who owns the motion becomes really clear, really fast.

With a package, the answer is basically "the package author." Your team just accepts whatever animations ship with it. Nobody on the team really decides how your tabs feel. It just is what it is.

When the code is in your repo, someone has to own it. And I think that's healthy. Somebody on your team becomes the person who cares about how the UI moves. They tune the springs, they make sure the timing is consistent across components, they review PRs that touch animations.

A practical tip if you're on a team: pull your shared motion values into one place once you've customized a few components. Like a small file with your app's springs:

export const springs = {
  snappy: { type: "spring", damping: 22, stiffness: 260, mass: 1 },
  calm: { type: "spring", damping: 30, stiffness: 180, mass: 1 },
} as const;

Then update the components you've added to use those instead of their inline values. Now your whole app moves with the same personality, and changing it is one edit.

I don't ship components that way by default, because I want each file to be self contained and readable on its own. If Discrete Tabs imported springs from some shared file you don't have, it'd break when you added it. But once it's in your project, pulling values out like that is totally the right move.

That's kind of the copy model in a nutshell. I give you something self contained. You integrate it into your system however makes sense for you.

Why not offer both?

Someone asked me once why I don't just publish an npm package too. Give people the choice. Registry for people who want to own it, package for people who want updates.

I thought about it. I decided not to, at least for now, for a couple of reasons.

The first is focus. I'm one person. Maintaining a package means thinking about public APIs, semver, breaking changes, backwards compatibility, peer dependency ranges, and all the props that I'd need to expose to make it configurable. That's a whole different job. The registry lets me keep each component as a plain, readable file, which is the thing I actually want to be good at.

The second is that a package would quietly change how I design the components. The minute something's a package, I'd start adding props for everything, because people can't edit the source. The files would get longer and more abstract. I'd be designing for configurability instead of for how it feels. I think the components would get worse.

The third is honesty about what these are. They're not infrastructure. They're starting points with good taste baked in. A package says "trust me, don't look inside." A registry says "here's my best version, now make it yours." That second one is the actual relationship I want with people who use this.

Mistakes people make after copying

Since the code is in your hands, here are the things I see go wrong most often. None of these are your fault exactly, they're just the sharp edges of owning the code.

Removing "use client". The components use state, effects, and Motion, so they're client components. The file starts with "use client". If you delete it, or move the logic into a server component, you'll get errors in the Next.js App Router. Keep it. If you want a server rendered wrapper, put that in a separate file that imports the client component.

Path aliases that don't match. The components import cn from @/lib/utils, which is the standard shadcn setup. If your project uses a different alias, the CLI usually handles it based on your components.json, but if you copy paste manually from the docs page instead of using the CLI, you might need to fix the import.

Overwriting your own changes. If you customized a component and then re-add it from the registry without committing first, you can lose your edits. The CLI asks before overwriting, but it's easy to hit yes on autopilot. Commit first. Always.

Deleting the "boring" lines. Some lines look unnecessary but aren't. In Discrete Tabs, the isLoaded state is what stops the label from doing its entrance animation on first render. The willChange: "transform" styles help the browser prepare for the motion. The inline border radius helps Motion keep corners looking right while the pill resizes. If you delete these, it still works, it just gets a little worse in ways that are hard to spot. Read before you cut.

Customizing in five places at once. People open the file and change the spring, the colors, the padding, the font, and the icons all in one go. Then something feels off and they don't know which change caused it. Change one thing, look at it, then change the next.

Forgetting people who prefer reduced motion. Some users have reduced motion turned on at the OS level. Motion has tools for respecting that, like the useReducedMotion hook and MotionConfig with reducedMotion="user". Since the component is yours, you can decide how to handle it in your app. A common approach is wrapping your app in MotionConfig so transforms get toned down for people who asked for that. It's a few lines and it's worth doing.

The package mindset vs the owner mindset

There's a mental shift that happens when people start using copy model components, and I think it's the most important part of this whole thing.

In the package mindset, a component is something you consume. You read the docs, you find the props, you use it as intended. If it doesn't do what you want, you either live with it or you file an issue and wait. The component belongs to someone else and you're a guest.

In the owner mindset, a component is something you start from. You read the code, you understand what each part does, and you make it fit. If it doesn't do what you want, you change it. The component belongs to you and the original author is more like someone who gave you a head start.

A lot of developers, especially newer ones, are really trained into the package mindset. I was too. It feels wrong to edit something that came from somewhere else, like you're voiding a warranty. There's no warranty. MIT literally says so. Edit it.

Once that clicks, the copy model gets a lot more fun. You stop thinking "what can this component do" and start thinking "what do I want my product to do." The component is just the fastest way to get there.

MIT, sponsors, and staying honest

useLayouts is MIT licensed and free. You can use it in personal projects, client work, commercial products, whatever. Keep the license notice around, and that's basically it.

I chose MIT because it's the only license that actually matches the copy model. If I'm telling you the file is yours, the license needs to back that up. Anything more restrictive would make "it's yours" a lie.

The project runs on my time, some sponsors, and the support from being in the Vercel Open Source Program Winter 2026 cohort. That program gave the project credits and support from Vercel, which matters more than you might think for a registry. Every time someone runs the CLI, it fetches a JSON file from uselayouts.com. Every docs page has live previews. All of that is hosted, and having Vercel back it means I don't stress about traffic spikes when someone with a big audience shares a component.

If your company gets real value out of useLayouts, sponsoring is how you keep it free for the solo devs and students who can't pay. If you're building something small, just use it. That's how I want it to work. No pro tier. No locked components. No upsell inside the file.

And just to clear it up since people mix it up all the time: useLayouts is not UI Layouts. Different creators, different projects. UI Layouts is at ui-layouts.com. Both happen to be in the Vercel OSS program, which hasn't helped with the confusion.

What people usually change in other components

Discrete Tabs is the easy example, but the same idea applies everywhere. Here's what I'd expect you to touch first in a few other components, based on what I end up changing myself when I drop them into real projects.

Status Button (it's save-button in the registry). The states are the obvious thing. My demo walks through a simple idle, working, done flow, but your app might need an error state that actually means something, or a state that says "queued" instead of "working." The other big edit is wiring it to your real async call instead of a simulated delay. And timing. How long the success state sticks around before resetting is a product decision, not a library decision. A settings page can show "Saved" for a while. A chat input probably shouldn't.

Delete Button. Copy, first. The words on a destructive action matter a lot and they should sound like your product. Then the countdown. The stock version flips into a cancel state with a countdown, so you get a few seconds to back out before anything happens. How long that window should be is a product call. Deleting an account deserves a long one. Archiving a row in a list probably wants a short one. The colors and timing live in a config object at the top of the file, so this is a quick edit. Since it's your file, you can also make it conditional, like skipping the countdown for things you can undo anyway.

Morphing Input. Usually the content that it morphs between. It's built to show how an input can change shape instead of being replaced, and what it changes into depends entirely on your feature. Search, inline add, a quick compose box. You'll also probably want to connect it to your form library if you use one.

Pricing Card. Almost everything content wise. Plan names, prices, features, the highlighted plan. The layout is a starting point, but pricing pages are very brand specific, so I'd expect you to change spacing and typography more here than anywhere else. The interaction details are the part to keep.

Multi-Step Form. The steps, obviously, and validation. My version shows the flow and the transitions between steps. Your version needs real fields, real validation rules, and probably a real submit. The motion between steps is the part that makes it feel like progress instead of paperwork, so I'd leave that mostly alone and focus your edits on the content.

Bento Card. Grid sizing. Bento layouts live or die by how the cards are sized relative to each other, and that depends on your content. Change the spans until the most important thing is the biggest thing.

Smooth Dropdown and Bottom Menu. Items, icons, and what happens on select. These are navigation pieces, so they need to plug into your routing. Same idea as making Discrete Tabs controlled.

Notice a pattern? In almost every case, the first edits are about content and wiring, not motion. The motion is the part that took me hours to get right, and it's the part you probably shouldn't need to touch much. The content is the part that's always specific to your product, and it's the part a package would make hardest to change. That's the whole case for the copy model in one observation.

A quick checklist

If you're about to add your first useLayouts component, here's the short version of this whole post:

Add the registry to components.json once.
Read the source on the component's docs page before you add it.
Run the add command.
Commit the pristine file.
Make the edits that matter for your product. Copy, icons, colors, maybe the spring.
Commit your edits separately.
Ship it.
Come back later if you want to tune more.

That's the loop. Copy, customize, ship.

Questions I get about this

Isn't copying code an anti pattern? DRY and all that?
DRY is about not repeating logic inside your own codebase. Copying a component into your project once, and then using it everywhere from that one file, is totally DRY. It's not different from writing the component yourself, you just didn't have to start from zero.

What if you find a security issue in a component?
These are UI components, mostly state and animation, so the surface area is small. But if something important needed fixing, I'd announce it on the repo and the site so people know to update their copies. The diff workflow above makes that easy to apply.

Can I copy paste from the docs page instead of using the CLI?
Yeah, the source is right there. The CLI is just more convenient because it handles dependencies and file placement for you. If you copy manually, make sure you install the dependencies listed for that component and fix any import paths.

Can I publish my modified version?
It's MIT, so yes, as long as you keep the license notice. I'd love it if you mentioned where it started, but the license only asks for the notice.

Will you ever break my app with an update?
No. I literally can't. Your copy only changes when you change it.

Does it work with pnpm, yarn, bun?
All of them:

pnpm dlx shadcn@latest add @uselayouts/discrete-tabs
yarn dlx shadcn@latest add @uselayouts/discrete-tabs
bunx --bun shadcn@latest add @uselayouts/discrete-tabs

Can I add a few at once?

npx shadcn@latest add @uselayouts/delete-button @uselayouts/save-button

Go own something

If you've been living in package land and fighting overrides, try this once. Pick one component where your current UI feels a little dead. A tab bar, a delete action, a save button. Add the useLayouts version, commit it, change three things, ship it.

I think you'll feel the difference not just in the UI, but in how you work. You stop asking a library for permission and you just build.

Browse the components at uselayouts.com, read the intro in the docs, and if it ends up being useful, a star on GitHub genuinely helps. The repo's at hundreds of stars and climbing, and every one of them helps someone else find it.

Site: https://uselayouts.com/
Docs: https://uselayouts.com/docs/introduction
GitHub: https://github.com/iurvish/uselayouts

Thanks for reading.

Urvish (@0xUrvish)