element

Creates one HTML element from a tag name and a props object, without the generic prop runtime of spread and Dynamic: for a library that renders one fixed element (a link, a button) and wants to pay only for what it binds. (element of @shadow-js/web)

Creates one HTML element from a tag name and a props object, without the generic prop runtime of spread and Dynamic: for a library that renders one fixed element (a link, a button) and wants to pay only for what it binds. It draws a hydration key, so during hydrate() it adopts the server's element and its children; on the server it returns the markup Dynamic writes for the tag.

Each prop other than children, ref and onX is read in a render effect, so a getter prop updates the element in place. class and the other attributes follow setAttribute (URL attributes that would run script are refused); style follows style. Use Dynamic when the tag is not known in advance, or for SVG, classList, delegated events or React prop names.

Import#

import { element } from "@shadow-js/web";

Signature#

function element(tag: string, props: object): unknown

Parameters#

Name Description

tag An HTML tag name matching [a-z][a-z0-9-]* (any case), such as "a". script is refused.

props The element's props. onX keys whose third letter is uppercase are native listeners, read once: the rest of the key lowercased is the event (onClick is click), and the value is a function (called with the element as this) or a [fn, data] tuple (called as fn(data, event)); handlers run batched and untracked. ref is called once with the element. children is inserted (a getter keeps it reactive). class takes a string; style a string or an object.

Name	Description
`tag`	An HTML tag name matching `[a-z][a-z0-9-]*` (any case), such as `"a"`. `script` is refused.
`props`	The element's props. `onX` keys whose third letter is uppercase are native listeners, read once: the rest of the key lowercased is the event (`onClick` is `click`), and the value is a function (called with the element as `this`) or a `[fn, data]` tuple (called as `fn(data, event)`); handlers run batched and untracked. `ref` is called once with the element. `children` is inserted (a getter keeps it reactive). `class` takes a string; `style` a string or an object.

Returns#

The element on the client; its server markup when rendering on the server.

Throws#

TypeError SHADOW_ELEMENT_TAG when tag is not an allowed tag name.

Examples#

import { useSignal } from "@shadow-js/core";
import { element } from "@shadow-js/web";

function HomeLink() {
  const [active] = useSignal(true);
  return element("a", {
    href: "/",
    get "aria-current"() { return active() ? "page" : undefined; },
    onClick: (event: MouseEvent) => console.log(event.type),
    children: "Home",
  });
}