createElement

createElement is the low-level function behind every DOM.<tag>() call. It creates a DOM element, applies attributes, binds refs, and appends children. It is also useful for plugin authors who need to create elements programmatically.

Import

import { createElement } from "just-dom";

Signature

function createElement<T extends JDAllTags>(
  tagName: T,
  options: JDCreateElementOptions<T>,
  children?: JDCreateElementChildren,
  namespace?: JDElementNamespace,
): JDTagsMap[T];

JDElementNamespace is "html" | "svg" | "mathml" — the same values the DOM.<tag>() factories pass internally.

Parameters

Parameter	Type	Description
`tagName`	`T extends JDAllTags`	Any HTML, SVG, or MathML tag name
`options`	`JDCreateElementOptions<T>`	Attributes, styles, events, data attributes, and ref
`children`	`JDCreateElementChildren`	Optional children (array of nodes/strings, or a single string)
`namespace`	`JDElementNamespace`	Optional. Forces the element namespace. Omit it for normal HTML tags. Use `"svg"` / `"mathml"` when the tag string is shared with HTML (e.g. `"a"`, `"script"`, `"title"`) but you need the SVG or MathML element.

Namespace and shared tag names

Several tag names exist in both HTML and SVG (a, script, style, title). DOM.a and DOM.svgA both call createElement with "a", so the library resolves the namespace via the fourth argument — you should do the same when calling createElement directly:

import { createElement } from "just-dom";

const htmlLink = createElement("a", { href: "/home" }, "Home");
const svgLink = createElement("a", { href: "#section" }, "Jump", "svg");

If you omit namespace, unknown tag names fall back to inference: HTML-listed names use the HTML namespace; remaining names that appear only in SVG or MathML lists use createElementNS.

Returns

Type	Description
`JDTagsMap[T]`	The created element, typed to the specific tag (e.g. `HTMLDivElement` for `"div"`)

Usage

import { createElement } from "just-dom";

const div = createElement("div", { className: "card" }, [
  createElement("h2", {}, ["Title"]),
  createElement("p", {}, ["Content"]),
]);

This is equivalent to:

import DOM from "just-dom";

const div = DOM.div({ className: "card" }, [
  DOM.h2({}, "Title"),
  DOM.p({}, "Content"),
]);

For Plugin Authors

createElement is useful when building plugins that need to compose standard DOM elements:

import { definePlugin, createElement } from "just-dom";

export const alertPlugin = definePlugin({
  name: "alert",
  extend: () => ({
    alert: (message: string, type: "info" | "error" = "info") => {
      return createElement("div", { className: `alert alert-${type}` }, [
        createElement("span", {}, [message]),
      ]);
    },
  }),
});