Dom utilities

import { containsHtml, isHtml, spanify, strToDom, splitText, wrapEl, downloadToDevice, removeWithTrace, restoreFromTrace } from '@bbc/front-end-kit/js/utils/dom';

This file contains all DOM-related utility functions that help shorten the codebase and speed up development.

`containsHtml`

Detects if a given string contains HTML tags or entities.

Returns

boolean

import { containsHtml } from '@bbc/front-end-kit/js/utils/dom';

containsHtml('Lorem Ipsum'); // false
containsHtml('Lorem <strong>Ipsum</strong>'); // true
containsHtml('<div>Lorem <strong>Ipsum</strong></div>'); // true

`isHtml`

Detects if a given string is exclusively an HTML tag or entity — no surrounding text.

Returns

boolean

import { isHtml } from '@bbc/front-end-kit/js/utils/dom';

isHtml('Lorem Ipsum'); // false
isHtml('Lorem <strong>Ipsum</strong>'); // false
isHtml('<div>Lorem <strong>Ipsum</strong></div>'); // true

`spanify`

Wraps a string in a <span> element with the given attributes. Attribute keys are converted to kebab-case; object values are JSON-stringified.

Parameters

str (string): The content to place inside the span.
attributes (object, optional): Key-value pairs to set as attributes on the span.

Returns

string — an HTML string of the span element.

import { spanify } from '@bbc/front-end-kit/js/utils/dom';

spanify('Hello', { className: 'highlight', dataIndex: 0 });
// '<span class-name="highlight" data-index="0">Hello</span>'

`strToDom`

Converts an HTML string into a live DOM element without adding it to the page first.

Parameters

str (string): An HTML string to parse.

Returns

Element — the first element child of the parsed fragment.

javascript

import { strToDom } from '@bbc/front-end-kit/js/utils/dom';

const $wrapper = strToDom('<div class="element"></div>');
const $inner = strToDom(`<div class="element__inner" id="el-${Math.round(Math.random() * 100)}"></div>`);

$wrapper.classList.add('element--modifier');
$wrapper.appendChild($inner);
document.body.appendChild($wrapper);

html

<body>
    <div class="element element--modifier">
        <div class="element__inner"></div>
    </div>
</body>

`splitText`

Splits all text within the target element(s) into individual <span> elements per word and per character.

Parameters

target (string | NodeList | Element): A CSS selector string, NodeList, or single Element to process.
attributes (object, optional): Attribute objects applied to word and character spans.
- attributes.word: Attributes for each word-level span.
- attributes.character: Attributes for each character-level span.

Returns

undefined

import { splitText } from '@bbc/front-end-kit/js/utils/dom';

splitText('.my-text', {
    word: { class: 'word' },
    character: { class: 'char' }
});

`wrapEl`

Wraps a given element in a newly created <div>.

Parameters

$el (Element): The element to wrap.
options (object, optional):
- replace (boolean, default false): If true, attempts to insert the wrapper in place of $el in the DOM.

Returns

Element — the original $el (not the wrapper div).

Warning

The replace: true branch calls parentNode.insertAfter(), which does not exist on Node. This option is currently broken and will throw a TypeError. Omit replace or handle placement manually.

import { wrapEl } from '@bbc/front-end-kit/js/utils/dom';

const $el = document.querySelector('.my-element');

// wraps $el in a div and returns $el
const $el = wrapEl($el);

`downloadToDevice`

Triggers a file download in the browser by creating a temporary anchor and clicking it programmatically.

Parameters

url (string): The URL of the file to download.
filename (string): The filename the browser should use when saving.

Returns

undefined

import { downloadToDevice } from '@bbc/front-end-kit/js/utils/dom';

downloadToDevice('https://example.com/file.pdf', 'report.pdf');

Removes an element from the DOM but leaves a hidden <span> placeholder in its place. The placeholder's ID is recorded in the element's data-origins attribute so it can be restored later with restoreFromTrace.

Multiple calls on the same element append IDs to data-origins separated by |, creating a position history.

Parameters

$el (Element): The element to remove.

Returns

Element — the removed element (with updated data-origins).

import { removeWithTrace } from '@bbc/front-end-kit/js/utils/dom';

const $el = document.querySelector('.my-element');
removeWithTrace($el); // $el removed, span placeholder left behind

Tips

Very handy for elements that need to move between DOM positions across screen sizes. Use a single element instance that travels rather than duplicating markup.

`restoreFromTrace`

Moves an element back to its previous DOM position by finding the last placeholder ID in its data-origins attribute and replacing it with the element.

Parameters

$el (Element): The element to restore.

Returns

Element — the restored element (chainable).

import { removeWithTrace, restoreFromTrace } from '@bbc/front-end-kit/js/utils/dom';

const $el = document.querySelector('.my-element');

removeWithTrace($el);
document.querySelector('.popup').appendChild($el);
removeWithTrace($el);
document.querySelector('.other').appendChild($el);

restoreFromTrace($el); // back to .popup
restoreFromTrace($el); // back to original position

// or chained:
restoreFromTrace(restoreFromTrace($el));