Package @reatom/jsx

JSX

Features

⚡️ Zero re-renders: reactive bindings update DOM directly
🧩 Native elements: <div /> returns a real DOM node
🛠 No extra build step: just TSX and TypeScript support
🎯 Tiny footprint: ~3KB runtime (plus a minimal core)
🎨 Built-in styles: efficient via CSS variables

Installation

npm install @reatom/core @reatom/jsx

Set up TypeScript to use the JSX runtime:

tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "jsx": "preserve",
    "jsxImportSource": "@reatom/jsx"
  }
}

For Vite users:

vite.config.js:

import { defineConfig } from 'vite'

export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'hf',
    jsxInject: `import { h, hf } from "@reatom/jsx"`,
  },
})

Framework compatibility

You can integrate @reatom/jsx into existing React or other JSX projects.

Create a separate package for Reatom-based components
Extend(https://www.typescriptlang.org/tsconfig#extends) your base tsconfig.json with JSX config
In each file, declare JSX pragma manually:

// @jsxRuntime classic
// @jsx h
import { h } from '@reatom/jsx'

This enables you to gradually migrate or optimize parts of your app without conflict with existing tooling.

Example

💡 See a more advanced version with dynamic entities: https://github.com/reatom/reatom/tree/v1000/examples/reatom-jsx

Define a component:

import { atom } from '@reatom/core'

const value = atom('')
// Event handlers shouldn't be wrapped, Reatom take care of it
const onInput = (event: Event & { currentTarget: HTMLInputElement }) =>
  value.set(event.currentTarget.value)

const Input = () => <input value={value} on:input={onInput} />

Mount your app:

import { connectLogger, context, clearStack } from '@reatom/core'
import { mount } from '@reatom/jsx'
import { App } from './App'

// Disable default global context to enforce explicit context usage (recommended)
clearStack()

// Create a root context for the application
const rootContext = context.start()

if (import.meta.env.MODE === 'development') {
  connectLogger()
}

// Mount the app within the created context
mount(document.getElementById('app')!, <App />)

Reference

This package implements a JSX factory that creates and binds native DOM elements with reactivity.

Props

JSX props are treated as follows:

Default: set as DOM properties or attributes are used depending on the context, to ensure correct behavior and predictable outcomes.
prop:*: sets DOM properties.
attr:*: sets DOM attributes.
on:*: register event listeners. Functions interacting with Reatom state or actions are wrapped (wrap) automatically.

All values can be:

null or undefined: removes DOM attribute or resets DOM property
string, number or boolean: sets property or attribute
AtomLike or a derived function: tracked reactively, the prop is automatically updated when dependencies change

const enabled = atom(true)
const value = atom('')
<input
  value={value}
  attr:type="text"
  prop:disabled={() => !enabled()}
  on:input={(event) => value.set(event.currentTarget.value)}
/>

Children

The children prop defines element content. It supports:

boolean, null, or undefined → renders nothing
string or number → renders text
Node → inserts DOM node as-is
AtomLike → reactive content

<div>{count}</div>

Models

Use model:* props for two-way binding with native input controls.

Supported props:

model:value: binds the value property of inputs, useful for text inputs and <textarea>
model:valueAsNumber: binds the valueAsNumber property, typically used for numeric inputs
model:checked: binds the checked property of checkboxes or radio buttons

const value = atom('')
const Input = () => <input model:value={value} />

Components run once on creation, so it’s safe to define atoms or any setup logic inside:

const Input = () => {
  const value = atom('')
  return <input model:value={value} />
}

`style` props

Use style={{ key: value }} for inline styles. Falsy values like false, null, and undefined remove the style.

<div style={{ top: 0, display: hidden() && 'none' }} />

Avoid replacing the full style object — prefer updates via static keys:

❌ Avoid:

<div style={() => (flag() ? { top: 0 } : { bottom: 0 })} />

✅ Use:

<div
  style={() =>
    flag() ? { top: 0, bottom: undefined } : { top: undefined, bottom: 0 }
  }
/>

`style:*` props

Set individual styles via style:*:

// <div style="top: 10px; right: 0;"></div>
<div
  style:top={atom('10px')}
  style:right={0}
  style:bottom={undefined}
  style:left={null}
></div>

Values can be primitives or reactive (atom, () => string, etc.). Numbers are passed as-is (no automatic px).

`class` or `className` props

The JSX runtime automatically applies the same logic internally using reatomClassName.

/** @example <button class="button button--size-medium button--theme-primary button--is-active"></button> */
<button class={[
  'button',
  `button--size-${props.size}`,
  `button--theme-${props.theme}`,
  {
    'button--is-disabled': props.isDisabled,
    'button--is-active': props.isActive() && !props.isDisabled(),
  },
]}></button>

CSS-in-JS

The css prop provides an ideal architectural balance for styling: it keeps styles colocated with the markup they affect while avoiding the coupling issues of other approaches.

Use the css prop to declare styles via tagged template literals. Dynamic values can be passed as CSS variables via css:*.

const Component = () => (<input
  css:size={size}
  css="font-size: calc(1em + var(--size) * 0.1em);"
></div>)

This will be compiled to:

<div data-reatom-style="1" data-reatom-name="Component" style="--size: 3"></div>

Behind the scenes, the runtime:

Generates a unique style ID and sets it as data-reatom-style attribute
Inserts the CSS rule once using attribute selector ([data-reatom-style="1"])
Applies dynamic values as inline CSS variables (--size)
Sets data-reatom-name attribute with the component name for better DevTools traceability

Why css-prop?

Every styling approach forces trade-offs. CSS-modules and SFC style tags split your component across files. Tailwind requires learning a new vocabulary and clutters your markup. Styled-components and Linaria add runtime overhead or complex build pipelines.

The css prop takes a different path: just write CSS where you use it. No preprocessing, no new syntax to learn — Reatom passes your styles directly to the DOM. You still get native CSS nesting, readable component names in DevTools via data-reatom-name attribute, and zero build complexity.

But the real win is architectural. When styles live inline, growing components naturally want to be extracted as new components — not split into separate style files. This keeps markup and styles together, maintaining high cohesion and low coupling. The path of least resistance leads to better code organization.

Tip: wrapping logic in components improves data-reatom-name readability and traceability.

Prettier formats css template literals correctly, and the vscode-styled-components extension provides syntax highlighting.

CSS Mixins

Since styles are just strings, you can build your own design system with plain JavaScript — no framework magic required.

Mix utilities with custom CSS when needed:

<div
  css={`
    ${card}
    max-width: 400px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  `}
/>

Use them directly — no template literals needed for simple cases:

<main css={center}>
  <article css={card}>
    <h1 css={text(colors.text)}>Hello</h1>
    <button css={bg(colors.primary) + px(4) + py(2) + rounded}>Click me</button>
  </article>
</main>

Your design tokens and utilities:

// Tokens
export const colors = {
  primary: '#3b82f6',
  surface: '#f8fafc',
  text: '#1e293b',
}
export const space = [0, 4, 8, 16, 24, 32, 48] as const
export type Size = 0 | 1 | 2 | 3 | 4 | 5 | 6

// Utilities — just strings and functions
export const flex = 'display: flex;'
export const flexCenter = 'justify-content: center; align-items: center;'
export const rounded = 'border-radius: 8px;'

export const p = (n: Size) => `padding: ${space[n]}px;`
export const px = (n: Size) => `padding-inline: ${space[n]}px;`
export const py = (n: Size) => `padding-block: ${space[n]}px;`
export const bg = (color: string) => `background: ${color};`
export const text = (color: string) => `color: ${color};`

export const card = bg(colors.surface) + rounded + p(4)
export const center = flex + flexCenter

This gives you the composability of utility-first CSS with full CSS power — all type-safe, all just JavaScript.

Conditional Styles with Attributes

We have built-in class names parsing and a reactive helper reatomClassName. But often it’s simpler and more effective to use native attributes for conditional styles — the attribute becomes both the state indicator and the CSS selector target.

const Accordion = ({ title, children }) => {
  const open = atom(false)

  return (
    <details
      open={open}
      css={`
        article {
          display: grid;
          grid-template-rows: 0fr;
          transition: grid-template-rows 0.2s;
        }
        &[open] article {
          grid-template-rows: 1fr;
        }
      `}
    >
      <summary on:click={open.toggle}>{title}</summary>
      <article>
        <div css="overflow: hidden;">{children}</div>
      </article>
    </details>
  )
}

Works with ARIA and standard attributes — accessible and styleable in one:

<nav aria-busy={loading} css="&[aria-busy] { opacity: 0.5; }">
  {/* shows loading state to screen readers AND applies style */}
</nav>

<button disabled={submitting} css="&[disabled] { cursor: wait; }">
  {/* native disabled behavior AND custom style */}
</button>

Why this pattern works best:

Single source of truth — attribute is both the reactive binding and style condition
Accessible by default — ARIA attributes communicate state to assistive technologies
Inspectable — attributes are visible in DevTools, debugging is trivial
Testable — query by semantic selectors ([aria-current], [disabled]) instead of class names

Components

Components are plain functions that return DOM elements. They are stateless, have no lifecycle, and are evaluated only once — at the moment of mounting.

There’s no virtual tree or diffing — everything happens directly in the DOM.

Use dynamic atoms for reactive lists:

const list = atom([
  <li>1</li>,
  <li>2</li>,
])

const add = () => list.set((state) => [
  ...state,
  <li>{state.length + 1}</li>,
])

<div>
  <button on:click={add}>Add</button>
  {computed(() => <ul>{list().map((item) => item)}</ul>)}
</div>

⚠ Do not reuse elements

JSX elements are real DOM nodes, not virtual descriptions. Reusing the same element instance multiple times leads to incorrect rendering — it will only appear in the last place it was inserted. Each JSX element must be created fresh where it’s used.

❌ Incorrect

const shared = <span>{valueAtom}</span>

<>
  <div>{shared}</div>
  <p>{shared}</p>
</>

Result:

<div></div>
<p>
  <span>text</span>
</p>

Only the last usage is rendered — the first one is silently dropped.

✅ Correct

const Shared = () => <span>{valueAtom}</span>

<>
  <div><Shared /></div>
  <p><Shared /></p>
</>

Result:

<div><span>Hello</span></div>
<p><span>Hello</span></p>

Each call creates a unique element with its own lifecycle and subscriptions.

`$spread` prop

Use $spread to declaratively bind multiple props or attributes at once. The object can be reactive (e.g., atom, () => obj) and will update automatically.

<div
  $spread={computed(() =>
    valid()
      ? { disabled: true, readonly: true }
      : { disabled: false, readonly: false },
  )}
/>

Always include all relevant keys on each update to avoid stale DOM state.

SVG

To create SVG elements, use the svg: namespace prefix to the tag name.

<svg:svg viewBox="0 0 24 24">
  <svg:path d="..." />
</svg:svg>

SVG elements are rendered as native DOM nodes in the SVG namespace.

If you need to inject raw SVG markup, use one of the following approaches:

Option 1: parse from string

const SvgIcon = ({ svg }: { svg: string }) =>
  new DOMParser()
    .parseFromString(svg, 'image/svg+xml')
    .children.item(0) as SVGElement

Option 2: use prop:outerHTML

const SvgIcon = ({ svg }: { svg: string }) => <svg:svg prop:outerHTML={svg} />

`ref` props

Use the ref prop to get access to the DOM element and register mount/unmount side effects.

<button
  ref={(el) => {
    el.focus()
    return (el) => el.blur()
  }}
/>

Unmount callbacks are called automatically in reverse order — from child to parent:

<div
  ref={() => {
    console.log('mount parent')
    return () => console.log('unmount parent')
  }}
>
  <span
    ref={() => {
      console.log('mount child')
      return () => console.log('unmount child')
    }}
  />
</div>

Console output:

mount child
mount parent
unmount child
unmount parent

Utilities

`reatomClassName` class names reactivity

reatomClassName works similarly to clsx or classnames, but with full reactivity support — you can pass strings, arrays, objects, functions, and atoms. All values are automatically converted into a class string that updates when dependencies change.

Strings are added directly.
Arrays are flattened and processed recursively.
Objects add a key as a class if its value is truthy.
Functions and atoms are tracked reactively and automatically recomputed on changes.

reatomClassName('my-class') // Computed<'my-class'>

reatomClassName(['first', atom('second')]) // Computed<'first second'>

/**
 * The `active` class will be determined by the truthiness of the data property
 * `isActiveAtom`.
 */
reatomClassName({ active: isActiveAtom }) // Computed<'active' | ''>

reatomClassName(() => (isActiveAtom() ? 'active' : undefined)) // Computed<'active' | ''>

The reatomClassName function supports various complex data combinations, making it easier to declaratively describe classes for complex UI components.

/**
 * @example
 *   Computed<'button button--size-medium button--theme-primary button--is-active'>
 */
reatomClassName([
  'button',
  `button--size-${props.size}`,
  `button--theme-${props.theme}`,
  {
    'button--is-disabled': props.isDisabled,
    'button--is-active': props.isActive() && !props.isDisabled(),
  },
])

`css` template literal

You can import css function from @reatom/jsx to describe separate css-in-js styles with syntax highlight and Prettier support. Also, this function skips all falsy values, except 0.

import { css } from '@reatom/jsx'

const styles = css`
  color: red;
  background: blue;
  ${somePredicate && 'border: 0;'}
`

You can use this with the css or style props.

`<Bind>` component

You can use <Bind> component to use all @reatom/jsx features on top of existed element. For example, there are some library, which creates an element and returns it to you and you want to add some reactive properties to it.

import { Bind } from '@reatom/jsx'

const MyComponent = () => {
  const container = new SomeLibrary()

  return (
    <Bind
      element={container}
      class={computed(() => (visible() ? 'active' : 'disabled'))}
    />
  )
}

TypeScript

JSX components in @reatom/jsx are plain functions and integrate seamlessly with TypeScript.

Typing component props

If you want to define props for a specific HTML element you should use it name in the type name, like in the code below.

import { type JSX } from '@reatom/jsx'

// allow only plain data types
interface InputProps extends JSX.InputHTMLAttributes {
  defaultValue?: string
}
// allow plain data types and atoms
type InputProps = JSX.IntrinsicElements['input'] & {
  defaultValue?: string
}

const Input = ({ defaultValue, ...props }: InputProps) => {
  props.value ??= defaultValue
  return <input {...props} />
}

Use JSX.IntrinsicElements['tagName'] to get the correct typing for a given element (input, button, div, etc).

Typing event handlers

You can annotate event handlers explicitly with built-in types.

const Form = () => {
  const handleSubmit = (event: Event) => {
    event.preventDefault()
  }

  const handleInput = (event: JSX.InputEvent) => {
    const value: number = event.currentTarget.valueAsNumber
    // e.g. valueAtom.set(value)
  }

  const handleSelect = (event: JSX.TargetedEvent<HTMLSelectElement>) => {
    const value: string = event.currentTarget.value
    // e.g. selectAtom.set(value)
  }

  return (
    <form on:submit={handleSubmit}>
      <input on:input={handleInput} />
      <select on:input={handleSelect} />
    </form>
  )
}

Extending JSX typings

You may have custom elements that you’d like to use in JSX, or you may wish to add additional attributes to all HTML elements to work with a particular library. To do this, you will need to extend the IntrinsicElements or HTMLAttributes interfaces, respectively, so that TypeScript is aware and can provide correct type information.

Add new intrinsic elements

function MyComponent() {
  return <loading-bar showing />
  //       ~~~~~~~~~~~
  //    💥 Property 'loading-bar' does not exist...
}

To fix:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'loading-bar': { showing?: boolean | null | undefined }
    }
  }
}

// This empty export is important! It tells TS to treat this as a module
export {}

Add custom HTML attributes

function MyComponent() {
  return <div custom="value" />
  //        ~~~~~~
  //     💥 Property 'custom' does not exist...
}

To fix:

declare global {
  namespace JSX {
    interface HTMLAttributes {
      custom?: string | null | undefined
    }
  }
}

// This empty export is important! It tells TS to treat this as a module
export {}

Don’t forget the export {} at the bottom — it makes the file a module so TypeScript merges types correctly.

Limitations

These features are not yet supported:

❌ DOM-less SSR (you need a DOM-like environment such as linkedom)
❌ Keyed lists (use linked lists instead)

Type Aliases

FC()

FC<Props> = (props) => JSXElement

Defined in: index.ts:31

Type Parameters

Props

Props = { }

Parameters

props

Props & object

Returns

JSXElement

JSXElement

JSXElement = JSX.Element

Defined in: index.ts:29

Variables

DEBUG

DEBUG: Atom<boolean, [boolean]>

Defined in: index.ts:52

DOM

DOM: Atom<Window & typeof globalThis, [Window & typeof globalThis]>

Defined in: index.ts:50

stylesheet

stylesheet: Atom<CSSStyleSheet, [CSSStyleSheet]>

Defined in: index.ts:62

Note

Create style tag for support oldest browser.

See

Functions

Bind()

Bind<T>(props): T

Defined in: index.ts:646

Type Parameters

T

T extends Element

Parameters

props

object & AttributesAtomMaybe<Partial<Omit<T, "children">> & DOMAttributes<T>>

Returns

T

css()

css(strings, …values): string

Defined in: index.ts:638

This simple utility needed only for syntax highlighting and it just concatenates all passed strings. Falsy values are ignored, except for 0.

Parameters

strings

TemplateStringsArray

values

…any[]

Returns

string

h()

h(tag, props, …children): Element

Defined in: index.ts:520

Parameters

tag

any

props

Rec

children

…any[]

Returns

Element

hf()

hf(): void

Defined in: index.ts:580

Fragment.

Returns

void

Todo

Describe a function as a component.

mount()

mount(target, child): void

Defined in: index.ts:582

Parameters

target

Element

child

Element

Returns

void

reatomClassName()

reatomClassName(value, name): Computed<string>

Defined in: utils.ts:7

Parameters

value

ClassNameValue

name

string = ...

Returns

Computed<string>

Package @reatom/jsx

JSX

Features

Installation

Framework compatibility

Example

Reference

Props

Children

Models

style props

style:* props

class or className props

CSS-in-JS

Why css-prop?

CSS Mixins

Conditional Styles with Attributes

Components

⚠ Do not reuse elements

$spread prop

SVG

ref props

Utilities

reatomClassName class names reactivity

css template literal

<Bind> component

TypeScript

Typing component props

Typing event handlers

Extending JSX typings

Add new intrinsic elements

Add custom HTML attributes

Limitations

Type Aliases

FC()

Type Parameters

Props

Parameters

props

Returns

JSXElement

Variables

DEBUG

DOM

stylesheet

Note

See

Functions

Bind()

Type Parameters

T

Parameters

props

Returns

css()

Parameters

strings

values

Returns

h()

Parameters

tag

props

children

Returns

hf()

Returns

Todo

mount()

Parameters

target

child

Returns

reatomClassName()

Parameters

value

name

Returns

`style` props

`style:*` props

`class` or `className` props

`$spread` prop

`ref` props

`reatomClassName` class names reactivity

`css` template literal

`<Bind>` component