OpenAEC-Foundation/solid-syntax-jsx

solid-syntax-jsx

Quick Reference

JSX Compilation Model

SolidJS compiles JSX to direct DOM creation calls -- there is NO virtual DOM. Components execute once during initialization. Dynamic expressions in {} are automatically wrapped in reactive effects that perform surgical DOM updates.

React:    JSX → createElement() → Virtual DOM → Diff → DOM patches
SolidJS:  JSX → Compiled DOM creation → Direct DOM nodes + reactive effects

Control Flow Component Quick Reference

| Component | Import | Purpose | Key Props | |-----------|--------|---------|-----------| | <Show> | solid-js | Conditional rendering | when, fallback, keyed | | <For> | solid-js | List rendering (objects) | each, fallback | | <Index> | solid-js | List rendering (primitives) | each, fallback | | <Switch>/<Match> | solid-js | Multi-branch conditionals | fallback / when | | <Dynamic> | solid-js/web | Dynamic component/element | component | | <Portal> | solid-js/web | Render outside DOM tree | mount, useShadow, isSVG | | <Suspense> | solid-js | Async resource loading | fallback |

Namespaced Attribute Prefixes

| Prefix | Purpose | Example | |--------|---------|---------| | attr: | Force HTML attribute (vs property) | <div attr:data-id={id} /> | | prop: | Set DOM property directly | <input prop:value={val} /> | | class: | Toggle individual CSS class | <div class:active={isActive()} /> | | on: | Native event listener (non-delegated) | <div on:scroll={handler} /> | | use: | Custom directive | <div use:myDirective={value} /> | | bool: | Boolean HTML attribute | <div bool:disabled={isDisabled()} /> | | @once | One-time binding (no reactivity) | <div textContent={@once val} /> |

For vs Index Decision Table

| Scenario | Use | Why | |----------|-----|-----| | Array of objects, items reorder | <For> | Keyed by reference -- DOM nodes move with items | | Array of primitives (strings, numbers) | <Index> | Keyed by index -- values update in place | | Form inputs where position matters | <Index> | Stable index means stable DOM position | | List where items are added/removed/moved | <For> | Reference tracking avoids recreation |

Critical Warnings

NEVER use Array.map() to render lists -- it recreates ALL DOM nodes on every array change. ALWAYS use <For> or <Index>.

NEVER use ternary operators for complex conditional rendering -- they bypass SolidJS fine-grained reactivity optimizations. ALWAYS use <Show> with fallback.

NEVER use JavaScript switch/case statements in component bodies for conditional views -- the component body runs once so the switch evaluates once and never updates. ALWAYS use <Switch>/<Match>.

NEVER pass a key prop to list items -- SolidJS ignores the key prop entirely. <For> keys by object reference automatically.

NEVER use early returns in component bodies for conditional rendering -- the component runs once so the return is permanent. ALWAYS use <Show> or <Switch>/<Match>.

---

JSX Compilation Details

Static vs Dynamic Optimization

The SolidJS compiler separates static and dynamic content at build time:

// Static parts: template created once, cloned for each instance
// Dynamic parts: reactive effects update only the specific text node or attribute
const Counter = () => {
  const [count, setCount] = createSignal(0);
  return (
    <div class="counter">          {/* static -- compiled to template */}
      <span>Count: {count()}</span> {/* "Count: " static, {count()} dynamic */}
      <button onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
};

Attribute Declaration Order

SolidJS evaluates attributes in declaration order -- later definitions override earlier ones:

// value={currentValue} ALWAYS overrides any value in defaultProps
<input type="text" {...defaultProps} value={currentValue} />

Style Object Syntax

ALWAYS use double curly braces and kebab-case property names:

<button style={{ color: "red", "font-size": "2rem" }}>Click</button>

---

Show -- Conditional Rendering

Renders children when when is truthy, otherwise renders fallback:

import { Show } from "solid-js";

// Basic conditional with fallback:
<Show when={isLoggedIn()} fallback={<LoginForm />}>
  <Dashboard />
</Show>

// Render function -- receives narrowed non-null accessor:
<Show when={user()}>
  {(u) => <p>Welcome, {u().name}</p>}
</Show>

// Keyed -- re-renders when object reference changes:
<Show when={user()} keyed>
  <UserProfile user={user()} />
</Show>

Behavior: Without keyed, only truthiness changes trigger updates. With keyed, reference changes also trigger re-render.

---

For -- List Rendering (Objects)

Renders a list keyed by object reference. ALWAYS use for arrays of objects:

import { For } from "solid-js";

<For each={todos()} fallback={<p>No todos yet</p>}>
  {(todo, index) => (
    <div>
      <span>#{index() + 1}</span>  {/* index is a SIGNAL -- call it */}
      <span>{todo.text}</span>      {/* item is a direct VALUE */}
    </div>
  )}
</For>

Callback signature: (item: T, index: () => number) => JSX.Element

• item -- direct value (T), NOT a signal
• index -- signal, MUST call as index() to read

---

Index -- List Rendering (Primitives)

Renders a list keyed by array index. ALWAYS use for arrays of primitives:

import { Index } from "solid-js";

const [names, setNames] = createSignal(["Alice", "Bob", "Charlie"]);

<Index each={names()}>
  {(name, i) => (
    <input
      value={name()}     {/* item is a SIGNAL -- call it */}
      onInput={(e) => {
        setNames(prev => {
          const next = [...prev];
          next[i] = e.target.value;  {/* index is a plain NUMBER */}
          return next;
        });
      }}
    />
  )}
</Index>

Callback signature: (item: () => T, index: number) => JSX.Element

• item -- signal, MUST call as item() to read
• index -- direct number, NOT a signal

This is the OPPOSITE of <For>.

---

Switch/Match -- Multi-Branch Conditionals

Evaluates <Match> children sequentially -- first truthy when wins:

import { Switch, Match } from "solid-js";

<Switch fallback={<NotFound />}>
  <Match when={route() === "home"}><HomePage /></Match>
  <Match when={route() === "about"}><AboutPage /></Match>
  <Match when={route() === "settings"}><SettingsPage /></Match>
</Switch>

// With render function -- receives narrowed value:
<Switch>
  <Match when={user()}>
    {(u) => <UserProfile user={u()} />}
  </Match>
  <Match when={error()}>
    {(e) => <ErrorDisplay error={e()} />}
  </Match>
</Switch>

Behavior: Only ONE <Match> renders at a time (mutual exclusivity).

---

Dynamic -- Dynamic Component/Element Selection

import { Dynamic } from "solid-js/web";

// Dynamic component:
const [currentView, setCurrentView] = createSignal<Component>(HomeView);
<Dynamic component={currentView()} user={currentUser()} />

// Dynamic HTML element:
const [tag, setTag] = createSignal("h1");
<Dynamic component={tag()}>Hello World</Dynamic>

// Polymorphic "as" pattern:
function Box(props: { as?: string | Component; children: JSX.Element }) {
  const merged = mergeProps({ as: "div" }, props);
  return <Dynamic component={merged.as}>{props.children}</Dynamic>;
}

The component prop accepts SolidJS components, HTML tag strings, or JSX intrinsic element keys. All additional props are forwarded.

---

Portal -- Render Outside DOM Tree

import { Portal } from "solid-js/web";

<Portal mount={document.getElementById("modal-root")!}>
  <div class="modal-overlay">
    <div class="modal-content">Modal content here</div>
  </div>
</Portal>

Key behavior: Events propagate through the component tree, not the DOM tree. Client-side only -- hydration is disabled for portals.

---

Suspense -- Async Resource Loading

Tracks all createResource calls within its boundary:

import { Suspense } from "solid-js";

<Suspense fallback={<LoadingSpinner />}>
  <DataView data={dataResource()} />
</Suspense>

Key advantage over Show: <Show when={resource()}> destroys and recreates DOM. <Suspense> creates DOM nodes immediately but delays attachment -- preserving state and avoiding flicker.

Nested Suspense boundaries resolve independently:

<Suspense fallback={<HeaderSkeleton />}>
  <Header />
  <Suspense fallback={<ContentSkeleton />}>
    <Content />
  </Suspense>
</Suspense>

---

Common Anti-Patterns (Summary)

| React Pattern (WRONG) | SolidJS Pattern (CORRECT) | Why | |----------------------|--------------------------|-----| | {items.map(i => ...)} | <For each={items()}> | map recreates all DOM nodes | | {cond ? <A/> : <B/>} | <Show when={cond} fallback={<B/>}> | Show optimizes DOM mutations | | switch(x) { case: ... } | <Switch><Match when={...}> | Component body runs once | | <div key={id}> | No key needed | For keys by reference | | if (!data) return <Loading/> | <Show when={data} fallback={...}> | Early return is permanent |

---

Reference Links

• references/methods.md -- API signatures for Show, For, Index, Switch/Match, Dynamic, Portal, Suspense
• references/examples.md -- Control flow patterns, conditional rendering, list rendering, portals, suspense
• references/anti-patterns.md -- Array.map, ternary, switch/case, key prop -- all JSX anti-patterns

Official Sources

• https://docs.solidjs.com/concepts/understanding-jsx
• https://docs.solidjs.com/reference/components/show
• https://docs.solidjs.com/reference/components/for
• https://docs.solidjs.com/reference/components/index-component
• https://docs.solidjs.com/reference/components/switch-and-match
• https://docs.solidjs.com/reference/components/dynamic
• https://docs.solidjs.com/reference/components/portal
• https://docs.solidjs.com/reference/components/suspense