solid-syntax-components

name	solid-syntax-components
description	Use when creating components, handling props, working with children, refs, directives, or events in SolidJS. Prevents props destructuring and children access patterns from React that break SolidJS reactivity. Covers Component/ParentComponent/VoidComponent/FlowComponent types, splitProps, mergeProps, children() helper, ref patterns, use: directives, and event delegation. Keywords: splitProps, mergeProps, children, Component, ParentComponent, VoidComponent, FlowComponent, ref, use directive, SolidJS props, event handling.
license	MIT
compatibility	Designed for Claude Code. Requires SolidJS 1.x/2.x with TypeScript.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

solid-syntax-components

Quick Reference

Component Types

Type	Children	Use When
Component<P>	Optional (untyped)	General-purpose component
ParentComponent<P>	Required (children: JSX.Element)	Layout wrappers, containers
VoidComponent<P>	Forbidden	Icons, inputs, leaf nodes
FlowComponent<P, C>	Typed (children: C)	Control flow, render props

Props Handling

Need	Tool	Import
Access prop values	props.x directly	--
Derived values outside JSX	() => props.x	--
Separate prop groups	splitProps(props, [...keys])	solid-js
Default prop values	mergeProps(defaults, props)	solid-js
Spread remaining props	splitProps + {...rest}	solid-js

Children Resolution

Need	Tool	Import
Resolve and cache children	children(() => props.children)	solid-js
Iterate resolved children	resolved.toArray()	solid-js

Ref Patterns

Pattern	Syntax	When
Variable assignment	let ref!: HTMLElement	Standard ref
Callback	ref={(el) => { ... }}	Side effects on creation
Signal ref	const [ref, setRef] = createSignal<HTMLElement>()	Conditional elements
Forwarding	Pass ref as regular prop	Parent needs child DOM access

Event Systems

System	Syntax	Listener Location	Use When
Delegated	onClick={handler}	document (shared)	Common UI events (23 events)
Native	on:scroll={handler}	Element (direct)	Custom events, stopPropagation needed

Critical Warnings

NEVER destructure props in function parameters or body -- this severs reactivity. Props are reactive getters on a proxy object. ALWAYS access as props.x.

NEVER access props.children multiple times without the children() helper -- each access can re-create child elements. ALWAYS resolve with children(() => props.children).

NEVER use useRef or forwardRef -- these are React APIs. ALWAYS use let ref!: HTMLElement for refs and pass ref as a regular prop for forwarding.

NEVER use event.stopPropagation() with delegated events expecting it to prevent other delegated handlers -- delegated events share a single document listener. ALWAYS use on: prefix when propagation control is needed.

NEVER call a handler signal directly in an event attribute (onClick={handler()}) -- this evaluates once. ALWAYS wrap in an arrow function: onClick={() => handler()}.

---

Component Type Decision Tree

Creating a new component?
|
+-- Does it accept children?
|   |
|   +-- YES: Are children a specific type (render prop, typed slot)?
|   |   |
|   |   +-- YES --> FlowComponent<Props, ChildType>
|   |   +-- NO  --> ParentComponent<Props>
|   |
|   +-- NO: Will it NEVER have children?
|       |
|       +-- YES --> VoidComponent<Props>
|       +-- MAYBE --> Component<Props>

ALWAYS import types from solid-js:

import type { Component, ParentComponent, VoidComponent, FlowComponent } from "solid-js";

---

Props Handling

WRONG vs CORRECT: Destructuring

// WRONG -- breaks reactivity (frozen at initial value):
function Greeting({ name }: { name: string }) {
  return <h1>Hello {name}</h1>;
}

// WRONG -- same problem:
function Greeting(props: { name: string }) {
  const { name } = props;
  return <h1>Hello {name}</h1>;
}

// CORRECT -- reactive access:
const Greeting: Component<{ name: string }> = (props) => {
  return <h1>Hello {props.name}</h1>;
};

// CORRECT -- derived accessor for use outside JSX:
const Greeting: Component<{ name: string }> = (props) => {
  const upper = () => props.name.toUpperCase();
  return <h1>Hello {upper()}</h1>;
};

splitProps -- Reactive Prop Separation

import { splitProps } from "solid-js";

const Button: ParentComponent<ButtonProps> = (props) => {
  const [local, styleProps, rest] = splitProps(
    props,
    ["onClick", "disabled"],   // Group 1: behavior
    ["variant", "class"]       // Group 2: styling
  );                           // rest: everything else

  return (
    <button
      onClick={local.onClick}
      disabled={local.disabled}
      class={`btn-${styleProps.variant} ${styleProps.class}`}
      {...rest}
    >
      {props.children}
    </button>
  );
};

mergeProps -- Default Values

import { mergeProps } from "solid-js";

const Button: ParentComponent<ButtonProps> = (props) => {
  const merged = mergeProps(
    { variant: "primary", size: "md", disabled: false },
    props
  );
  // Later sources override earlier ones -- props overrides defaults
  return <button class={`btn-${merged.variant}`} disabled={merged.disabled}>{props.children}</button>;
};

---

Children

WRONG vs CORRECT

// WRONG -- accessing props.children multiple times re-creates elements:
const Bad: ParentComponent = (props) => {
  createEffect(() => { console.log(props.children); }); // Re-creates!
  return <div>{props.children}</div>;                    // Creates again!
};

// CORRECT -- resolve once with children() helper:
import { children } from "solid-js";
const Good: ParentComponent = (props) => {
  const resolved = children(() => props.children);
  createEffect(() => { console.log(resolved()); }); // Stable reference
  return <div>{resolved()}</div>;
};

Iterating Children

const List: ParentComponent = (props) => {
  const resolved = children(() => props.children);
  return (
    <ul>
      <For each={resolved.toArray()}>
        {(child) => <li>{child}</li>}
      </For>
    </ul>
  );
};

---

Refs

WRONG vs CORRECT: React useRef vs SolidJS ref

// WRONG (React pattern):
const ref = useRef<HTMLCanvasElement>(null);
useEffect(() => { ref.current?.getContext("2d"); }, []);
return <canvas ref={ref} />;

// CORRECT (SolidJS):
let canvasRef!: HTMLCanvasElement;
onMount(() => { canvasRef.getContext("2d"); });
return <canvas ref={canvasRef} />;

React vs SolidJS Ref Comparison

Aspect	React useRef	SolidJS ref
Declaration	const ref = useRef(null)	let ref!: HTMLElement
Access	ref.current	ref (direct)
Timing	After mount (useEffect)	Assigned during render, use in onMount
Hook required	Yes (useRef)	No -- plain variable
Forwarding	forwardRef() HOC	Pass ref as regular prop
Directives	No built-in system	use: prefix for reusable behaviors

Ref Forwarding

// Parent:
function Parent() {
  let childRef!: HTMLCanvasElement;
  onMount(() => { childRef.getContext("2d"); });
  return <ChildCanvas ref={childRef} />;
}

// Child -- ref is ALWAYS received as a callback, regardless of parent declaration:
const ChildCanvas: Component<{ ref: HTMLCanvasElement | ((el: HTMLCanvasElement) => void) }> = (props) => {
  return <canvas ref={props.ref} />;
};

---

Directives (use:)

Directive Signature

function directiveName(element: Element, accessor: () => any): void;

Example: clickOutside

import { onCleanup } from "solid-js";

function clickOutside(element: Element, accessor: () => () => void): void {
  const onClick = (e: Event) => {
    if (!element.contains(e.target as Node)) accessor()();
  };
  document.addEventListener("click", onClick);
  onCleanup(() => document.removeEventListener("click", onClick));
}

// TypeScript declaration (required to avoid errors):
declare module "solid-js" {
  namespace JSX {
    interface Directives {
      clickOutside: () => void;
    }
  }
}

// Usage:
<div use:clickOutside={() => setOpen(false)}>Dropdown content</div>

---

Event Handling

Delegated Events (23 Events)

beforeinput, click, dblclick, contextmenu, focusin, focusout, input, keydown, keyup, mousedown, mousemove, mouseout, mouseover, mouseup, pointerdown, pointermove, pointerout, pointerover, pointerup, touchend, touchmove, touchstart

For ALL other events, ALWAYS use the on: prefix.

Array Binding Syntax

const handler = (data: string, event: MouseEvent) => {
  console.log("Data:", data, "Target:", event.target);
};

// Avoids creating a new closure -- data is first arg, event is second:
<button onClick={[handler, "hello"]}>Click</button>

Event Delegation Caveats

1. stopPropagation: Delegated events share a document listener -- stopPropagation() does NOT prevent other delegated handlers. Use on:click when propagation control is needed.
2. Portals: Events propagate through the component tree, not the DOM tree.

---

Reference Links

• references/methods.md -- Component types, splitProps, mergeProps, children(), ref patterns, directives, event types
• references/examples.md -- Complete component patterns, props handling, children resolution, ref forwarding, directives, events
• references/anti-patterns.md -- Destructuring props, useRef, forwardRef, React children patterns, event handler mistakes

Official Sources

• https://docs.solidjs.com/concepts/components/basics
• https://docs.solidjs.com/concepts/components/props
• https://docs.solidjs.com/reference/component-apis/children
• https://docs.solidjs.com/concepts/refs
• https://docs.solidjs.com/concepts/components/event-handlers