@hyperfrontend/ui-utils/element

element

DOM element creation, retrieval, and dimension-tracking helpers.

createElement builds a configured element from an ElementConfig (tag, attributes, children, listeners) and returns it with ElementMethods attached for fluent updates. The per-tag shortcuts (div, span, button, input, img, paragraph, header, section, unorderedList, table-cell helpers, etc.) are pre-bound versions of createElement for the common HTML tags. getElementAsync resolves an element by ref or selector once it appears in the DOM, with OnSuccess/OnFail callbacks for the timeout case. onElementResize registers an ElementResizeCallback against ResizeObserver to track dimension changes without polling.

API Reference

ƒ Functions

§function

anchor(config?: ElementConfig): ElementMethods<HTMLAnchorElement>

Creates an anchor (link) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLAnchorElement>
An ElementMethods object containing the created anchor element and helper methods

Example

Creating anchor element

const link = anchor({ href: '/home', textContent: 'Home' })
link.element // => HTMLAnchorElement
§function

article(config?: ElementConfig): ElementMethods<HTMLElement>

Creates an article element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLElement>
An ElementMethods object containing the created article element and helper methods

Example

Creating article element

const post = article({ class: 'blog-post' })
post.element // => HTMLElement
§function

aside(config?: ElementConfig): ElementMethods<HTMLElement>

Creates an aside element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLElement>
An ElementMethods object containing the created aside element and helper methods

Example

Creating aside element

const sidebar = aside({ class: 'sidebar' })
sidebar.element // => HTMLElement
§function

button(config?: ElementConfig): ElementMethods<HTMLButtonElement>

Creates a button element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLButtonElement>
An ElementMethods object containing the created button element and helper methods

Example

Creating button element

const submitBtn = button({ class: 'btn-primary', textContent: 'Submit' })
submitBtn.element // => HTMLButtonElement
§function

canvas(config?: ElementConfig): ElementMethods<HTMLCanvasElement>

Creates a canvas element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLCanvasElement>
An ElementMethods object containing the created canvas element and helper methods

Example

Creating canvas element

const drawing = canvas({ width: '800', height: '600' })
drawing.element // => HTMLCanvasElement
§function

createElement<T>(tagName: unknown, config?: ElementConfig): ElementMethods<T>

Creates an HTML element with configuration and provides utility methods for manipulation. Supports inline styles, class names, and common DOM operations.

Parameters

NameTypeDescription
§tagName
unknown
The HTML tag name to create
§config?
ElementConfig
Optional configuration for the element including styles and class names

Returns

ElementMethods<T>
An ElementMethods object with helper methods and a reference to the created element

Example

Creating element with configuration

const card = createElement('div', {
  className: 'card',
  classNames: ['shadow', 'rounded'],
  inlineStyle: { padding: '16px', margin: '8px' }
})

const title = createElement('h2')
title.ref.textContent = 'Card Title'

card.addChild(title)
card.attachTo(document.body)
card.show(300) // Fade in over 300ms
§function

div(config?: ElementConfig): ElementMethods<HTMLDivElement>

Creates a div element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLDivElement>
An ElementMethods object containing the created div element and helper methods

Example

Creating div element

const container = div({ class: 'container', id: 'main' })
container.element // => HTMLDivElement
§function

getElementAsync(elementRefOrString: ElementRefOrString, options?: GetElementAsyncOptions): () => void

Asynchronously waits for an element to become available in the DOM. Polls at regular intervals and invokes callbacks on success or timeout.

Parameters

NameTypeDescription
§elementRefOrString
ElementRefOrString
Either an HTMLElement reference or a CSS selector string
§options?
GetElementAsyncOptions
Configuration options including duration, interval, and callbacks

Returns

() => void
A cleanup function to cancel the polling

Example

Waiting for dynamic element

const cancel = getElementAsync('#dynamic-content', {
  duration: 5000,
  interval: 100,
  onSuccess: (element) => {
    console.log('Element found:', element)
  },
  onFail: () => {
    console.log('Element not found within timeout')
  },
})

// Cancel polling if no longer needed
cancel()
§function

header(level: number, config?: ElementConfig): ElementMethods<HTMLHeadingElement>

Creates a heading element (h1-h6) with optional configuration.

Parameters

NameTypeDescription
§level
number
The heading level (1-6)
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLHeadingElement>
An ElementMethods object containing the created heading element and helper methods

Example

Creating heading element

const title = header(1, { textContent: 'Page Title' })
title.element // => HTMLHeadingElement (h1)
§function

img(config?: ElementConfig): ElementMethods<HTMLImageElement>

Creates an image element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLImageElement>
An ElementMethods object containing the created image element and helper methods

Example

Creating image element

const avatar = img({ src: '/avatar.png', alt: 'User avatar' })
avatar.element // => HTMLImageElement
§function

input(config?: ElementConfig): ElementMethods<HTMLInputElement>

Creates an input element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLInputElement>
An ElementMethods object containing the created input element and helper methods

Example

Creating input element

const email = input({ type: 'email', placeholder: 'Enter email' })
email.element // => HTMLInputElement
§function

label(config?: ElementConfig): ElementMethods<HTMLLabelElement>

Creates a label element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLLabelElement>
An ElementMethods object containing the created label element and helper methods

Example

Creating label element

const emailLabel = label({ for: 'email', textContent: 'Email:' })
emailLabel.element // => HTMLLabelElement
§function

listItem(config?: ElementConfig): ElementMethods<HTMLLIElement>

Creates a list item (li) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLLIElement>
An ElementMethods object containing the created list item element and helper methods

Example

Creating list item element

const item = listItem({ textContent: 'First item' })
item.element // => HTMLLIElement
§function

onElementResize(element: HTMLElement, callback: ElementResizeCallback): () => void

Observes an element for size changes and triggers a callback when resized.

Parameters

NameTypeDescription
§element
HTMLElement
The element to observe for resize events
§callback
ElementResizeCallback
The function to call when the element is resized

Returns

() => void
A cleanup function to stop observing the element

Example

Observing element resize

const container = document.getElementById('resizable-panel')
const stopObserving = onElementResize(container, (rect) => {
  console.log(`New size: ${rect.width}x${rect.height}`)
})

// Stop observing when done
stopObserving()
§function

orderedList(config?: ElementConfig): ElementMethods<HTMLOListElement>

Creates an ordered list (ol) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLOListElement>
An ElementMethods object containing the created ordered list element and helper methods

Example

Creating ordered list element

const steps = orderedList({ class: 'instructions' })
steps.element // => HTMLOListElement
§function

paragraph(config?: ElementConfig): ElementMethods<HTMLParagraphElement>

Creates a paragraph element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLParagraphElement>
An ElementMethods object containing the created paragraph element and helper methods

Example

Creating paragraph element

const text = paragraph({ textContent: 'Hello, world!' })
text.element // => HTMLParagraphElement
§function

section(config?: ElementConfig): ElementMethods<HTMLElement>

Creates a section element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLElement>
An ElementMethods object containing the created section element and helper methods

Example

Creating section element

const about = section({ id: 'about', class: 'page-section' })
about.element // => HTMLElement
§function

span(config?: ElementConfig): ElementMethods<HTMLSpanElement>

Creates a span element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLSpanElement>
An ElementMethods object containing the created span element and helper methods

Example

Creating span element

const badge = span({ class: 'badge', textContent: 'New' })
badge.element // => HTMLSpanElement
§function

syncElementDimensions<S, T>(sourceElementRefOrString: ElementRefOrString<S>, targetElementRefOrString: ElementRefOrString<T>, options?: GetElementAsyncOptions): () => void

Synchronizes the dimensions and position of a target element with a source element. Automatically updates when the source element is resized.

Parameters

NameTypeDescription
§sourceElementRefOrString
ElementRefOrString<S>
The source element to copy dimensions from (element or selector)
§targetElementRefOrString
ElementRefOrString<T>
The target element to apply dimensions to (element or selector)
§options?
GetElementAsyncOptions
Optional configuration for element retrieval and callbacks

Returns

() => void
A cleanup function to stop synchronization

Example

Syncing overlay to video dimensions

// Sync an overlay to match a video player's dimensions
const stopSync = syncElementDimensions('#video-player', '#overlay', {
  onSuccess: () => console.log('Elements synced'),
})

// Stop syncing when component unmounts
stopSync()
§function

tableBody(config?: ElementConfig): ElementMethods<HTMLTableSectionElement>

Creates a table body (tbody) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableSectionElement>
An ElementMethods object containing the created tbody element and helper methods

Example

Creating table body element

const body = tableBody({ id: 'data-rows' })
body.element // => HTMLTableSectionElement
§function

tableCell(config?: ElementConfig): ElementMethods<HTMLTableCellElement>

Creates a table data cell (td) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableCellElement>
An ElementMethods object containing the created td element and helper methods

Example

Creating table cell element

const cell = tableCell({ textContent: 'John Doe' })
cell.element // => HTMLTableCellElement
§function

tableFooter(config?: ElementConfig): ElementMethods<HTMLTableSectionElement>

Creates a table footer (tfoot) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableSectionElement>
An ElementMethods object containing the created tfoot element and helper methods

Example

Creating table footer element

const foot = tableFooter({ class: 'summary' })
foot.element // => HTMLTableSectionElement
§function

tableHead(config?: ElementConfig): ElementMethods<HTMLTableSectionElement>

Creates a table head (thead) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableSectionElement>
An ElementMethods object containing the created thead element and helper methods

Example

Creating table head element

const head = tableHead({ class: 'sticky-header' })
head.element // => HTMLTableSectionElement
§function

tableHeader(config?: ElementConfig): ElementMethods<HTMLTableElement>

Creates a table element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableElement>
An ElementMethods object containing the created table element and helper methods

Example

Creating table element

const grid = tableHeader({ class: 'data-table' })
grid.element // => HTMLTableElement
§function

tableHeaderCell(config?: ElementConfig): ElementMethods<HTMLTableCellElement>

Creates a table header cell (th) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableCellElement>
An ElementMethods object containing the created th element and helper methods

Example

Creating table header cell

const header = tableHeaderCell({ textContent: 'Name', scope: 'col' })
header.element // => HTMLTableCellElement
§function

tableRow(config?: ElementConfig): ElementMethods<HTMLTableRowElement>

Creates a table row (tr) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLTableRowElement>
An ElementMethods object containing the created tr element and helper methods

Example

Creating table row element

const row = tableRow({ class: 'data-row' })
row.element // => HTMLTableRowElement
§function

unorderedList(config?: ElementConfig): ElementMethods<HTMLUListElement>

Creates an unordered list (ul) element with optional configuration.

Parameters

NameTypeDescription
§config?
ElementConfig
Optional configuration for element attributes, styles, and content

Returns

ElementMethods<HTMLUListElement>
An ElementMethods object containing the created unordered list element and helper methods

Example

Creating unordered list element

const menu = unorderedList({ class: 'nav-menu' })
menu.element // => HTMLUListElement

Interfaces

§interface

GetElementAsyncOptions

Configuration options for async element retrieval.

Properties

§duration?:number
Maximum time to wait in milliseconds
§interval?:number
Polling interval in milliseconds
§onFail?:OnFail
Callback when lookup times out
§onSuccess?:OnSuccess
Callback when element is found

Types

§type

ElementConfig

Configuration options for creating an HTML element.
§type

ElementMethods

Utility methods and properties for manipulating a created HTML element.
§type

ElementRefOrString

Element reference as either an HTMLElement or a CSS selector string
type ElementRefOrString = T | string
§type

ElementResizeCallback

Callback invoked when an element is resized with the new content rect.
type ElementResizeCallback = (rect: DOMRectReadOnly) => void
§type

HtmlTagName

Valid HTML element tag name from the HTMLElementTagNameMap.
type HtmlTagName = unknown
§type

OnFail

Callback invoked when the element lookup times out
type OnFail = () => void
§type

OnSuccess

Callback invoked when the element is found
type OnSuccess = (element: HTMLElement) => void