React JSX Element Resolution Explained: Capitalization Rules, AST Compilation, and Dynamic Component Architecture

React JSX Element Resolution Explained: Capitalization Rules, AST Compilation, and Dynamic Component Architecture

JSX is one of the most recognizable features of modern React development. Developers use expressions such as <div>, <Button />, and <UserProfile /> every day, but the syntax hides an important compilation process. Before React can work with a JSX expression, a compiler must parse and transform it into JavaScript that the configured JSX runtime understands.

One small detail controls an important part of this process: capitalization. React developers know that native HTML elements use lowercase names while custom components generally begin with uppercase letters. However, this convention is not merely a visual style preference. It affects how JSX names are classified, how the compiler emits element types, and how TypeScript resolves component references.

The same mechanics become especially important when building dynamic component systems. A dashboard may select widgets from configuration, a design system may expose a component registry, and a form renderer may resolve field components from a schema. These patterns require a clear understanding of the difference between a JSX tag name, a JavaScript variable, and a React component type.

What this guide covers:
  • How JSX distinguishes intrinsic elements from custom components.
  • Why lowercase and uppercase naming conventions matter.
  • How JSX source code becomes an Abstract Syntax Tree (AST).
  • How classic and automatic JSX runtimes differ.
  • How TypeScript resolves JSX element types and validates props.
  • How to implement dynamic component registries safely.
  • How to use lazy-loaded components and configuration-driven rendering.
  • How to troubleshoot common JSX resolution and runtime errors.
React JSX Element Resolution Explained
 React JSX Element Resolution Explained

1. Understanding JSX Element Resolution

JSX is a syntax extension for JavaScript that allows developers to describe UI structures using XML-like markup. It looks similar to HTML, but it is not HTML and browsers do not execute JSX directly.

Consider this React component:

function Welcome() {
  return (
    <section className="welcome">
      <h1>Welcome</h1>
      <UserProfile />
    </section>
  );
}

The browser cannot interpret this JSX as ordinary JavaScript without a compilation step. A JSX-capable compiler transforms the syntax into JavaScript calls or runtime expressions.

Conceptually, the compiler must determine:

  • Whether a JSX name represents a native element or a JavaScript component reference.
  • Which props belong to the element.
  • How child elements and expressions should be represented.
  • Which JSX runtime function should create the element description.
  • How fragments should be represented without adding an extra DOM wrapper.

1.1 JSX and React are separate concepts

JSX is syntax. React is a library that can consume the element descriptions produced by a compatible JSX runtime. JSX is not exclusive to React; other libraries can implement their own JSX runtime and type definitions.

This distinction matters when working with build tools. Babel, TypeScript, SWC, and other compilers can transform JSX according to their configuration. The resulting code depends on the selected transform mode and runtime.

JSX Source Code
↓
Compiler Parser
↓
JSX AST Nodes
↓
JSX Transform
↓
JavaScript Runtime Calls
↓
React Element Descriptions

The JSX compiler does not decide which component should appear based on the visual appearance of the name. It follows defined parsing and transformation rules, including the distinction between intrinsic tag names and JavaScript references.

1.2 What does element resolution mean?

In this context, JSX element resolution means determining what a tag expression represents and how it should be translated into a runtime element type.

For example:

<button />
<PrimaryButton />
<UI.Button />

These three expressions do not represent the same kind of name:

JSX expression Resolution Typical runtime type
<button /> Intrinsic element String: "button"
<PrimaryButton /> JavaScript component reference Identifier: PrimaryButton
<UI.Button /> Member expression reference Object property: UI.Button

2. Capitalization Rules: Intrinsic vs Custom Elements

The lowercase-versus-uppercase convention is one of the fundamental JSX rules. It allows JSX tooling to distinguish names that represent platform elements from names that should be resolved through JavaScript scope.

2.1 Lowercase names represent intrinsic elements

Names such as div, span, button, and input are treated as intrinsic element names in React's JSX conventions.

function LoginForm() {
  return (
    <form>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" />
      <button type="submit">
        Sign in
      </button>
    </form>
  );
}

In the classic JSX transform, these names become string element types:

React.createElement(
  "button",
  { type: "submit" },
  "Sign in"
);

The string identifies the intrinsic element type. In a browser-based React application, this normally corresponds to a DOM element.

2.2 Uppercase names represent component references

Custom React components should begin with an uppercase letter. JSX treats the name as a JavaScript value that must be available in the current scope.

function PrimaryButton() {
  return <button className="primary">Save</button>;
}

function SettingsPage() {
  return (
    <main>
      <PrimaryButton />
    </main>
  );
}

The compiler preserves the component reference rather than converting it into the string "PrimaryButton".

Conceptually, classic JSX output looks like this:

React.createElement(
  PrimaryButton,
  null
);

The JavaScript identifier must resolve to a value. If the component is not imported or declared in scope, the application can fail during compilation or execution depending on the tooling and code path.

2.3 Why lowercase custom component names are problematic

Consider a component declared with a lowercase name:

function userCard() {
  return <div>User details</div>;
}

function Dashboard() {
  return <userCard />;
}

The JSX expression <userCard /> is interpreted as an intrinsic tag name, not as a reference to the JavaScript function userCard.

It does not automatically call the function simply because a function with the same name exists in scope. If the intention is to render the custom component, rename it and use an uppercase JSX identifier.

function UserCard() {
  return <div>User details</div>;
}

function Dashboard() {
  return <UserCard />;
}
Important distinction: JavaScript identifiers are case-sensitive. userCard, UserCard, and USERCARD are different identifiers. JSX capitalization rules also affect whether the name is treated as an intrinsic tag or a component reference.

2.4 Custom HTML elements are a separate consideration

HTML supports custom elements, commonly written with a hyphen, such as <user-card>. These are not the same as React function components.

function Page() {
  return (
    <div>
      <user-card data-user-id="ABC" />
    </div>
  );
}

A custom element name is treated as an intrinsic-style tag name by JSX. Its browser behavior depends on whether the corresponding custom element has been registered with the browser's Custom Elements API.

Do not confuse a web component custom element with a React component. They have different lifecycle and integration models, even though both can appear in JSX.

3. How JSX Resolves Different Tag Names

JSX supports more than simple lowercase and uppercase identifiers. Understanding the different name forms is useful when building reusable component libraries and dynamic UI systems.

3.1 Member expressions

A component can be exposed as a property of an object or namespace-like module.

const UI = {
  Button: PrimaryButton,
  Card: ContentCard
};

function Dashboard() {
  return (
    <UI.Card>
      <UI.Button />
    </UI.Card>
  );
}

The JSX member expression resolves through JavaScript property access. It is not converted into the literal string "UI.Card".

This pattern is useful for component namespaces, grouped design-system exports, and APIs that expose related components together.

3.2 Component references inside JavaScript expressions

JSX does not allow arbitrary JavaScript expressions to be written directly as tag names. Instead, resolve the component into a variable first.

For example, this is not valid JSX:

// Invalid JSX
<components[type] />

Use a JavaScript expression to select the component:

const Component = components[type];

return <Component />;

The capitalized variable is now a valid value-based JSX element reference.

3.3 Fragments

Fragments let components return multiple sibling elements without adding an extra DOM node.

function UserSummary() {
  return (
    <>
      <h2>Account overview</h2>
      <p>Account status: Active</p>
    </>
  );
}

A fragment is not a normal HTML tag. It is a special JSX construct that the transform maps to the configured fragment runtime representation.

In React's automatic runtime, the compiler uses the Fragment export from the JSX runtime. In the classic runtime, fragments are represented through the configured fragment pragma, commonly React.Fragment.

3.4 Dynamic expressions inside JSX

JavaScript expressions can be embedded inside JSX braces. This is the standard way to render a component selected at runtime.

const selectedComponent = isAdmin
  ? AdminPanel
  : UserPanel;

function AccountPage() {
  return (
    <main>
      {isAdmin
        ? <AdminPanel />
        : <UserPanel />}
    </main>
  );
}

For more complex systems, selecting the component before rendering usually makes the code easier to maintain.

Understanding how JSX resolves component references is only one part of building scalable React applications; production systems also need a predictable architecture for coordinating route rendering, asynchronous data dependencies, and nested UI composition. The next step is to connect component architecture with route-level data orchestration using parallel loaders, reusable layouts, and strongly typed data contracts.

Related architecture deep dive: React Router v6 Data Architecture: Parallel Loaders, Nested Layouts, and Type-Safe Route Data

4. JSX Parsing and AST Transformation

To understand JSX compilation, it helps to look at what a compiler does internally. A compiler does not simply search for angle brackets and replace them with function calls. It parses source code into a structured representation called an Abstract Syntax Tree.

4.1 What is an Abstract Syntax Tree?

An Abstract Syntax Tree, or AST, represents the structure of source code as nodes. Each node describes a language construct, such as a function declaration, identifier, call expression, object expression, or JSX element.

For example, this JSX:

const element = <PrimaryButton disabled />;

contains several meaningful parts:

  • A variable declaration for element.
  • A JSX element node.
  • A JSX opening element.
  • A JSX identifier named PrimaryButton.
  • A JSX attribute named disabled.

The compiler can inspect these nodes without treating the source as an unstructured string.

4.2 JSX AST node structure

In Babel's AST representation, JSX-related syntax is represented through node types such as:

AST node Purpose
JSXElement Represents a complete JSX element.
JSXOpeningElement Represents the opening tag and its attributes.
JSXClosingElement Represents the closing tag.
JSXIdentifier Represents a JSX name such as Button or div.
JSXAttribute Represents an attribute such as disabled or className.
JSXExpressionContainer Represents a JavaScript expression inside braces.
JSXFragment Represents fragment syntax.

These node names are useful when inspecting compiler output or writing custom Babel plugins. Exact AST structures and helper APIs depend on the compiler and version.

4.3 The compiler transformation pipeline

A typical JSX compilation pipeline has multiple stages:

1. Source Code
JSX + JavaScript + TypeScript
↓
2. Parsing
Tokenization and AST construction
↓
3. Transformation
JSX nodes become runtime expressions
↓
4. Code Generation
JavaScript output is emitted
↓
5. Bundling and Execution
Modules are packaged and runtime code executes

The JSX transform is generally one part of a larger build pipeline. A TypeScript project may also remove type annotations, resolve module syntax, and apply other transformations before the output is bundled.

4.4 How capitalization affects AST transformation

Consider two expressions:

<button type="button" />
<PrimaryButton type="button" />

The compiler distinguishes the intrinsic name from the component reference. The resulting runtime calls are conceptually different:

// Intrinsic element
jsx("button", {
  type: "button"
});

// Custom component reference
jsx(PrimaryButton, {
  type: "button"
});

The first argument is a string for the intrinsic element and a JavaScript value for the custom component.

This distinction explains why a lowercase function name does not become a component merely because it exists in the current module. The compiler has already classified the JSX name according to its syntax.

4.5 Inspecting JSX output with Babel

Babel provides a JSX transformation plugin that can convert JSX into JavaScript. The transform can use either the classic or automatic runtime.

A simplified Babel configuration using the automatic runtime looks like this:

{
  "presets": [
    [
      "@babel/preset-react",
      {
        "runtime": "automatic"
      }
    ]
  ]
}

For a TypeScript application, the project may use a separate TypeScript transform or a toolchain that handles both JSX and TypeScript syntax. Avoid configuring multiple independent transforms to process the same syntax unless the build pipeline explicitly requires it.

Developer debugging technique: When JSX output is unclear, inspect the compiled JavaScript rather than guessing. Compare a lowercase intrinsic tag, an uppercase component identifier, a member expression, and a fragment to see how your actual build configuration transforms each expression.

5. Classic Runtime vs Automatic Runtime

React projects commonly use one of two JSX runtime styles: the classic runtime or the automatic runtime. The difference affects the generated JavaScript, imports, and configuration requirements.

5.1 Classic JSX runtime

The classic transform commonly converts JSX into calls to React.createElement.

Example source:

const element = (
  <PrimaryButton variant="primary">
    Save changes
  </PrimaryButton>
);

Conceptual classic output:

const element = React.createElement(
  PrimaryButton,
  { variant: "primary" },
  "Save changes"
);

Because the default factory references React.createElement, older configurations generally require React to be in scope when JSX is transformed this way.

5.2 Automatic JSX runtime

The automatic runtime was introduced to remove the need for a React import solely to support JSX transformation. The compiler automatically imports the required functions from the configured JSX runtime package.

Example source:

const element = (
  <PrimaryButton variant="primary">
    Save changes
  </PrimaryButton>
);

Conceptual automatic output:

import { jsx as _jsx } from "react/jsx-runtime";

const element = _jsx(PrimaryButton, {
  variant: "primary",
  children: "Save changes"
});

The exact generated output can differ based on the compiler, development or production mode, and the number of children. For example, the runtime may use jsxs for elements with multiple static children.

5.3 Runtime comparison

Area Classic runtime Automatic runtime
Typical transform React.createElement jsx, jsxs
React import for JSX alone Usually required with default factory Not required solely for JSX
Fragment handling Configured fragment pragma Runtime Fragment export
Configuration Classic JSX factory Automatic JSX runtime
Typical usage Legacy or custom configurations Modern React toolchains

5.4 TypeScript JSX compiler settings

TypeScript exposes several JSX compiler modes through the jsx option.

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

Common JSX modes include:

  • preserve – keeps JSX in the emitted output for another tool to transform.
  • react – uses the classic React factory transform.
  • react-jsx – uses the automatic JSX runtime.
  • react-jsxdev – uses the automatic development runtime.
  • react-native – preserves JSX while using the React Native-oriented output mode.

Choose a mode that matches the build system. A project using Babel, SWC, Vite, or another compiler may delegate JSX transformation to that tool rather than relying entirely on TypeScript's emitted JavaScript.

6. TypeScript JSX Element Resolution

TypeScript adds a static type-checking layer to JSX. It checks whether a tag name is valid, whether the component reference can be resolved, and whether the supplied props match the component's declared contract.

6.1 Intrinsic elements and value-based elements

TypeScript distinguishes two important categories:

  • Intrinsic elements: Environment-defined tags such as div, button, and input.
  • Value-based elements: JavaScript references such as PrimaryButton and UserProfile.

For intrinsic elements, TypeScript checks the element name and its attributes against the configured JSX type definitions. For custom components, it resolves the component value and checks its props.

6.2 Define component props explicitly

type ButtonProps = {
  children: React.ReactNode;
  variant?: "primary" | "secondary";
  disabled?: boolean;
  onClick?: () => void;
};

function PrimaryButton({
  children,
  variant = "primary",
  disabled = false,
  onClick
}: ButtonProps) {
  return (
    <button
      className={`button button-${variant}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

TypeScript can now validate the JSX usage:

<PrimaryButton variant="primary">
  Save
</PrimaryButton>

// Type error: invalid variant
<PrimaryButton variant="danger">
  Delete
</PrimaryButton>

This validation depends on the component's declared props and the JSX type-checking configuration.

6.3 TypeScript resolves component references through scope

A value-based JSX element must refer to a valid identifier or member expression.

import { UserProfile } from "./UserProfile";

function AccountPage() {
  return <UserProfile />;
}

If the identifier is missing, misspelled, or imported incorrectly, TypeScript reports an error because it cannot resolve the component reference.

This is another reason why component capitalization is more than a naming convention: it changes the category of JSX expression TypeScript and the JSX transform expect.

6.4 Type component references explicitly

When building dynamic component systems, TypeScript's React component types are useful for describing valid component references.

import type { ComponentType } from "react";

type PanelProps = {
  title: string;
};

const PanelRegistry: Record<
  string,
  ComponentType<PanelProps>
> = {
  profile: ProfilePanel,
  settings: SettingsPanel
};

Each registered component must accept the expected props. This is a useful starting point for a registry in which every component follows a common interface.

When components have different props, use a more specific mapping or a discriminated union rather than forcing unrelated component contracts into one broad type.

7. Dynamic Component Architecture in React

Dynamic component architecture allows an application to select which component to render based on runtime information. This pattern is common in dashboard builders, configurable forms, content management systems, admin panels, and page composition tools.

For example, a dashboard configuration may describe which widgets should appear:

const dashboardConfig = [
  { type: "revenue", title: "Revenue" },
  { type: "users", title: "Active users" },
  { type: "orders", title: "Recent orders" }
];

Instead of writing a separate conditional branch for every widget in the page, the application can resolve each configuration entry to a component.

7.1 Basic dynamic component selection

const componentMap = {
  revenue: RevenueWidget,
  users: UsersWidget,
  orders: OrdersWidget
};

function DashboardWidget({ type }) {
  const Component = componentMap[type];

  if (!Component) {
    return <p>Unsupported widget</p>;
  }

  return <Component />;
}

The key step is assigning the selected component to a capitalized variable. JSX then treats Component as a value-based element reference.

For a production application, the registry and its keys should be typed instead of relying on unrestricted string indexing.

7.2 Why not use a large conditional tree?

A conditional renderer is reasonable for a small number of fixed alternatives. However, it can become difficult to maintain as the number of component types increases.

function RenderWidget({ type }) {
  if (type === "revenue") {
    return <RevenueWidget />;
  }

  if (type === "users") {
    return <UsersWidget />;
  }

  if (type === "orders") {
    return <OrdersWidget />;
  }

  return null;
}

As new widget types are introduced, the renderer grows and becomes a central location for unrelated component decisions.

A registry provides a more declarative mapping between a configuration key and its component implementation.

7.3 Separate component selection from component rendering

A useful architecture has three responsibilities:

  1. Configuration: Describes which component should appear and what data it needs.
  2. Resolution: Maps the configuration type to an approved component.
  3. Rendering: Passes validated props to the selected component.
Dashboard Configuration
↓
Component Resolver / Registry
↓
Type-Safe Component Selection
↓
React Component Rendering

This separation makes it easier to test the resolver independently and change the implementation of a widget without rewriting the dashboard's rendering logic.

8. Building a Type-Safe Component Registry

A production component registry should prevent unknown keys, invalid props, and accidental component selection. TypeScript can provide strong guarantees when all registered components share a known contract.

8.1 Define a common component contract

import type { ComponentType } from "react";

type WidgetProps = {
  title: string;
  refreshInterval?: number;
};

type WidgetType =
  | "revenue"
  | "users"
  | "orders";

type WidgetRegistry = Record<
  WidgetType,
  ComponentType<WidgetProps>
>;

const widgetRegistry: WidgetRegistry = {
  revenue: RevenueWidget,
  users: UsersWidget,
  orders: OrdersWidget
};

The registry now requires every declared widget type to have a component that accepts WidgetProps. It also prevents arbitrary string keys from being treated as valid widget types in strictly typed code.

8.2 Resolve and render safely

type DashboardWidgetConfig = {
  id: string;
  type: WidgetType;
  title: string;
  refreshInterval?: number;
};

function DashboardWidget({
  config
}: {
  config: DashboardWidgetConfig;
}) {
  const Component = widgetRegistry[config.type];

  return (
    <Component
      title={config.title}
      refreshInterval={config.refreshInterval}
    />
  );
}

The resolver is simple because the configuration type already restricts the allowed widget names. The component receives only the props defined by the shared contract.

8.3 What if components need different props?

Not every dynamic component should be forced into a single props interface. A chart may need a dataset, while a user table may need pagination and sorting options.

For these cases, a discriminated union can represent the relationship between the component type and its required configuration.

type WidgetConfig =
  | {
      id: string;
      type: "revenue";
      title: string;
      currency: string;
    }
  | {
      id: string;
      type: "users";
      title: string;
      pageSize: number;
    }
  | {
      id: string;
      type: "orders";
      title: string;
      status: "open" | "closed";
    };

A resolver can narrow the configuration before rendering:

function renderWidget(config: WidgetConfig) {
  switch (config.type) {
    case "revenue":
      return (
        <RevenueWidget
          title={config.title}
          currency={config.currency}
        />
      );

    case "users":
      return (
        <UsersWidget
          title={config.title}
          pageSize={config.pageSize}
        />
      );

    case "orders":
      return (
        <OrdersWidget
          title={config.title}
          status={config.status}
        />
      );
  }
}

This approach gives each widget its own prop contract while keeping the selection logic exhaustive. If a new union member is added, TypeScript can help identify resolver code that needs to be updated.

8.4 Avoid unsafe type assertions

A common shortcut is to cast an arbitrary configuration value to a component key:

// Avoid trusting arbitrary external input
const Component =
  widgetRegistry[config.type as WidgetType];

The assertion only tells TypeScript to trust the developer. It does not validate the value at runtime.

If configuration comes from an API, database, user-created dashboard, or CMS, validate it before resolving a component. A runtime schema or explicit allowlist can prevent unsupported values from entering the renderer.

Security consideration: Never treat an arbitrary string from an external source as permission to import or execute an arbitrary module. Use an approved component registry and validate configuration values. A component renderer should expose only the UI capabilities the application intends to support.

9. Lazy Loading and Dynamic Imports

Dynamic component architecture can also improve initial loading performance when large or infrequently used components are loaded only when needed.

React provides lazy for declaring components that are loaded through a dynamic import. The component can then be rendered inside a Suspense boundary.

9.1 Create lazy component references

import { lazy } from "react";

const ReportsPage = lazy(
  () => import("./pages/ReportsPage")
);

const AnalyticsPage = lazy(
  () => import("./pages/AnalyticsPage")
);

const SettingsPage = lazy(
  () => import("./pages/SettingsPage")
);

These declarations create lazy component types. The imported modules are requested when React attempts to render the corresponding lazy component.

9.2 Build a lazy component registry

import { lazy, Suspense } from "react";

const pageRegistry = {
  reports: lazy(() => import("./pages/ReportsPage")),
  analytics: lazy(() => import("./pages/AnalyticsPage")),
  settings: lazy(() => import("./pages/SettingsPage"))
};

type PageKey = keyof typeof pageRegistry;

function DynamicPage({ page }: { page: PageKey }) {
  const Component = pageRegistry[page];

  return (
    <Suspense fallback={<p>Loading page...</p>}>
      <Component />
    </Suspense>
  );
}

The registry limits selection to known page keys. The Suspense boundary provides fallback UI while the lazy component is waiting for its module to load.

9.3 Understand error handling for lazy imports

Suspense handles the loading state, but it is not a complete error-handling solution for failed imports. A rejected lazy import should be handled through an Error Boundary or another appropriate error recovery strategy.

For a production route or dashboard, consider:

  • A loading fallback that matches the expected component layout.
  • An Error Boundary around independently failing UI regions.
  • A retry or refresh strategy for recoverable chunk-loading failures.
  • Stable component declarations rather than recreating lazy component types during every render.
  • Monitoring for failed dynamic imports and deployment-version mismatches.

9.4 Do not confuse dynamic component selection with dynamic imports

These are related but different operations:

Technique What it does
Dynamic component selection Selects a component reference that is already available.
Dynamic import Loads a JavaScript module asynchronously.
React.lazy Creates a component that can load through a dynamic import.
Suspense Displays fallback UI while a supported child suspends.

A component registry can use ordinary imported components, lazy components, or a combination of both. The correct choice depends on bundle size, route boundaries, and the expected usage frequency of each component.

10. Performance and Rendering Considerations

Dynamic rendering does not automatically make an application slower. However, component identity, registry construction, state placement, and lazy-loading boundaries can influence rendering behavior.

10.1 Keep component references stable

Avoid creating a new component function inside a parent component every time it renders unless that behavior is intentional.

function Dashboard() {
  // Avoid defining a new component type on every render.
  function DynamicWidget() {
    return <RevenueWidget />;
  }

  return <DynamicWidget />;
}

Each execution creates a new function identity. When used as a component type, this can cause React to treat it as a different component type and reset its subtree rather than preserving the previous component instance.

Prefer defining component types and registries at module scope when their definitions do not depend on render-local values.

function DynamicWidget() {
  return <RevenueWidget />;
}

function Dashboard() {
  return <DynamicWidget />;
}

10.2 Do not confuse element identity with component identity

A JSX expression creates a React element description. The component type is the function, class, or other valid type referenced by that element. The element object itself is not the component implementation.

For example:

const firstElement = <UserProfile />;
const secondElement = <UserProfile />;

These are two element descriptions that reference the same component type. React uses element type, position, and keys as part of reconciliation to determine how the rendered tree should be updated.

Creating a new element description during a render is normal. Creating a new component type unnecessarily is a different issue.

10.3 Use stable keys for dynamic lists

When rendering a list of dynamically selected components, each element should have a stable key that identifies the item across updates.

function Dashboard({ widgets }) {
  return (
    <div>
      {widgets.map(widget => {
        const Component = widgetRegistry[widget.type];

        return (
          <Component
            key={widget.id}
            title={widget.title}
          />
        );
      })}
    </div>
  );
}

Use a stable identifier from the data model rather than an array index when the list can be reordered, inserted into, or filtered. Keys help React match sibling elements during reconciliation.

10.4 Avoid unnecessary registry recreation

For a static component map, define the registry outside the component so the same mapping is reused.

const widgetRegistry = {
  revenue: RevenueWidget,
  users: UsersWidget,
  orders: OrdersWidget
};

function Dashboard({ widgets }) {
  return widgets.map(widget => {
    const Component = widgetRegistry[widget.type];

    return (
      <Component
        key={widget.id}
        title={widget.title}
      />
    );
  });
}

If a registry genuinely depends on runtime values, build it deliberately and consider whether a different resolver design would make the dependencies clearer. Memoization should be based on actual requirements rather than added automatically.

11. Common JSX Resolution Errors and How to Debug Them

Many JSX errors are caused by a mismatch between the intended component reference and the expression the compiler actually sees.

Problem Typical cause Correction
Lowercase custom component Component is written as an intrinsic tag. Rename it with an uppercase first letter.
Component is undefined Missing import, incorrect export, or incorrect identifier. Verify the module export and import path.
Invalid dynamic JSX tag JavaScript property access is placed directly in the tag name. Resolve the component to an uppercase variable first.
Invalid component props Configuration and component prop contracts do not match. Use explicit prop types and runtime validation.
Lazy component never displays Missing Suspense boundary or failed module loading. Add a fallback and error handling.
Unexpected component state reset Component type or key changes between renders. Keep component types stable and use stable keys.
JSX runtime import error Compiler and runtime configuration are inconsistent. Align the JSX transform with the installed runtime.

11.1 Debug an unresolved component

When a component does not render as expected, check these items in order:

  1. Confirm the JSX tag begins with an uppercase letter if it represents a custom component.
  2. Confirm the identifier exists in the current module scope.
  3. Check whether the component is a default export or named export.
  4. Inspect the compiled JavaScript to confirm the expected component reference is emitted.
  5. Check whether the registry key exists before rendering.
  6. Verify that the selected value is a valid React component type.
  7. Inspect the browser console for module loading, rendering, or runtime errors.

11.2 Inspect the actual compiler output

When a JSX expression behaves unexpectedly, compile a small isolated example using the same build configuration as the application.

Compare the output for:

<button />
<PrimaryButton />
<UI.Button />
<><span /></>

This makes it easier to identify whether the problem comes from JSX parsing, component scope, TypeScript checking, or runtime behavior.

12. Production-Style Example: Configuration-Driven Dashboard Renderer

The following example combines a typed widget configuration, an approved component registry, dynamic component selection, and stable list keys. It demonstrates a practical pattern for applications that render a dashboard from structured configuration.

12.1 Define the widget components

type WidgetProps = {
  title: string;
};

function RevenueWidget({ title }: WidgetProps) {
  return (
    <section>
      <h2>{title}</h2>
      <p>Revenue summary</p>
    </section>
  );
}

function UsersWidget({ title }: WidgetProps) {
  return (
    <section>
      <h2>{title}</h2>
      <p>Active user summary</p>
    </section>
  );
}

function OrdersWidget({ title }: WidgetProps) {
  return (
    <section>
      <h2>{title}</h2>
      <p>Recent order summary</p>
    </section>
  );
}

12.2 Create the typed registry

import type { ComponentType } from "react";

type WidgetType =
  | "revenue"
  | "users"
  | "orders";

const widgetRegistry: Record<
  WidgetType,
  ComponentType<WidgetProps>
> = {
  revenue: RevenueWidget,
  users: UsersWidget,
  orders: OrdersWidget
};

12.3 Define configuration data

type DashboardWidgetConfig = {
  id: string;
  type: WidgetType;
  title: string;
};

const dashboardWidgets: DashboardWidgetConfig[] = [
  {
    id: "widget-ABC",
    type: "revenue",
    title: "Revenue"
  },
  {
    id: "widget-XYZ",
    type: "users",
    title: "Active Users"
  },
  {
    id: "widget-ORDERS",
    type: "orders",
    title: "Recent Orders"
  }
];

12.4 Implement the renderer

function DashboardRenderer() {
  return (
    <main className="dashboard-grid">
      {dashboardWidgets.map(widget => {
        const Component = widgetRegistry[widget.type];

        return (
          <Component
            key={widget.id}
            title={widget.title}
          />
        );
      })}
    </main>
  );
}

This implementation has several useful properties:

  • The configuration uses a finite set of allowed widget types.
  • The registry provides a direct mapping between each type and its component.
  • Every registered component follows a shared prop contract.
  • The renderer does not need a long chain of conditional statements.
  • Stable IDs are used as React keys.
  • The registry is defined outside the component and does not change on every render.

12.5 Validate configuration received from an API

In a real application, dashboard configuration may come from an API or database. TypeScript types do not validate JSON at runtime. A response can contain unexpected values even if the local code declares a strict interface.

Validate external data before passing it to the renderer. For example, a schema validator can ensure that:

  • The widget type is one of the supported values.
  • Each widget has a valid identifier.
  • Required properties are present.
  • Optional settings have the expected data types.
  • Unsupported widget types are rejected or handled gracefully.

Keep the component registry as an explicit allowlist. The configuration should choose among approved components rather than determine arbitrary module paths or executable code.

Architecture takeaway: JSX capitalization determines how a component name is interpreted. A typed registry then provides the application-level mapping from validated configuration to approved component references. These are separate stages, and keeping them separate makes dynamic rendering easier to reason about.

13. Production Architecture Checklist

Use this checklist when reviewing JSX-heavy component libraries, design systems, or configuration-driven rendering systems.

  • Native intrinsic tags use the expected lowercase naming convention.
  • Custom React components use uppercase identifiers.
  • Component identifiers are imported or declared in scope.
  • Member expressions are used only for valid component references.
  • Dynamic selections are assigned to capitalized variables before JSX rendering.
  • The JSX compiler configuration matches the project's runtime.
  • TypeScript JSX mode is aligned with the build toolchain.
  • Component props have explicit and meaningful types.
  • Dynamic registries use finite, approved keys.
  • External configuration is validated at runtime.
  • Different component prop contracts are modeled accurately.
  • Lazy components have Suspense fallbacks and error handling.
  • Component types are not recreated unnecessarily during rendering.
  • Dynamic lists use stable keys.
  • Compiler output is inspected when resolution behavior is unclear.
  • Tests cover supported configuration values and unknown values.

14. Final Thoughts

JSX element resolution is a small but important part of React's rendering architecture. The capitalization convention determines whether JSX treats a name as an intrinsic element or a JavaScript component reference. That distinction is reflected in the generated JavaScript and in TypeScript's JSX type checking.

Understanding the compiler pipeline makes this behavior easier to debug. JSX is parsed into structured syntax nodes, transformed according to the configured runtime, and emitted as JavaScript expressions. The classic runtime commonly uses React.createElement, while the automatic runtime uses functions such as jsx and jsxs.

These fundamentals become especially useful when building dynamic component systems. A well-designed registry separates configuration from component selection, provides explicit prop contracts, and prevents arbitrary external values from choosing unsupported components.

For production applications, combine the JSX rules with strict TypeScript types, runtime validation, stable component identities, appropriate lazy-loading boundaries, and predictable rendering behavior. This creates a component architecture that is easier to extend, test, and maintain.

15. Frequently Asked Questions

1. Why must React component names start with an uppercase letter?

JSX uses capitalization to distinguish intrinsic element names from JavaScript component references. Lowercase names are treated as intrinsic tags, while uppercase names are resolved as values in JavaScript scope.

2. What happens if a custom React component starts with a lowercase letter?

JSX treats the lowercase name as an intrinsic tag rather than a reference to the function or variable. Rename the component with an uppercase first letter and use that identifier in JSX.

3. Does JSX compile directly into React.createElement?

Not always. The classic runtime commonly transforms JSX into React.createElement calls. The automatic runtime uses functions such as jsx and jsxs from the configured JSX runtime.

4. What is JSX AST transformation?

It is the process of parsing JSX into structured syntax nodes and transforming those nodes into JavaScript expressions supported by the configured runtime. Compilers such as Babel and TypeScript can perform JSX transformations.

5. What is the difference between an intrinsic element and a custom component?

An intrinsic element is a platform-defined tag such as div or button. A custom component is a JavaScript value, such as UserProfile, that React uses as the element type.

6. How do you render a component dynamically in React?

Select a valid component reference in JavaScript, assign it to a capitalized variable, and render it using JSX. For larger systems, use a typed component registry with an approved set of component types.

7. Can JSX render a component using a lowercase variable?

A lowercase variable cannot be used directly as a value-based JSX tag under the normal naming convention. Assign the component reference to an uppercase variable before using it in JSX.

8. What is the difference between React.lazy and dynamic component selection?

Dynamic component selection chooses a component reference that is already available. React.lazy creates a component that can load its implementation asynchronously through a dynamic import.

9. Why should dynamic component registries be type-safe?

Type-safe registries restrict component selection to supported keys and help ensure that the selected component receives valid props. Runtime validation is still necessary when configuration comes from external sources.

10. Does creating a new JSX element cause a component to remount?

No. Creating new element descriptions during rendering is normal. Remounting is more closely related to changes in component type, tree position, or key identity. Defining a new component function inside another component can unintentionally create a new component type on each render.

16. Official Documentation and Further Reading

For compiler behavior, JSX configuration, and React runtime details, use the official documentation as the primary reference.

Technical note: JSX transformation output depends on the compiler, runtime mode, and build configuration. The generated JavaScript examples in this guide are representative illustrations; inspect your project's actual compiler output when debugging version-specific behavior.

Comments