@hyperfrontend/ui-utils/elementelement
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
Creates an anchor (link) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLAnchorElement>An ElementMethods object containing the created anchor element and helper methods
Example
Creating anchor element
const link = anchor({ className: 'nav-link' })
link.ref.href = '/home'Creates an article element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLElement>An ElementMethods object containing the created article element and helper methods
Example
Creating article element
const post = article({ className: 'blog-post' })
post.ref // => HTMLElementCreates an aside element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLElement>An ElementMethods object containing the created aside element and helper methods
Example
Creating aside element
const sidebar = aside({ className: 'sidebar' })
sidebar.ref // => HTMLElementCreates a button element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLButtonElement>An ElementMethods object containing the created button element and helper methods
Example
Creating button element
const submitBtn = button({ className: 'btn-primary' })
submitBtn.ref.textContent = 'Submit'Creates a canvas element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLCanvasElement>An ElementMethods object containing the created canvas element and helper methods
Example
Creating canvas element
const drawing = canvas({ className: 'stage' })
drawing.ref.width = 800Creates an HTML element with configuration and provides utility methods for manipulation. Supports inline styles, class names, and common DOM operations.
Parameters
| Name | Type | Description |
|---|---|---|
§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 300msCreates a div element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLDivElement>An ElementMethods object containing the created div element and helper methods
Example
Creating div element
const container = div({ className: 'container' })
container.ref.id = 'main'§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
| Name | Type | Description |
|---|---|---|
§elementRefOrString | ElementRefOrString | Either an HTMLElement reference or a CSS selector string |
§options? | GetElementAsyncOptions | Configuration options including duration, interval, and callbacks |
Returns
() => voidA 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()Creates a heading element (h1-h6) with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§level | number | The heading level (1-6) |
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLHeadingElement>An ElementMethods object containing the created heading element and helper methods
Example
Creating heading element
const title = header(1, { className: 'page-title' })
title.ref.textContent = 'Page Title'Creates an image element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLImageElement>An ElementMethods object containing the created image element and helper methods
Example
Creating image element
const avatar = img({ className: 'avatar' })
avatar.ref.src = '/avatar.png'Creates an input element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLInputElement>An ElementMethods object containing the created input element and helper methods
Example
Creating input element
const email = input({ className: 'field' })
email.ref.type = 'email'Creates a label element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLLabelElement>An ElementMethods object containing the created label element and helper methods
Example
Creating label element
const emailLabel = label({ className: 'field-label' })
emailLabel.ref.htmlFor = 'email'Creates a list item (li) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLLIElement>An ElementMethods object containing the created list item element and helper methods
Example
Creating list item element
const item = listItem({ className: 'nav-item' })
item.ref.textContent = 'First item'Observes an element for size changes and triggers a callback when resized.
Parameters
| Name | Type | Description |
|---|---|---|
§element | HTMLElement | The element to observe for resize events |
§callback | ElementResizeCallback | The function to call when the element is resized |
Returns
() => voidA 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()Creates an ordered list (ol) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLOListElement>An ElementMethods object containing the created ordered list element and helper methods
Example
Creating ordered list element
const steps = orderedList({ className: 'instructions' })
steps.ref // => HTMLOListElementCreates a paragraph element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLParagraphElement>An ElementMethods object containing the created paragraph element and helper methods
Example
Creating paragraph element
const text = paragraph({ className: 'lede' })
text.ref.textContent = 'Hello, world!'Creates a section element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLElement>An ElementMethods object containing the created section element and helper methods
Example
Creating section element
const about = section({ className: 'page-section' })
about.ref.id = 'about'Creates a span element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLSpanElement>An ElementMethods object containing the created span element and helper methods
Example
Creating span element
const badge = span({ className: 'badge' })
badge.ref.textContent = 'New'§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
| Name | Type | Description |
|---|---|---|
§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. onSuccess fires once, after both elements are found and the first sync has been applied, and receives the target element. onFail fires if either lookup times out. |
Returns
() => voidA 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: (overlay) => overlay.classList.add('ready'),
})
// Stop syncing when component unmounts
stopSync()Creates a table body (tbody) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableSectionElement>An ElementMethods object containing the created tbody element and helper methods
Example
Creating table body element
const body = tableBody({ className: 'data-rows' })
body.ref // => HTMLTableSectionElementCreates a table data cell (td) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableCellElement>An ElementMethods object containing the created td element and helper methods
Example
Creating table cell element
const cell = tableCell({ className: 'name-cell' })
cell.ref.textContent = 'John Doe'Creates a table head (thead) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableSectionElement>An ElementMethods object containing the created thead element and helper methods
Example
Creating table head element
const head = tableHead({ className: 'sticky-header' })
head.ref // => HTMLTableSectionElementCreates a table element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableElement>An ElementMethods object containing the created table element and helper methods
Example
Creating table element
const grid = tableHeader({ className: 'data-table' })
grid.ref // => HTMLTableElementCreates a table header cell (th) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableCellElement>An ElementMethods object containing the created th element and helper methods
Example
Creating table header cell
const nameHeader = tableHeaderCell({ className: 'col-name' })
nameHeader.ref.textContent = 'Name'Creates a table row (tr) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLTableRowElement>An ElementMethods object containing the created tr element and helper methods
Example
Creating table row element
const row = tableRow({ className: 'data-row' })
row.ref // => HTMLTableRowElementCreates an unordered list (ul) element with optional configuration.
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional inline styles and class names to apply to the element |
Returns
ElementMethods<HTMLUListElement>An ElementMethods object containing the created unordered list element and helper methods
Example
Creating unordered list element
const menu = unorderedList({ className: 'nav-menu' })
menu.ref // => HTMLUListElement◈ Interfaces
Configuration options for async element retrieval.
Properties
◆ Types
Utility methods and properties for manipulating a created HTML element.
Element reference as either an HTMLElement or a CSS selector string
type ElementRefOrString = T | stringCallback invoked when an element is resized with the new content rect.
type ElementResizeCallback = (rect: DOMRectReadOnly) => voidValid HTML element tag name from the HTMLElementTagNameMap.
type HtmlTagName = unknownCallback invoked when the element is found
type OnSuccess = (element: HTMLElement) => void