@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
Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLAnchorElement>Example
Creating anchor element
const link = anchor({ href: '/home', textContent: 'Home' })
link.element // => HTMLAnchorElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLElement>Example
Creating article element
const post = article({ class: 'blog-post' })
post.element // => HTMLElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLElement>Example
Creating aside element
const sidebar = aside({ class: 'sidebar' })
sidebar.element // => HTMLElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLButtonElement>Example
Creating button element
const submitBtn = button({ class: 'btn-primary', textContent: 'Submit' })
submitBtn.element // => HTMLButtonElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLCanvasElement>Example
Creating canvas element
const drawing = canvas({ width: '800', height: '600' })
drawing.element // => HTMLCanvasElementParameters
Returns
ElementMethods<T>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 300msParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLDivElement>Example
Creating div element
const container = div({ class: 'container', id: 'main' })
container.element // => HTMLDivElementgetElementAsync(elementRefOrString: ElementRefOrString, options?: GetElementAsyncOptions): () => void
Parameters
Returns
() => voidExample
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()Parameters
Returns
ElementMethods<HTMLHeadingElement>Example
Creating heading element
const title = header(1, { textContent: 'Page Title' })
title.element // => HTMLHeadingElement (h1)Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLImageElement>Example
Creating image element
const avatar = img({ src: '/avatar.png', alt: 'User avatar' })
avatar.element // => HTMLImageElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLInputElement>Example
Creating input element
const email = input({ type: 'email', placeholder: 'Enter email' })
email.element // => HTMLInputElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLLabelElement>Example
Creating label element
const emailLabel = label({ for: 'email', textContent: 'Email:' })
emailLabel.element // => HTMLLabelElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLLIElement>Example
Creating list item element
const item = listItem({ textContent: 'First item' })
item.element // => HTMLLIElementParameters
Returns
() => voidExample
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()Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLOListElement>Example
Creating ordered list element
const steps = orderedList({ class: 'instructions' })
steps.element // => HTMLOListElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLParagraphElement>Example
Creating paragraph element
const text = paragraph({ textContent: 'Hello, world!' })
text.element // => HTMLParagraphElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLElement>Example
Creating section element
const about = section({ id: 'about', class: 'page-section' })
about.element // => HTMLElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLSpanElement>Example
Creating span element
const badge = span({ class: 'badge', textContent: 'New' })
badge.element // => HTMLSpanElementsyncElementDimensions<S, T>(sourceElementRefOrString: ElementRefOrString<S>, targetElementRefOrString: ElementRefOrString<T>, options?: GetElementAsyncOptions): () => void
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 |
Returns
() => voidExample
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()Parameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableSectionElement>Example
Creating table body element
const body = tableBody({ id: 'data-rows' })
body.element // => HTMLTableSectionElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableCellElement>Example
Creating table cell element
const cell = tableCell({ textContent: 'John Doe' })
cell.element // => HTMLTableCellElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableSectionElement>Example
Creating table head element
const head = tableHead({ class: 'sticky-header' })
head.element // => HTMLTableSectionElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableElement>Example
Creating table element
const grid = tableHeader({ class: 'data-table' })
grid.element // => HTMLTableElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableCellElement>Example
Creating table header cell
const header = tableHeaderCell({ textContent: 'Name', scope: 'col' })
header.element // => HTMLTableCellElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLTableRowElement>Example
Creating table row element
const row = tableRow({ class: 'data-row' })
row.element // => HTMLTableRowElementParameters
| Name | Type | Description |
|---|---|---|
§config? | ElementConfig | Optional configuration for element attributes, styles, and content |
Returns
ElementMethods<HTMLUListElement>Example
Creating unordered list element
const menu = unorderedList({ class: 'nav-menu' })
menu.element // => HTMLUListElement◈ Interfaces
◆ Types
type ElementRefOrString = T | stringtype ElementResizeCallback = (rect: DOMRectReadOnly) => voidtype HtmlTagName = unknowntype OnSuccess = (element: HTMLElement) => void