ref()

Create an ElementRef<T> (a Signal<T | null>) that Whisq populates with a DOM element after mount and resets to null on unmount. Pass it as the ref prop on any element and read .value — not .current — after onMount.

Not React

Whisq refs are plain signals. Read them with .value, never .current — that’s the most common mistake for developers coming from React. See Common Mistakes → .current instead of .value.

Signature

function ref<T extends HTMLElement = HTMLElement>(): ElementRef<T>;

Where ElementRef<T> is a named type alias exported from @whisq/core:

type ElementRef<T> = Signal<T | null>;

The alias is structurally identical to Signal<T | null> — its job is ergonomic. Tooltips read ElementRef<HTMLInputElement> instead of Signal<HTMLInputElement | null>, so the concept has a name.

Returns

An ElementRef<T> that starts at null and is set to the element after mount. Read via .value.

Examples

import { ref, component, input, onMount } from "@whisq/core";

const Focus = component(() => {
  const inputEl = ref<HTMLInputElement>(); // ElementRef<HTMLInputElement>
  onMount(() => inputEl.value?.focus()); // .value — not .current
  return input({ ref: inputEl, placeholder: "Autofocused" });
});

Because it’s a regular signal, you can also read it reactively:

import { ref, effect, div } from "@whisq/core";

const el = ref<HTMLDivElement>();
effect(() => {
  if (el.value) console.log("mounted", el.value.getBoundingClientRect());
});
div({ ref: el }, "Hello");

Naming a prop or field that holds a ref

Use the ElementRef<T> type when you need to declare the shape of an object, prop, or collection of refs:

import type { ElementRef } from "@whisq/core";

type FormRefs = {
  email: ElementRef<HTMLInputElement>;
  submitBtn: ElementRef<HTMLButtonElement>;
};

Callback-ref form

A function that receives the element is also supported on the ref prop. Ref<T> — exported as a type from @whisq/core — is the union of both shapes:

import type { Ref } from "@whisq/core";

type Ref<T> = ElementRef<T> | ((el: T | null) => void);

Backward compatibility

ElementRef<T> is a type alias over Signal<T | null>, not a new type. Code that declared const r: Signal<HTMLInputElement | null> = ref() still type-checks without changes — the alias exists for readability, not for nominal typing.