` | | `prop:` | Set DOM property directly | `` | | `class:` | Toggle individual CSS class | `

` | | `on:` | Native event listener (non-delegated) | `

` | | `use:` | Custom directive | `

` | | `bool:` | Boolean HTML attribute | `

` | | `@once` | One-time binding (no reactivity) | `

` | ### For vs Index Decision Table | Scenario | Use | Why | |----------|-----|-----| | Array of objects, items reorder | `` | Keyed by reference -- DOM nodes move with items | | Array of primitives (strings, numbers) | `` | Keyed by index -- values update in place | | Form inputs where position matters | `` | Stable index means stable DOM position | | List where items are added/removed/moved | `` | Reference tracking avoids recreation | ### Critical Warnings **NEVER** use `Array.map()` to render lists -- it recreates ALL DOM nodes on every array change. ALWAYS use `` or ``. **NEVER** use ternary operators for complex conditional rendering -- they bypass SolidJS fine-grained reactivity optimizations. ALWAYS use `` 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 ``/``. **NEVER** pass a `key` prop to list items -- SolidJS ignores the `key` prop entirely. `` 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 `` or `/`. --- ## JSX Compilation Details ### Static vs Dynamic Optimization The SolidJS compiler separates static and dynamic content at build time: ```typescript // 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 (

{/* static -- compiled to template */} Count: {count()} {/* "Count: " static, {count()} dynamic */}

); }; ``` ### Attribute Declaration Order SolidJS evaluates attributes in **declaration order** -- later definitions override earlier ones: ```typescript // value={currentValue} ALWAYS overrides any value in defaultProps ``` ### Style Object Syntax ALWAYS use double curly braces and kebab-case property names: ```typescript ``` --- ## Show -- Conditional Rendering Renders children when `when` is truthy, otherwise renders `fallback`: ```typescript import { Show } from "solid-js"; // Basic conditional with fallback: }> // Render function -- receives narrowed non-null accessor: {(u) =>

Welcome, {u().name}

} // Keyed -- re-renders when object reference changes: ``` **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: ```typescript import { For } from "solid-js"; No todos yet

}> {(todo, index) => (

#{index() + 1} {/* index is a SIGNAL -- call it */} {todo.text} {/* item is a direct VALUE */}

)} ``` **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: ```typescript import { Index } from "solid-js"; const [names, setNames] = createSignal(["Alice", "Bob", "Charlie"]); {(name, i) => ( { setNames(prev => { const next = [...prev]; next[i] = e.target.value; {/* index is a plain NUMBER */} return next; }); }} /> )} ``` **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 ``.** --- ## Switch/Match -- Multi-Branch Conditionals Evaluates `` children sequentially -- first truthy `when` wins: ```typescript import { Switch, Match } from "solid-js"; }> // With render function -- receives narrowed value: {(u) => } {(e) => } ``` **Behavior**: Only ONE `` renders at a time (mutual exclusivity). --- ## Dynamic -- Dynamic Component/Element Selection ```typescript import { Dynamic } from "solid-js/web"; // Dynamic component: const [currentView, setCurrentView] = createSignal(HomeView); // Dynamic HTML element: const [tag, setTag] = createSignal("h1"); Hello World // Polymorphic "as" pattern: function Box(props: { as?: string | Component; children: JSX.Element }) { const merged = mergeProps({ as: "div" }, props); return {props.children}; } ``` The `component` prop accepts SolidJS components, HTML tag strings, or JSX intrinsic element keys. All additional props are forwarded. --- ## Portal -- Render Outside DOM Tree ```typescript import { Portal } from "solid-js/web"; ``` **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: ```typescript import { Suspense } from "solid-js"; }> ``` **Key advantage over Show**: `` destroys and recreates DOM. `` creates DOM nodes immediately but delays attachment -- preserving state and avoiding flicker. **Nested Suspense** boundaries resolve independently: ```typescript }>

}> ``` --- ## Common Anti-Patterns (Summary) | React Pattern (WRONG) | SolidJS Pattern (CORRECT) | Why | |----------------------|--------------------------|-----| | `{items.map(i => ...)}` | `` | map recreates all DOM nodes | | `{cond ? : }` | `}>` | Show optimizes DOM mutations | | `switch(x) { case: ... }` | `` | Component body runs once | | `
` | No key needed | For keys by reference | | `if (!data) return ` | `` | Early return is permanent | --- ## Reference Links - [references/methods.md](references/methods.md) -- API signatures for Show, For, Index, Switch/Match, Dynamic, Portal, Suspense - [references/examples.md](references/examples.md) -- Control flow patterns, conditional rendering, list rendering, portals, suspense - [references/anti-patterns.md](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