If you've ever used a native `<select>` and `<option>` in HTML, you've already
experienced the power of **compound components**—even if you didn't know the
name.

But what if you could bring that same flexibility and declarative power to your
own React components? That's what the Compound Components pattern is all about.

## What and Why: Compound Components in React

Compound components are a set of components that work together to form a
complete UI, implicitly sharing state and behavior. Think of them as a family:
each member has a role, but they all work together seamlessly.

The classic example is HTML's select:

```html
<select>
	<option value="1">Option 1</option>
	<option value="2">Option 2</option>
</select>
```

The `<select>` manages the state, and the `<option>`s are just configuration.
You don't have to wire them up manually—they just work.

You _could_ build a custom select like this:

```tsx
<CustomSelect
	options={[
		{ value: '1', display: 'Option 1' },
		{ value: '2', display: 'Option 2' },
	]}
/>
```

But what if you want to add custom attributes to an option, or change how it's
displayed when selected? You'd have to keep adding more props and configuration,
making your API more complex and less flexible.

Compound components let you keep your API simple and declarative:

```tsx
<CustomSelect>
	<CustomOption value="1">Option 1</CustomOption>
	<CustomOption value="2">Option 2</CustomOption>
</CustomSelect>
```

Now, you can pass _anything_ as children, and each option can be as flexible as
you need.

The parent component (like `<CustomSelect>`) manages the shared state and passes
it down to its children using React's context API. The children (like
`<CustomOption>`) consume that context and interact with the parent as needed.

This pattern lets you build components that are:

- **Flexible:** Users can compose your components however they want.
- **Declarative:** The structure of the UI matches the structure of the code.
- **Extensible:** Add new features without breaking existing APIs.

## Real-World Impact & When to Use

This isn't just a theoretical pattern. It's used in some of the most popular UI
libraries, like
[Radix UI Tabs](https://www.radix-ui.com/primitives/docs/components/tabs) and
[Radix UI Accordion](https://www.radix-ui.com/primitives/docs/components/accordion).
In fact, most of [Radix UI](https://www.radix-ui.com/primitives) is built on
this pattern.

Reach for compound components when:

- You want to give users maximum flexibility in composing your UI.
- You want to avoid prop explosion and keep your API clean.
- You want your components to "just work" together, like native HTML elements.

Want to master patterns like this—and many more?
[EpicReact.dev](https://epicreact.dev) is packed with hands-on workshops,
real-world examples, and deep dives into the patterns that make React apps
scalable and maintainable. Whether you're a beginner or a seasoned pro, you'll
find something to level up your React skills.


Build flexible, declarative UIs like native HTML with Compound Components—a powerful React pattern you’ll master at EpicReact.dev.

Compound Components: Truly Flexible React APIs

In this post, we’re going to dive deep on how you use modern React APIs for building forms. We will not be using third party libraries or frameworks. Understanding these lower level primitives will unlock them for you when using libraries and frameworks.

I recently heard someone say that web applications are just a skin on top of a database. And that’s actually pretty accurate. Since the beginning of the web, modern web applications have had two sides to them:

1. Users view data
2. Users mutate data

Loading data into a web application is a pretty straightforward proposition. It’s only when we start talking about needing to modify that data and keep things in sync that things get more complicated.

From day 1, HTML supported mechanisms for both of these use cases.

## Viewing Data

This allows the user to navigate to another page to view more data:

```html
<a href="/remix-utah/events/301213597">Remix Meetup June 🏖</a>
```

This *also* allows the user to navigate to another page to view more data, but enables them to control the data that comes back by including the user’s input in the generated URL:

```html
<form action="/remix-utah/events/search">
	<label for="event-search">Query</label>
	<input id="event-search" type="search" name="query" />
	<button type="submit">Search</button>
</form>
```

Let’s say the user types “August” in the input and hits enter. Thanks to the `action` the user would be sent to `/remix-utah/events/search?query=August`. So by default, `<form>` is just like `<a>` with the special ability of allowing the user to provide input.

## Mutating data

For both `<form>` and `<a>`, the navigation is performed via a `GET` request, which makes sense because you’re trying to `GET` data. But what if the user is trying to *modify* the data?

For example, let’s say you want to be able to sign up for an event with `/remix-utah/events/301213597/join`. If we made that endpoint a `GET` then we could do that like so:

```html
<a href="/remix-utah/events/301213597/join">Join Remix Meetup June 🏖</a>
```

This would certainly work (you could even use a `<form>` with a submit button if you wanted. However, this would also open your users up to a potential problem: **accidental or malicious modification of data**. Since `GET` requests are designed to be idempotent (they should be callable repeatedly without observable effects), using them for state-changing actions can lead to unintended consequences.

Additionally, if you made a login form using a `GET` request, then the user submits their password and the URL looks like this: `/login?username=kody&password=kodylovesyou`! The user’s submission is in plain text in plain sight!

This is part of the reason we have `POST` requests and while you can’t make `<a>` use `POST` instead of `GET`, you can do this with `<form>`.

`POST` requests are designed for submitting data to be processed to a specified resource. There’s no feature of HTML that triggers a `POST` request without user interaction, so they can safely be used to change the state of the server, which is perfect for our scenario of joining an event. Here’s how you can use a form to `POST` data:

```html
<form action="/remix-utah/events/301213597/join" method="POST">
	<button type="submit">Join Remix Meetup June 🏖</button>
</form>
```

By using `method="POST"`, we indicate that this form is meant to modify data on the server. The server will then process this request and update its state accordingly, ensuring that the user's intent to join the event is recorded.

### Handling Data Mutations with JavaScript

While traditional form submissions cause a full page reload, modern web applications often use JavaScript to handle these actions asynchronously, providing a smoother user experience.

Here's an example of how you might handle a form submission with JavaScript:

```html
<form id="join-event-form">
	<button type="submit">Join Remix Meetup June 🏖</button>
</form>

<script type="module">
	const form = document.getElementById('join-event-form')
	form.addEventListener('submit', async (event) => {
		event.preventDefault()

		const response = await fetch('/remix-utah/events/301213597/join', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({ /* any necessary data can go here */ }),
		})

		if (response.ok) {
			alert('Successfully joined the event!')
		} else {
			alert('Failed to join the event.')
		}
	})
</script>
```

This script intercepts the form submission, prevents the default browser behavior, and instead sends an asynchronous `POST` request to the server. This way, the page does not need to reload, and the user receives immediate feedback on their action.

You may notice the lack of `method="POST"` in this example and that’s because it’s not strictly necessary since we prevent the browser’s default behavior.

While preventing the full page refresh is great, we lose a lot of things the browser does for us automatically when we prevent that default behavior which result in bugs we find in applications all the time.

For example, race conditions and data revalidation. That said, if you have a framework that helps you with those things (like [React Router](https://reactrouter.com/)/[Remix](https://remix.run)), then the effort is worth the improved user experience.

## React Form Actions

Mutations are an important and common part of dynamic web applications. So is linking to different parts of the application. However, mutating data is complicated because as soon as the user has performed the mutation, there are parts of the UI they could be looking at that could be out of date.

Now, to be clear, with a regular browser mutation there isn’t a problem because the full page refresh means the user always sees the latest that the server has to offer. However, if we’re focused on providing the best user experience possible, the full page refresh is unacceptable. But that means we need to update the data on the page after the mutation.

Another thing that complicates both links and forms in client-side applications is managing pending states. By default, the browser will show a spinner (often in place of the favicon), but when we prevent that default behavior we need to think about giving feedback to the user during the transition.

React has a great solution [for transitions](https://react.dev/reference/react/useTransition), but that’s only half of the story for forms. Because of this added complexity, React 19 has a built-in mechanism for handling forms called “actions.”

Just like the action attribute in an HTML form, you use the action prop in a React component. However, in addition to a URL, you can instead provide a function which will be called upon submission of the form.

```tsx
function JoinEventForm() {
	function joinEvent(formData) {
		const response = await fetch('/remix-utah/events/301213597/join', {
			method: 'POST',
			body: formData,
		})

		if (response.ok) {
			alert('Successfully joined the event!')
		} else {
			alert('Failed to join the event.')
		}
	}

	return (
		<form action={joinEvent}>
			<button type="submit">Join Remix Meetup June 🏖</button>
		</form>
	)
}
```

If you’re familiar with React forms using the `onSubmit` prop, I want you to note a few key differences here:

1. There’s no need to add `event.preventDefault` because that’s handled for us by React
2. The `action` is automatically treated as a transition, so anything that happens during the action which trigger components to suspend will be a part of that same transition. More on this in a bit.
3. We can hook into the pending state of this action using `useFormStatus` .
4. React manages errors and race conditions to ensure our form’s state is always correct (no infinite spinners).

## Pending States

There are a couple ways to manage the pending states for this interaction.

### useFormStatus

If you’re familiar with how context works in React apps, think of the `<form>` component as a provider and the `useFormStatus` hook as a function which accesses that provider’s data. Fundamentally, the `<form>` in React manages state of the status of the form and we can access that in any child component of the `<form>` . So to access the pending state of our form (while the submission is in flight) we need to create a child component.

```tsx
function JoinButton({ children }: { children: React.ReactNode }) {
	const { pending } = useFormStatus()

	return (
		<button type="submit">
			{pending ? 'Joining...' : children}
		</button>
	)
}

function JoinEventForm() {
	async function joinEvent(formData) {
		const response = await fetch('/remix-utah/events/301213597/join', {
			method: 'POST',
			body: formData,
		})

		if (response.ok) {
			alert('Successfully joined the event!')
		} else {
			alert('Failed to join the event.')
		}
	}

	return (
		<form action={joinEvent}>
			<JoinButton>Join Remix Meetup June 🏖</JoinButton>
		</form>
	)
}
```

The cool thing about [the `useFormStatus` hook](https://react.dev/reference/react-dom/hooks/useFormStatus) is that it also gives you access to other things about the form (including the submitted data). So if you’re building a login form, you could have the pending state say: `logging you in as {data.get('username')}` .

One thing I don’t love about it though is the requirement to make an entirely new component to consume the form’s state, so let’s look at an alternative approach.

### useActionState

It’s easiest to explain [`useActionState`](https://react.dev/reference/react/useActionState) with an example:

```tsx
const JOIN_URL = '/remix-utah/events/301213597/join'

async function joinEvent(
	previousState: { joined: boolean },
	formData: FormData,
) {
	const response = await fetch(JOIN_URL, {
		method: 'POST',
		body: formData,
	})

	if (response.ok) {
		return { joined: true }
	} else {
		return { joined: false }
	}
}

function JoinEventForm() {
	const [state, formAction, isPending] = useActionState(
		joinEvent,
		{ joined: false },
		JOIN_URL,
	)

	return (
		<div>
			{state.joined ? (
				<p>See you there!</p>
			) : (
				<form action={formAction}>
					<button type="submit">
						{isPending ? 'Joining...' : 'Join Remix Meetup June 🏖'}
					</button>
				</form>
			)}
		</div>
	)
}
```

Alright, so what’s going on here is `useActionState` accepts a function (`joinEvent`), some initial state (`{ joined: false }`), and optionally a permalink URL (`JOIN_URL`). It then returns an array with the current state (`state`), a function you can call to trigger the action (`formAction`), and whether the form submission is pending (`isPending`).

The `joinEvent` function accepts the previous state. In a way you can think of it as a reducer a la `useReducer`. When our form is submitted, it’s `action` is called with the `formData`. Our `action` is the `formAction`. The `formAction` function will call `joinEvent` with the current state followed by any arguments it’s called with. I understand that may be a little confusing, so let me illustrate by being obnoxiously verbose:

```tsx
function JoinEventForm() {
	const [state, formAction, isPending] = useActionState(
		(prevState, ...args) => joinEvent(prevState, ...args),
		{ joined: false },
		JOIN_URL,
	)

	return (
		<div>
			{state.joined ? (
				<p>See you there!</p>
			) : (
				<form
					action={(formData) => {
						const args = [formData]
						formAction(...args)
					}}
				>
					<button type="submit">
						{isPending ? 'Joining...' : 'Join Remix Meetup June 🏖'}
					</button>
				</form>
			)}
		</div>
	)
}
```

The `action` prop is called with the `formData`, we then make an array called `args` with only one element of `formData` which we then spread into a call of `formAction`. `formAction` then calls our inline function with the `prevState` and the rest of the args (in our case that’s just the `formData`, but as far as `useActionState` is concerned, it doesn’t have to be. It just forwards along whatever arguments there are.

From there, our `joinEvent` function performs whatever async stuff it needs to do, and then it returns a value which ends the transition and triggers our form to rerender with the `state` being equal to our returned value.

Of course during the transition, `isPending` will be `true` so we can show our pending state. However, we don’t have access to the `formData` outside our `action` so we wouldn’t be able to use the form submission as part of our pending UI like we could with `useFormStatus`. But there’s even more we can do!

Before we talk about that, I’ll just briefly mention that the third argument to `useActionState` is called a `permalink` and it’s there for server rendering and progressive enhancement. What React does with that is set the `action` to the URL you provide during server rendering. That way if the form is submitted before React has a chance to load on the page, the regular browser behavior will take over and submit the form with the full-page refresh functionality we’re used to (you’ll just want to make sure your server can handle the form submission properly). Hooray for progressive enhancement!

### useOptimistic

Showing the user feedback of pending tasks is important and useful. It’s awesome if the pending state actually looks like the finished state (maybe with a subtle indicator that it’s not actually complete). A good example of this is when you send a Slack/Discord message. The message appears in the messages list, but it’s slightly transparent to give you the sense that it’s an incomplete mutation.

You can do this with [`useOptimistic`](https://react.dev/reference/react/useOptimistic):

```tsx
// ...

function JoinEventForm() {
	const [state, formAction] = useActionState(
		joinEvent,
		{ joined: false },
		JOIN_URL,
	)
	const [optimisticJoined, setOptimisticJoined] = useOptimistic(state.joined)

	return (
		<div>
			{optimisticJoined ? (
				// show faded a bit if we've not yet finished joining...
				<p style={{ opacity: state.joined ? 1 : 0.8 }}>See you there!</p>
			) : (
				<form
					action={(formData) => {
						setOptimisticJoined(true) // Optimistically set the state to joined
						return formAction(formData)
					}}
				>
					<button type="submit">
						Join Remix Meetup June 🏖
					</button>
				</form>
			)}
		</div>
	)
}
```

The `useOptimistic` hook allows you to immediately update the UI to reflect the user's action before the network request completes. If the actual request fails, the state is reverted to the previous state. This provides a smoother user experience by reducing the perceived latency of the action.

We can even remove the pending UI from the button, but we add a little transparency to the success message to give the impression things are not completely settled. You may want to consider the experience for non-seeing users as well. React provides us with all we need to build this kind of experience!

You can even perform multiple steps and keep the user up-to-date with what’s happening with `useOptimistic`. It’s awesome:

```tsx
// ...

function JoinEventForm() {
	const [state, formAction] = useActionState(
		joinEvent,
		{ joined: false },
		JOIN_URL,
	)
	const [optimisticMessage, setOptimisticMessage] = useOptimistic("")

	return (
		<div>
			{state.joined ? (
				<p>See you there!</p>
			) : (
				<form
					action={async (formData) => {
						setOptimisticMessage("Joining meetup...")
						await formAction(formData)
						setOptimisticMessage("Sending notifications...")
						await sendNotification()
					}}
				>
					<p>{optimisticMessage}</p>
					<button type="submit">
						Join Remix Meetup June 🏖
					</button>
				</form>
			)}
		</div>
	)
}
```

In this example, we use the `useOptimistic` hook to provide feedback to the user at multiple stages of the form submission process. Initially, we set the optimistic message to "Joining meetup...", then await the `formAction`. Once that completes, we update the message to "Sending notification..." and await the `sendNotification` function.

## Conclusion

I think it’s awesome that we’ve not needed to reach for any libraries other than React to have all of this functionality. Really, what’s cool is what you *don’t see* but get like declarative management of errors and pending transitions and proper management of race conditions. And a great Optimistic UI story is also awesome. We also didn’t get to talk much about how this integrates with the server via the [`"use server"`](https://react.dev/reference/rsc/use-server) directive, but that’s a huge win as well which we’ll have to explore in the future.

I hope this article helped you get a more clear picture of what’s possible with React 19’s form primitives.

React 19 introduces terrific primitives for building great forms. Let's dive deep on forms for the web with React.

A deep dive on forms with modern React

When you click a button in your app, how long does it take for the UI to
respond? If you're waiting for a network request to finish before showing the
result, your users might be left staring at a spinner, wondering if anything
happened at all.

That's where **optimistic UI** comes in. The idea is simple: assume the best,
update the UI immediately, and let the server catch up. If something goes wrong,
you can always roll back. But most of the time, things go right—and your app
feels lightning fast.

React 19 introduced a new hook,
[`useOptimistic`](https://react.dev/reference/react/useOptimistic), that makes
this pattern easier than ever.

## What is `useOptimistic`?

`useOptimistic` is a React Hook that lets you show a different state while an
async action is underway. It's perfect for things like instantly adding a new
item to a list when the user submits a form allowing them to quickly add another
item or even change the list item before it's even actually saved. You can also
give users feedback that their action is being processed and even updating the
UI to show individual parts of progress. For example: "reserving your seat" ->
"creating calendar event" -> "sending invitations" -> "done".

Let's see how it works in practice.

## Examples

### Optimistically Toggling a Like Button

Let's try another example: a "Like" button. When a user clicks it, you want the
count to update right away.

```tsx
import { useState, useOptimistic, startTransition } from 'react'

function LikeButton({ initialCount, sendLike }) {
	const [count, setCount] = useState(initialCount)

	// The update function adds the optimistic delta to the count
	const [optimisticCount, addOptimisticLike] = useOptimistic(
		count,
		(current, delta) => current + delta,
	)

	function handleLike() {
		// Optimistically increment the count
		addOptimisticLike(1)

		// Actually send to the server using the provided async function
		startTransition(async () => {
			await sendLike()
			setCount((c) => c + 1)
		})
	}

	return <button onClick={handleLike}>👍 {optimisticCount}</button>
}
```

The user sees the like count go up immediately, even if the network is slow.

### Adding Comments

Suppose you have a comment section. When a user submits a new comment, you want
it to appear instantly—even before the server responds.

Here's how you might do it with `useOptimistic`:

```tsx
import { useState, useOptimistic, startTransition } from 'react'

function CommentSection({ initialComments, sendComment }) {
	const [comments, setComments] = useState(initialComments)

	// The update function merges the optimistic comment into the list
	const [optimisticComments, addOptimisticComment] = useOptimistic(
		comments,
		(currentComments, newComment) => [
			{ ...newComment, optimistic: true },
			...currentComments,
		],
	)

	async function handleAddComment(text) {
		// Show the comment immediately
		addOptimisticComment({ id: Date.now(), text })

		// Actually send to the server using the provided async function
		startTransition(async () => {
			const savedComment = await sendComment(text)
			setComments((prev) => [{ ...savedComment }, ...prev])
		})
	}

	return (
		<div>
			<form
				action={async (formData) => {
					handleAddComment(formData.get('text'))
				}}
			>
				<input name="text" placeholder="Write a comment..." />
				<button type="submit">Add</button>
			</form>
			<ul>
				{optimisticComments.map((comment) => (
					<li
						key={comment.id}
						className={comment.optimistic ? 'text-gray-500' : ''}
					>
						{comment.text}
					</li>
				))}
			</ul>
		</div>
	)
}
```

Notice how the new comment appears instantly, with a grayed out text, even
before the server responds. If there was an error, then the comment will go away
at the end of the transition (you can show an error message if you want). If
there was no error, then the optimistic comment is still gone at the end of the
transition, but the newly created comment will be in the list of regular
comments (and will no longer be grayed out).

### Booking a Flight

Suppose you want to let users book a flight, and you want to show progress
through multiple steps—like "reserving seat", "processing payment", and "sending
confirmation"—with optimistic UI updates for both the booking state and the
progress message. You can accept all async logic and step messages as props,
making the component flexible and focused on UI state.

```tsx
import { useOptimistic, startTransition } from 'react'
import { reserveSeat, processPayment, sendConfirmation } from './api'

function BookFlight() {
	const [message, setMessage] = useOptimistic('Ready to book')

	async function handleBooking(formData: FormData) {
		setMessage('Reserving seat...')
		await reserveSeat(formData.get('flight'))

		setMessage('Processing payment...')
		await processPayment(formData.get('passenger'))

		setMessage('Sending confirmation...')
		const bookingId = await sendConfirmation(
			formData.get('passenger'),
			formData.get('flight'),
		)

		setMessage('Booking complete! Redirecting...')
		// In a real app, you'd use your routing library here
		console.log(`Redirecting to /booking/${bookingId}`)
	}

	return (
		<form action={handleBooking}>
			<input name="passenger" placeholder="Passenger Name" required />
			<input name="flight" placeholder="Flight Number" required />
			<button type="submit">Book Flight</button>
			<div className="mt-2">
				<strong>Status:</strong> {message}
			</div>
		</form>
	)
}
```

This pattern lets you keep all business logic outside the component, while still
providing a rich, step-by-step optimistic UI experience for your users.

## Why Not Just Use `useState`?

You might wonder: why not just update state directly and hope for the best? The
difference is that `useOptimistic` is designed to work seamlessly with React's
concurrent rendering and transitions. It keeps your UI in sync with the "real"
state, and automatically falls back if the action fails or completes.

Additionally, calling `setState` in a transition does not trigger a re-render
due to the nature of React transitions.

## Tips for Using `useOptimistic`

- **Keep your update function pure.** It should only compute the next optimistic
  state, not cause side effects.
- **Handle errors gracefully.** If the server rejects the action, you may want
  to show an error or roll back the optimistic update.
- **Use with transitions.** Pairing `useOptimistic` with `startTransition`
  ensures your UI stays responsive, even during async work.

## Conclusion

Optimistic UI is one of those little touches that can make your app feel
magical. With `useOptimistic`, React gives you a simple, powerful tool to make
your interfaces feel instant—even when the network isn't.

So next time you're building a form, a like button, or anything that talks to a
server, give `useOptimistic` a try. Your users will thank you.

## Ready to Go Deeper?

If you enjoyed this article and want to master hands-on patterns like
`useOptimistic`, Suspense, and more, join me in the Epic React Suspense
workshop! You'll get practical experience, real-world exercises, and a deeper
understanding of modern React.

[Register for Epic React](https://epicreact.dev/) and take your React skills to
the next level!


Make your React apps feel instant with the new useOptimistic hook from React 19. Improve UX by updating UI immediately while async actions complete.

`useOptimistic` to Make Your App Feel Instant

When building accessible React applications, one of the most common requirements
is to ensure that form fields and their labels are properly associated. This
usually means giving each input a unique `id` and making sure the corresponding
`<label>` uses the same value in its `htmlFor` attribute. But if you've ever
tried to build a reusable form component, you know that generating unique IDs
can be a pain.

Let's talk about why this matters, the problems with common approaches, and how
React's `useId` hook makes it all so much easier.

## Why Unique IDs Matter

Imagine you have a form with several fields:

```jsx
function ContactForm() {
	return (
		<form>
			<label htmlFor="name">Name</label>
			<input id="name" type="text" />
			<label htmlFor="email">Email</label>
			<input id="email" type="email" />
		</form>
	)
}
```

This works fine—until you want to reuse a field component multiple times, or
render a list of fields dynamically. If you hardcode the `id` and then reuse
that component, you end up with duplicate IDs, which is invalid HTML and breaks
accessibility for screen readers.

One easy way to tell whether a label is associated with an input is to click on
the label and see if the input is focused. If it is, then the label is
associated with the input. If it's not, then you've got work to do.

## The Temptation of Random IDs (and Why It's a Trap)

A common workaround is to generate a random string for each field:

```jsx
function Field({ label, ...props }) {
	const id = Math.random().toString(36).slice(2)
	return (
		<div>
			<label htmlFor={id}>{label}</label>
			<input id={id} {...props} />
		</div>
	)
}
```

This seems to work, but it introduces subtle bugs:

- The ID changes on every render, which can confuse screen readers.
- If you're doing server-side rendering (SSR), the IDs generated on the server
  won't match the ones on the client, causing hydration errors.

## Enter `useId`: The React Way

React 18 introduced the `useId` hook to solve this exact problem. It generates a
unique, stable ID for each component instance, and it works seamlessly with SSR.

Here's how you use it:

```jsx
import { useId } from 'react'

function Field({ label, ...props }) {
	const id = useId()
	return (
		<div>
			<label htmlFor={id}>{label}</label>
			<input id={id} {...props} />
		</div>
	)
}
```

Now, every time you render `<Field label="Name" />`, it gets a unique, stable
ID. You can safely use this component multiple times—even in lists or dynamic
forms—without worrying about duplicate IDs or hydration mismatches.

## When _Not_ to Use `useId`

It's important to note that `useId` is only for DOM relationships, like
associating a label with an input. Don't use it for React keys in lists:

```jsx
const key = useId()
// ❌ Don't do this!
return <div key={key}>{item}</div>
```

React keys should come from your data, not from `useId`. The ID from `useId` is
only stable for the lifetime of a component instance, not across renders or data
changes.

## Takeaways

- Unique IDs are essential for accessible forms and DOM relationships.
- Generating IDs manually is error-prone, especially with SSR.
- `useId` gives you a stable, unique ID for each component instance, the React
  way.
- Use `useId` for DOM relationships, not for React keys.

For more, check out the
[official React docs on useId](https://react.dev/reference/react/useId).

You'll learn this and other accessibility tips in the workshops on
[EpicReact.dev](https://www.epicreact.dev).


Learn how React’s useId hook ensures unique, accessible form field IDs, avoids SSR bugs, and improves usability in reusable components. Boost accessibility!

Improving React Accessibility with `useId`

Let's say we've got a form that allows you to specify a username. When you try to submit an invalid value, it will show an error message and refocus on the input so you can fix your mistake.

```tsx
import * as React from 'react'

function UsernameForm({
  initialUsername = '',
  onSubmitUsername,
}: {
  initialUsername?: string
  onSubmitUsername: (username: string) => void
}) {
  const [username, setUsername] = React.useState(initialUsername)
  const [touched, setTouched] = React.useState(false)

  const usernameInputRef = React.useRef<HTMLInputElement>(null)

  const usernameIsLowerCase = username === username.toLowerCase()
  const usernameIsLongEnough = username.length >= 3
  const usernameIsShortEnough = username.length <= 10
  const formIsValid =
    usernameIsShortEnough && usernameIsLongEnough && usernameIsLowerCase

  const displayErrorMessage = touched && !formIsValid

  React.useEffect(() => {
    if (displayErrorMessage) usernameInputRef.current?.focus()
  }, [displayErrorMessage])

  let errorMessage = null
  if (!usernameIsLowerCase) {
    errorMessage = 'Username must be lower case'
  } else if (!usernameIsLongEnough) {
    errorMessage = 'Username must be at least 3 characters long'
  } else if (!usernameIsShortEnough) {
    errorMessage = 'Username must be no longer than 10 characters'
  }

  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setTouched(true)
    if (!formIsValid) return

    onSubmitUsername(username)
  }

  function handleChange(event: React.ChangeEvent<HTMLInputElement>) {
    setUsername(event.currentTarget.value)
  }

  function handleBlur() {
    setTouched(true)
  }

  return (
    <form name="usernameForm" onSubmit={handleSubmit} noValidate>
      <div>
        <label htmlFor="usernameInput">Username:</label>
        <input
          ref={usernameInputRef}
          id="usernameInput"
          type="text"
          value={username}
          onChange={handleChange}
          onBlur={handleBlur}
          pattern="[a-z]{3,10}"
          required
          aria-describedby={displayErrorMessage ? 'error-message' : undefined}
        />
      </div>
      {displayErrorMessage ? (
        <div role="alert" className="error-message">
          {errorMessage}
        </div>
      ) : null}
      <button type="submit">Submit</button>
    </form>
  )
}
```

There's a bit going on there, but let's zoom in on the `useEffect`. That's responsible for focusing the input when an error is displayed so the user can fix the problem.

```tsx
React.useEffect(() => {
  if (displayErrorMessage) usernameInputRef.current?.focus()
}, [displayErrorMessage])
```

If you know me, you know that [I'm a firm proponent](/myths-about-useeffect) of the `exhaustive-deps` rule from the [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) package. So you might wonder why my dependency array doesn't include: `usernameInputRef.current`. Isn't that one of the dependencies of my effect callback? After all, what would happen if that value were to change?

Well, let's try adding it to the array:

```tsx
React.useEffect(() => {
  if (displayErrorMessage) usernameInputRef.current?.focus()
}, [displayErrorMessage, usernameInputRef.current])
```

Ah, we get a lint warning from the `exhuastive-deps` rule:

```
React Hook React.useEffect has an unnecessary dependency: 'usernameInputRef.current'.
Either exclude it or remove the dependency array.
Mutable values like 'usernameInputRef.current' aren't valid dependencies because
mutating them doesn't re-render the component.
eslint(react-hooks/exhaustive-deps)
```

Alright, let's dig into that warning. Remember:

**`useRef` is similar to `useState` except changing the value doesn't trigger a re-render.**

In our example above, we're using `useRef` to keep track of a DOM node, but you can use it to keep track of any value whatsoever, just like `useState` (bet you didn't think about putting a function in `useState` before did you 😉, you totally can though).

The fact that an update the a `ref.current` value doesn't trigger a re-render is an intentional feature. React doesn't keep track of the `current` value of a ref. You're responsible for referencing and mutating that value yourself. Because referencing DOM nodes is such a common use case, React will set the `current` value for you when you pass a `ref` prop to an element. But other than that, all React promises is that it will store your object and associate it to a particular instance of a component for as long as that component exists.

By the way, that's what differentiates a `ref` from just a regular variable outside the component. `useRef` ensures that the value is associated with a particular instance of a component.

Alright, so let's bring this back to the warning. Let's recall the purpose of a dependency array: It's there so React can do something when there are changes in the values provided each time the component renders. And that's the answer right there! React can't know that the value changed if a change doesn't trigger a render! Here's a quick contrived example:

```tsx
function Counter() {
  const countRef = React.useRef(0)

  React.useEffect(() => {
    console.log(countRef.current)
  }, [countRef.current])

  const increment = () => (countRef.current += 1)
  return <button onClick={increment}>Click me</button>
}
```

I can click that button over and over again, but I'm never going to get that `useEffect` callback to run again because there's no re-render associated to the update in the value, I won't get any updated logs!

"_But Kent_" you ask, "_what if I *want* an update to a ref to result in a re-render?_" If that's the case, what you actually want is `useState`/`useReducer`, not `useRef`!

## The rule that governs exceptions to the `exhaustive-deps` rule

So refs are an exception to the `exhaustive-deps` rule, but they're actually not the only exception. The exception itself is general. Here's the general rule for the exception:

**Anything you use in your effect callback that won't trigger a re-render when updated should not go into the dependency array.**

Additionally (and consequentially), you should not expect any change in such values to result in the effect callback getting called. If you _need_ the callback to be called when those things change, then you _need_ to put it in `useState` (or `useReducer`).

This general rule is why if you pass the value of a module-level variable into a dependency array like this you'll get a similar lint warning:

```tsx
let log = console.log

function Comp() {
  React.useEffect(() => {
    log(new Date())
  }, [log]) // <-- 🚨 eslint warning here
  return <div>{/* stuff here */}</div>
}
```

Here's what the linter will tell you about that:

```
React Hook React.useEffect has an unnecessary dependency: 'log'.
Either exclude it or remove the dependency array. Outer scope values like 'log'
aren't valid dependencies because mutating them doesn't re-render the component.
eslint(react-hooks/exhaustive-deps)
```

This is because even if I did reassign that `log` variable to something else at some point, React wouldn't know about it so you'd end up with a stale side-effect anyway. So just don't list it, and if you _do_ want a change to trigger the effect to run, then put it in state!

Same thing happens with imports (with the added benefit of the fact that you can't reassign these values anyway):

```tsx
import log from './logger'

function Comp() {
  React.useEffect(() => {
    log(new Date())
  }, [log]) // <-- 🚨 eslint warning here
  return <div>{/* stuff here */}</div>
}
```

The lint warning for this is actually identical to the variable form.

## Custom hooks and the ref object itself

You won't get a warning with code like this:

```tsx
function Comp() {
  const logRef = React.useRef(console.log)
  React.useEffect(() => {
    logRef.current(new Date())
  }, []) // <-- ✅ No eslint warning here
  return <div>{/* stuff here */}</div>
}
```

That's because you're not using any values in your `useEffect` that the lint plugin knows can change on re-renders.

However, you also won't get a warning with code like this:

```tsx
function Comp() {
  const logRef = React.useRef(console.log)
  React.useEffect(() => {
    logRef.current(new Date())
  }, [logRef]) // <-- ✅ No eslint warning here
  return <div>{/* stuff here */}</div>
}
```

That's because the `logRef` value _can never change_. So it actually makes no difference whether you include it or not and I guess the authors of the lint rule decided to not bother you about something that doesn't matter. Good call.

But here's an interesting case. What about a custom hook that accepts a ref?

```tsx
function useDateCall(cbRef) {
  React.useEffect(() => {
    cbRef.current(new Date())
  }, []) // <-- 🚨 eslint warning here
}

function Comp() {
  const logRef = React.useRef(console.log)
  useDateCall(logRef)
  return <div>{/* stuff here */}</div>
}
```

The warning we get there is:

```
React Hook React.useEffect has a missing dependency: 'cbRef'.
Either include it or remove the dependency array.
eslint(react-hooks/exhaustive-deps)
```

The reason we get the warning there when we didn't get it within the component is because ESLint is pretty limited in its ability to trace what you're doing with your JavaScript. So the React plugin for ESLint can't know that `cbRef` is actually a `ref`. So just to be safe, it warns you.

Luckily, as we just learned, including it in the dependency array doesn't make any difference anyway, so just include it!

```tsx
function useDateCall(cbRef) {
  React.useEffect(() => {
    cbRef.current(new Date())
  }, [cbRef]) // <-- ✅ No eslint warning here
}

function Comp() {
  const logRef = React.useRef(console.log)
  useDateCall(logRef)
  return <div>{/* stuff here */}</div>
}
```

And we're all good.

## Conclusion

So the reason you shouldn't list a ref in your `useEffect` dependency array is because it's an indication that you want the effect callback to re-run when a value is changed, but you're not notifying React when that change happens. So the solution is to either:

1. Not include it in the array 2. Put that value in `useState`/`useReducer` so an update will trigger a render.

Hope that cleared up some confusion for you! Good luck.

If you use a ref in your effect callback, shouldn't it be included in the dependencies? Why refs are a special exception to the rule!

Compound Components: Truly Flexible React APIs

What and Why: Compound Components in React

Real-World Impact & When to Use

Get my free 7-part email course on React!

More Articles

A deep dive on forms with modern React

`useOptimistic` to Make Your App Feel Instant

Improving React Accessibility with `useId`

Why you shouldn't put refs in a dependency array