# component
A minimal component system built on JavaScript and DOM primitives. Write components that render on the server, stream to the browser, and hydrate only where you need interactivity.
## Features
- **JSX Runtime** - Convenient JSX syntax
- **Component State** - State managed with plain JavaScript variables
- **Manual Updates** - Explicit control over when components update via `handle.update()`
- **Real DOM Events** - Events are real DOM events using the `on()` mixin and `addEventListeners()`
- **Inline CSS** - `css(...)` mixin with pseudo-selectors and nested rules
- **Server Rendering** - Stream full pages or fragments with `renderToStream`
- **Hydration** - Mark interactive components with `clientEntry` and hydrate them on the client with `run`
- **Frames** - `` streams partial server UI into the page and can be reloaded without a full page navigation
## Installation
```sh
npm i remix
```
## Quick Start
### Server
Render a full page to a streaming response:
```tsx
import { renderToStream } from 'remix/component/server'
import { Frame } from 'remix/component'
import { Counter } from './assets/counter.tsx'
function App() {
return () => (
My App
Hello
Loading...} />
)
}
let stream = renderToStream(, {
resolveFrame(src, target, context) {
let headers = new Headers({ accept: 'text/html' })
if (target) headers.set('x-remix-target', target)
return fetch(new URL(src, context?.currentFrameSrc ?? request.url), { headers }).then((res) =>
res.text(),
)
},
})
return new Response(stream, {
headers: { 'Content-Type': 'text/html' },
})
```
### Client Entry
Mark components that need client-side interactivity with `clientEntry`. They render on the server and hydrate on the client:
```tsx
import { clientEntry, on, type Handle } from 'remix/component'
export let Counter = clientEntry(
'/assets/counter.js#Counter',
function Counter(handle: Handle, setup: number) {
let count = setup
return (props: { label: string }) => (
{props.label}: {count}
)
},
)
```
The first argument is the module URL and export name the client will use to load this component. The component renders on the server like any other component, and the client hydrates it in place, preserving the server-rendered HTML.
### Client
Boot the client with `run`. It finds all client entries in the page, loads their modules, and hydrates them:
```tsx
import { run } from 'remix/component'
let app = run({
async loadModule(moduleUrl, exportName) {
let mod = await import(moduleUrl)
return mod[exportName]
},
async resolveFrame(src, signal, target) {
let headers = new Headers({ accept: 'text/html' })
if (target) headers.set('x-remix-target', target)
let res = await fetch(src, { headers, signal })
return res.body ?? (await res.text())
},
})
await app.ready()
```
### Frames
`` renders server content into the page. Frames can stream in after the initial HTML, nest other frames, and contain client entries. They can be reloaded from the client without a full page navigation:
```tsx
Loading sidebar...} />
```
Client entries inside a frame can trigger a reload:
```tsx
function RefreshButton(handle: Handle) {
return () => (
)
}
```
When a frame reloads, its server HTML is re-fetched and diffed into the page. Client entries inside the frame receive updated props from the server while preserving their local state.
You can also name frames and reload adjacent ones:
```tsx
```
```tsx
function CartRow(handle: Handle) {
return () => (
)
}
```
When a frame reloads, its server HTML is re-fetched and diffed into the page. Client entries inside the frame receive updated props from the server while preserving their local state.
## Components
All components return a render function. The setup function runs **once** when the component is first created, and the returned render function runs on the first render and **every update** afterward:
```tsx
function Counter(handle: Handle, setup: number) {
// Setup phase: runs once
let count = setup
// Return render function: runs on every update
return (props: { label?: string }) => (
{props.label || 'Count'}: {count}
)
}
```
### Setup Prop vs Props
When a component returns a function, it has two phases:
1. **Setup phase** - The component function receives the `setup` prop and runs once. Use this for initialization.
2. **Render phase** - The returned function receives props and runs on initial render and every update afterward. Use this for rendering.
The `setup` prop is separate from regular props. Only the `setup` prop is passed to the setup function, and only props are passed to the render function.
- `setup` prop for values that initialize state (e.g., `initial`, `defaultValue`)
- Regular props for values that change over time (e.g., `label`, `disabled`)
```tsx
// Usage: setup prop goes to setup function, regular props go to render function
let el =
function Counter(
handle: Handle,
setup: number, // receives 5 (the setup prop value)
) {
let count = setup // use setup for initialization
return (props: { label?: string }) => {
// props only receives { label: "Total" } - not the setup prop
return (
{props.label}: {count}
)
}
}
```
## Events
Events use the `on()` mixin. Listeners receive an `AbortSignal` that's aborted when the component is disconnected or the handler is re-entered.
```tsx
function SearchInput(handle: Handle) {
let query = ''
return () => (
{
query = event.currentTarget.value
handle.update()
// Pass the signal to abort the fetch on re-entry or node removal
// This avoids race conditions in the UI and manages cleanup
fetch(`/search?q=${query}`, { signal })
.then((res) => res.json())
.then((results) => {
if (signal.aborted) return
// Update results
})
}),
]}
/>
)
}
```
You can also listen to global event targets like `document` or `window` using `addEventListeners()` with automatic cleanup on component removal:
```tsx
function KeyboardTracker(handle: Handle) {
let keys: string[] = []
addEventListeners(document, handle.signal, {
keydown: (event) => {
keys.push(event.key)
handle.update()
},
})
return () =>
Keys: {keys.join(', ')}
}
```
## CSS Mixin
Use the `css(...)` mixin for inline styles with pseudo-selectors and nested rules:
```tsx
function Button(handle: Handle) {
return () => (
)
}
```
The syntax mirrors modern CSS nesting, but in object form. Use `&` to reference the current element in pseudo-selectors, pseudo-elements, and attribute selectors. Use class names or other selectors directly for child selectors:
```css
.button {
color: white;
background-color: blue;
&:hover {
background-color: darkblue;
}
&::before {
content: '';
position: absolute;
}
&[aria-selected='true'] {
border: 2px solid yellow;
}
.icon {
width: 16px;
height: 16px;
}
@media (max-width: 768px) {
padding: 8px;
}
}
```
```tsx
function Button(handle: Handle) {
return () => (
)
}
```
## Ref Mixin
Use the `ref(...)` mixin to get a reference to the DOM node after it's rendered. This is useful for DOM operations like focusing elements, scrolling, or measuring dimensions.
```tsx
function Form(handle: Handle) {
let inputRef: HTMLInputElement
return () => (
)
}
```
The `ref` callback receives an `AbortSignal` as its second parameter, which is aborted when the element is removed from the DOM:
```tsx
function Component(handle: Handle) {
return () => (
{
// Set up something that needs cleanup
let observer = new ResizeObserver(() => {
// handle resize
})
observer.observe(node)
// Clean up when element is removed
signal.addEventListener('abort', () => {
observer.disconnect()
})
}),
]}
>
Content
)
}
```
## Component Handle API
Components receive a `Handle` as their first argument with the following API:
- **`handle.update()`** - Schedule an update and await completion to get an `AbortSignal`.
- **`handle.queueTask(task)`** - Schedule a task to run after the next update. Useful for DOM operations that need to happen after rendering (e.g., moving focus, scrolling, measuring elements, etc.).
- **`addEventListeners(target, handle.signal, listeners)`** - Listen to an event target with automatic cleanup when the component disconnects.
- **`handle.signal`** - An `AbortSignal` that's aborted when the component is disconnected. Useful for cleanup.
- **`handle.id`** - Stable identifier per component instance.
- **`handle.context`** - Context API for ancestor/descendant communication.
- **`handle.frame`** - The component's closest frame. Call `handle.frame.reload()` to refresh the frame's server content.
- **`handle.frames.get(name)`** - Look up named frames in the current runtime tree for adjacent frame reloads.
### `handle.update()`
Schedule an update and optionally await completion to coordinate post-update work.
```tsx
function Counter(handle: Handle) {
let count = 0
return () => (
)
}
```
You can await the update before doing DOM work:
```tsx
function Player(handle: Handle) {
let isPlaying = false
let playButton: HTMLButtonElement
let stopButton: HTMLButtonElement
return () => (
)
}
```
### `handle.queueTask(task)`
Schedule a task to run after the next update. Useful for DOM operations that need to happen after rendering (e.g., moving focus, scrolling, measuring elements).
```tsx
function Form(handle: Handle) {
let showDetails = false
let detailsSection: HTMLElement
return () => (
)
}
```
### `addEventListeners(target, handle.signal, listeners)`
Listen to an [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) with automatic cleanup when the component disconnects. Ideal for listening to events on global event targets like `document` and `window`.
```tsx
function KeyboardTracker(handle: Handle) {
let keys: string[] = []
addEventListeners(document, handle.signal, {
keydown: (event) => {
keys.push(event.key)
handle.update()
},
})
return () =>
Keys: {keys.join(', ')}
}
```
The listeners are automatically removed when the component is disconnected, so you don't need to manually clean up.
### `handle.signal`
An `AbortSignal` that's aborted when the component is disconnected. Useful for cleanup operations.
```tsx
function Clock(handle: Handle) {
let interval = setInterval(() => {
// clear the interval when the component is disconnected
if (handle.signal.aborted) {
clearInterval(interval)
return
}
handle.update()
}, 1000)
return () => {new Date().toString()}
}
```
### `handle.id`
Stable identifier per component instance. Useful for HTML APIs like `htmlFor`, `aria-owns`, etc. so consumers don't have to supply an id.
```tsx
function LabeledInput(handle: Handle) {
return () => (
)
}
```
### `handle.context`
Context API for ancestor/descendant communication. All components are potential context providers and consumers. Use `handle.context.set()` to provide values and `handle.context.get()` to consume them.
```tsx
function App(handle: Handle<{ theme: string }>) {
handle.context.set({ theme: 'dark' })
return () => (
)
}
function Header(handle: Handle) {
// Consume context from App
let { theme } = handle.context.get(App)
return () => (
Header
)
}
```
Setting context values does not automatically trigger updates. If a provider needs to render its own context values, call `handle.update()` after setting them. However, since providers often don't render context values themselves, calling `update()` can cause expensive updates of the entire subtree. Instead, make your context an [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) and have consumers subscribe to changes.
```tsx
import { TypedEventTarget } from 'remix/component'
class Theme extends TypedEventTarget<{ change: Event }> {
#value: 'light' | 'dark' = 'light'
get value() {
return this.#value
}
setValue(value: string) {
this.#value = value
this.dispatchEvent(new Event('change'))
}
}
function App(handle: Handle) {
let theme = new Theme()
handle.context.set(theme)
return () => (
)
}
function ThemedContent(handle: Handle) {
let theme = handle.context.get(App)
// Subscribe to theme changes and update when it changes
addEventListeners(theme, handle.signal, { change: () => handle.update() })
return () => (
Current theme: {theme.value}
)
}
```
## Fragments
Use `Fragment` to group elements without adding extra DOM nodes:
```tsx
function List(handle: Handle) {
return () => (
<>