Config-driven UI is useful when product screens change faster than the components underneath them.
It is also easy to overbuild. A small JSON layout file can become a private framework with its own conditionals, routing rules, validation model, and debugging tax. The trick is knowing where the pattern helps and where plain JSX is still the better tool.
Link to this sectionWhat config-driven UI means in React
Config-driven UI means the page structure comes from data instead of being hard-coded directly in JSX.
The React components still exist. You still own the design system, state management, validation, and behavior. The config decides which approved components appear, in what order, and with which props.
A minimal config might look like this:
{
"layout": [
{
"id": "hero",
"type": "HeroBanner",
"props": {
"title": "Welcome to the Dashboard"
}
},
{
"id": "stats",
"type": "StatsGrid",
"props": {
"columns": 3
}
}
]
}That config is not rendering arbitrary UI. It is selecting from a known set of components.
That distinction matters.
Link to this sectionThe core pattern is config, registry, renderer
A config-driven UI system usually has three parts.
First, the config describes the screen.
Second, a component registry maps string names to real React components:
import HeroBanner from "@/components/HeroBanner";
import StatsGrid from "@/components/StatsGrid";
export const componentMap = {
HeroBanner,
StatsGrid,
};Third, a renderer reads each config item and renders the matching component:
type LayoutItem = {
id: string;
type: keyof typeof componentMap;
props: Record<string, unknown>;
};
export function ConfigRenderer({ layout }: { layout: LayoutItem[] }) {
return layout.map((item) => {
const Component = componentMap[item.type];
if (!Component) {
return null;
}
return <Component key={item.id} {...item.props} />;
});
}In a Next.js app, the config can be imported at build time, loaded from a CMS, or fetched from an internal API.
The implementation detail matters less than the boundary: config controls composition, not arbitrary execution.
Link to this sectionWhere config-driven UI helps
The pattern is strongest when you need controlled flexibility.
Good use cases include:
- landing pages assembled from approved sections
- dashboards where cards can be reordered or hidden
- onboarding flows that vary by customer segment
- internal tools where non-engineers need safe layout control
- repeated page templates with different content and component order
In those cases, config reduces repetitive JSX and lets one renderer support several page variants.
It also gives AI tools a cleaner target. Instead of asking a model to rewrite a React page, you can ask it to propose a layout config that uses known components. That is easier to review and safer to reject.
Link to this sectionWhere the pattern starts to break
Config-driven UI gets expensive when the config starts describing behavior.
The warning signs are predictable:
- the config needs nested conditionals
- component props become untyped blobs
- product logic moves out of React and into JSON
- debugging requires reading the renderer, the config, and hidden defaults
- every new component needs special renderer behavior
At that point, you have not simplified the system. You have created a second programming language with worse tooling.
Use JSX when the screen is unique, behavior-heavy, or easier to understand as code. Config is not a virtue by itself.
Link to this sectionValidate config before rendering it
The most important production rule is validation.
Do not render untrusted config directly. Validate the shape, component type, and props before they reach the renderer. A schema library such as Zod works well because it gives you runtime validation and TypeScript inference from the same source.
The renderer should also fail safely. Unknown component type? Skip it or render a controlled fallback. Invalid props? Log the issue and avoid rendering broken UI.
This is especially important if config comes from a CMS, admin tool, database, or AI-generated output. Config is data, but it still controls the interface users see.
Link to this sectionThe practical rule
Use config-driven UI to rearrange known components.
Do not use it to invent a full UI language unless you are prepared to maintain a full UI language.
For most React and Next.js apps, the right version is boring: a typed schema, a small registry, a renderer with strict fallbacks, and clear limits on what the config is allowed to express.
That gives you flexibility without turning JSON into your least-debuggable framework.