Refs and the DOM

Most of the time you never touch a DOM node. You describe the page in TSX, and the compiler wires every {value} to the exact text node or attribute that shows it. But some things the browser only lets you do on an element: move focus to it, scroll it into view, measure it, or hand it to a library that draws into it. For those you need the element itself, and ref is how you ask for it.

Getting an element with ref

Put ref on any element and give it a variable. When weft makes the element, it assigns it:

import { Button } from '@weft-js/warp'export function Focus() {  // oxlint-disable-next-line no-unassigned-vars -- the compiler assigns it through ref  let field!: HTMLInputElement  return (    <form>      <input ref={field} aria-label="Your name" />      <Button onClick={() => field.focus()}>Focus the field</Button>    </form>  )}

Three things make this work:

1. let, not const. The compiler turns ref={field} into an assignment, field = theInput, so the variable must be assignable. With a const it calls the value as a function instead (next section).
2. ! after the name tells TypeScript the variable will hold an element before you use it. Without it, TypeScript says field is used before it's assigned, because it can't see the compiler's assignment either.
3. The comment above it. Linters with the no-unassigned-vars rule (oxlint, and ESLint 9) flag a variable that is declared and read but never written. The write is in the compiled output, so the rule can't see it. Turn it off for that one line and say why, as above.

If you'd rather not have the ! and the comment, use the function form below. Both are common in weft's own code.

The function form

ref also takes a function. weft calls it once, with the element:

import { Button } from '@weft-js/warp'export function Focus() {  let field: HTMLInputElement | undefined  return (    <form>      <input ref={el => (field = el)} aria-label="Your name" />      <Button onClick={() => field?.focus()}>Focus the field</Button>    </form>  )}

Here field is honestly HTMLInputElement | undefined, so you write field?.focus(). The function form is also what you use when the element goes somewhere other than one variable: into a Map, into a library call, or out to a parent. ref takes an array of functions too, ref={[measure, el => (field = el)]}, and calls each one.

When the element exists

A component's body runs once, top to bottom, and the TSX it returns is what makes the elements. So while the body is running, the element doesn't exist yet:

export function Broken() {  let field!: HTMLInputElement  field.focus() // TypeError: field is undefined. The <input> below hasn't been made yet.  return <input ref={field} aria-label="Name" />}

Use the element in code that runs later:

• Event handlers. A click can only happen once the element is on the page.
• onMount(fn). It runs once the component's elements are in the document, with every ref assigned. This is the place for work the first paint needs: measuring, focusing on arrival, starting a library.
• watch after its first run. A watch runs once straight away, while the body runs, and then on each change. On that first run the ref is still empty, so guard it with ?. or start the watch inside onMount.

import { onMount } from '@weft-js/core'export function Search() {  let field: HTMLInputElement | undefined  onMount(() => field?.focus())  return <input ref={el => (field = el)} type="search" aria-label="Search" />}

onMount never runs on the server, because there is no document there. Neither does ref: the server only writes HTML, and the browser makes the elements that ref points at. Code that needs an element is browser code by nature, so these are the right places for it.

An element a write just showed

Writes in weft are batched: a handler can change five boxes, and the page updates once, on the next microtask. So right after open.value = true, the element that open shows isn't in the page yet. If you need it now, call flush() first. It applies every pending update straight away:

import { flush, state } from '@weft-js/core'import { Button } from '@weft-js/warp'export function Rename() {  const editing = state(false)  let field: HTMLInputElement | undefined  const start = () => {    editing.value = true    flush() // the input is in the page now, and `field` holds it    field?.select()  }  return (    <div>      {editing.value ? <input ref={el => (field = el)} value="Untitled" aria-label="Name" /> : <Button onClick={start}>Rename</Button>}    </div>  )}

React has flushSync for the same job. You need it rarely: most DOM work belongs in onMount or a handler that runs after the update anyway.

Focusing, scrolling and measuring

These are the three jobs refs do most. Each one is a call on the element, from a handler or onMount.

Focus is el.focus(), el.select() and el.blur(), as in the demo at the top.

Scrolling is el.scrollIntoView(). When there are many elements, collect them with the function form. A ref function in a list runs once per row, when that row's element is made:

import { Button } from '@weft-js/warp'export function Cats(props: { names: string[] }) {  const rows = new Map<string, HTMLElement>()  const show = (name: string) => rows.get(name)?.scrollIntoView({ block: 'nearest' })  return (    <div>      <Button emphasis="soft" onClick={() => show('Orlando')}>Find Orlando</Button>      <ol style="max-block-size:7rem;overflow:auto">        {props.names.map(name => (          <li key={name} ref={(el: HTMLElement) => rows.set(name, el)}>{name}</li>        ))}      </ol>    </div>  )}

A row that is removed leaves its element in the map. That's harmless for a fixed list. For a long-lived list that changes, delete the entry where you remove the item, or look the element up when you need it (list.querySelector(...)) instead of keeping a map.

Measuring reads sizes and positions: getBoundingClientRect(), offsetWidth, scrollHeight. The element must be in the document and laid out, so measure in onMount or later. To follow a size as it changes, start a ResizeObserver in onMount and stop it in onCleanup:

The number on screen is state, written by the observer's callback. That's the usual shape of DOM work in weft: the element tells you something, you put it in a box, and the page follows the box like anything else.

Refs to elements inside other components

ref on a component isn't special: it's a prop like any other. A component that wants to give one of its elements to whoever renders it takes a ref prop, a function, and puts it on that element:

import { Button } from '@weft-js/warp'function NameField(props: { label: string; ref?: ((el: HTMLInputElement) => void) | undefined }) {  return (    <label>      {props.label} <input ref={props.ref} />    </label>  )}export function Form() {  let input: HTMLInputElement | undefined  return (    <div>      <NameField label="Name" ref={el => (input = el)} />      <Button onClick={() => input?.focus()}>Focus the name</Button>    </div>  )}

The parent passes a function, not a variable: on a component, ref={input} would pass the variable's current value, which is undefined, because the compiler only turns ref={x} into an assignment on an element. Inside NameField, ref={props.ref} is on an element, so it calls the function with the input.

This is what React calls forwarding a ref, without forwardRef. warp's components do it where it's useful: Button and Card take a ref function and call it with their element.

Values that aren't elements

React's useRef has a second job: holding a value that survives re-renders without causing one, such as a timer id. In weft that's a plain variable in the component body. The body runs once, so the variable is made once and stays:

import { onCleanup, state } from '@weft-js/core'import { Button } from '@weft-js/warp'export function Stopwatch() {  const tenths = state(0)  let timer: ReturnType<typeof setInterval> | undefined // not on screen, so not state  const start = () => {    clearInterval(timer)    timer = setInterval(() => tenths.value++, 100)  }  const stop = () => clearInterval(timer)  onCleanup(stop)  return (    <p>      {(tenths.value / 10).toFixed(1)} s <Button onClick={start}>Start</Button> <Button onClick={stop}>Stop</Button>    </p>  )}

The rule for picking between them: if the page shows it, it's state; if only your code reads it, a let is enough. A let that the TSX reads never updates the page, because nothing tells the page it changed. The catalog names that W041, though this weft doesn't report it yet: a let written in a handler and read in TSX should be state.

Recap

• ref={x} on an element assigns it to a let variable; ref={el => …} calls a function with it.
• let x!: T with ref={x} needs the ! for TypeScript and a no-unassigned-vars disable for linters; the function form needs neither.
• The element exists once the component's TSX has made it: use it in handlers, onMount, or watch after its first run, never while the body runs. flush() puts a just-written change in the page now.
• autofocus focuses an element when it's created, with no ref.
• A component passes one of its elements out through a ref prop that is a function.
• A plain let is weft's useRef for values: the body runs once, so it lasts as long as the component.

Try it