When to Use Imperative vs Declarative APIs

React encourages a declarative style: you describe what the UI should look like for a given state, and React reconciles the DOM to match. Most behavior flows through props and state rather than direct DOM commands.

This model makes UIs predictable, since the rendered output is a pure function of state rather than the result of a sequence of manual mutations.

Some interactions resist a purely declarative expression. Imperatively focusing an element, triggering an animation at a precise moment, or driving a third-party DOM widget often cannot be captured cleanly as a function of state.

For these cases React provides escape hatches like refs and imperative handles, used sparingly where declarative props fall short.

Imperative APIs come with tradeoffs. They are harder to test, since you must drive methods and observe side effects, and they can break the unidirectional data flow that makes React apps easy to follow.

Imperative calls also tend to scatter behavior across event handlers rather than concentrating it in a clear state-to-UI mapping, raising maintenance cost.

Prefer declarative APIs and reach for imperative ones only for interactions and measurements: focus, scroll, animations, media playback, and reading sizes or positions.

If something can be modeled as state that maps to rendered output, do that. If it is a momentary action with no clean state representation, an imperative handle is appropriate.

A declarative modal renders based on an isOpen prop the parent owns, so visibility is driven by state. An imperative modal exposes open and close methods, hiding its own state behind a handle.

The declarative version fits React data flow better and is usually preferred, while the imperative version can be convenient when triggering must happen from scattered, event-driven code.

You can reset a form declaratively by changing its key prop, which forces React to remount it fresh with default state. No imperative call is required.

The imperative alternative exposes a reset method on a handle. The key trick is often cleaner because it leans on React reconciliation rather than manual state clearing.

The Next.js router exposes imperative methods like push, replace, and prefetch. Prefetching a route ahead of a likely navigation is an action, not a piece of render state, so an imperative call fits naturally.

This shows that even idiomatic React tooling uses imperative APIs where the operation is fundamentally an action triggered at a moment in time.

The official guidance frames refs and imperative handles as escape hatches, tools for stepping outside the declarative model when you genuinely must. They are not the default way to build features.

Keeping this mindset prevents overuse: you reach for an escape hatch only after confirming that props and state cannot express the behavior cleanly.

Before adding an imperative handle, ask: can this be state mapped to UI? If yes, stay declarative. Is it a focus, scroll, measurement, animation, or third-party action? If yes, imperative may be justified.

Also confirm the surface is small and documented, and that you are not using a ref simply to pass data a prop could carry.

Real applications blend both approaches. The vast majority of logic stays declarative, with a thin layer of imperative handles for the handful of interactions that need them.

Striking this balance keeps your code predictable and testable while still letting you handle focus management, media control, and library integration where declarative code cannot reach.

Choose when an imperative API is the right tool.

React defaults to declarative UI driven by props and state, which is predictable and testable. Imperative handles exist as escape hatches for focus, scroll, animation, measurement, and third-party DOM control.

Compare declarative and imperative modals, prefer the key prop for form resets, and recall that even the Next.js router uses imperative methods for actions. Keep the imperative layer small, documented, and justified.