Global

Methods

altlangs() → {object}

Utility to grab all alternative languages on the page. this scrapes the page of all elements and returns as a readable object

Source:
Returns:

object of available languages and corresponding URLs

Type
object
Example
import { altlangs } from '@carbon/ibmdotcom-utilities';

const langs = altlangs();

console.log(langs); // { 'us-en': 'https://www.ibm.com/us-en', ... }

calculateTotalWidth(elements) → {number}

Utility to calculate the total width of elements

Parameters:
Name Type Description
elements Array

array of classnames
Source:
Returns:

total width of the elements

Type
number
Example
import {calculateTotalWidth} from '@carbon/ibmdotcom-utilities';

const elements = ['bx--classname1', 'bx--classname2','bx--classname3','bx--classname4'];

calculateTotalWidth(elements);

decodeString(str) → {string}

Utility function to parse and decode text content. Strings can become encoded for various reasons. This utility decodes those strings.

Parameters:
Name Type Description
str string

String to decode
Source:
Returns:

Final string with decoded characters

Type
string
Example
import { decodeString } from '@carbon/ibmdotcom-utilities'

const str = decodeString('https://www.ibm.com/search?lang=en&cc=us&q=cloud');
console.log(str); // https://www.ibm.com/search?lang=en&cc=us&q=cloud

escapeRegExp(str) → {string}

Utiltity function for escaping regex expressions https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Escaping

Parameters:
Name Type Description
str string

String to escape regex
Source:
Returns:

Final string with escaped regex

Type
string
Example
import { escapeRegExp } from '@carbon/ibmdotcom-utilities'

const result = escapeRegExp('Hello?!*`~World()[]');
console.log(result); // Hello\?!\*`~World\(\)\[\]

focuswrap(element, sentinelNodes, eventRequestFocusWrapopt) → {function}

Fires the given event if focus goes out of the given element.

Parameters:
Name Type Attributes Default Description
element Element

The element to monitor the focus on.
sentinelNodes Array.<Element>

The focus sentinel nodes. If these nodes gets focus, we see it as focus went out of the element.
eventRequestFocusWrap string <optional>
 cds-request-focus-wrap

The event name.
Source:
Returns:

The handle to remove the event handler.

Type
function

formatVideoCaption(optionsopt) → {string}

The default g11n formatter for video caption, combining video name and video duration. Components using this function should have a mechanism to allow translators to replace it with one accomodating the preferences of specific locale.

Parameters:
Name Type Attributes Description
options object <optional>

The options, with a video name and a formatted video duration.

Properties
Name Type Attributes Description
duration string <optional>

The video duration.
name string <optional>

The video name.
Source:
Returns:

The formatted video caption.

Type
string

formatVideoDuration(optionsopt) → {string}

The default g11n formatter for video duration. Components using this function should have a mechanism to allow translators to replace it with one accomodating the preferences of specific locale, or to replace it with general-purpose g11n formatting library. (e.g. moment, though it's too big for us to make it a hard dependency)

Parameters:
Name Type Attributes Description
options object <optional>

The options, with a video duration.

Properties
Name Type Attributes Description
duration number <optional>

The video duration, in seconds.
Source:
Returns:

The formatted video duration.

Type
string

loadNonLatinPlex(language, weightsopt)

Utility to load in the corresponding non-Latin Plex font if necessary

Parameters:
Name Type Attributes Default Description
language string

two-character language code
weights Array <optional>
 []

Array of specific weights to load (100-700)
Source:
Example
import { loadNonLatinPlex } from '@carbon/ibmdotcom-utilities';

loadNonLatinPlex('ar');

// Load specific weights only
loadNonLatinPlex('ar', [400,600]);

markdownToHtml(str, optionsopt) → {string}

Converts markdown syntaxes into html

Parameters:
Name Type Attributes Default Description
str string

String to convert to html
options object <optional>
 {}

Object with options for the conversion

Properties
Name Type Attributes Default Description
allowHtml boolean <optional>
 false

Defines if should allow or remove html tags
renderer object <optional>

Custom renderers
customTags Set.<string> <optional>

List of custom element tags the renderer uses.
Source:
Returns:

String converted to html

Type
string
Example
import { markdownToHtml } from '@carbon/ibmdotcom-utilities';

markdownToHtml('Lorem *ipsum* dolor __sit__.')
// 'Lorem <em class="bx--type-light">ipsum</em> dolor <strong class="bx--type-semibold">sit</strong>.'

on(element, …args) → {Event}

Parameters:
Name Type Attributes Description
element *
args any <repeatable>
Source:
Returns:

The event

Type
Event

parseAspectRatio(aspectRatioString) → {Array}

Utility to parse aspect ratios into width & height values

Parameters:
Name Type Description
aspectRatioString string

string in format

Source:
Returns:

[widthInt, heightInt]

Type
Array
Example
import {parseAspectRatio} from '@carbon/ibmdotcom-utilities';

const [width, height] = parseAspectRatio('16x9');

removeHtmlTagEntities(str, optionsopt) → {string}

Parameters:
Name Type Attributes Default Description
str string

html string passed in to remove html tags and entities
options object <optional>
 {}

Object with options for the conversion

Properties
Name Type Attributes Default Description
removeEntities boolean <optional>
 true

Defines if should remove html entities
Source:
Returns:

String removed of html tags

Type
string
Example
import { removeHtmlTagEntities } from '@carbon/ibmdotcom-utilities';

markdownToHtml('<p>example string</p>&nbsp;<p>here</>')
// 'example string here'

sameHeight(elemCollection, minSize)

Utility that sets an array of elements to the same height.

Parameters:
Name Type Default Description
elemCollection Array

Html objects array
minSize string false

Minimum size for the utility to be activated, empty for small, md for medium, lg for large, xlg for xlarge, max for maximum
Source:
Example
import {sameHeight} from '@carbon/ibmdotcom-utilities';

sameHeight(ElementArray, 'md');

if you want the utility to refresh the sizes as you resize the screen, consider using a listener:

window.addEventListener('resize', function() {
  window.requestAnimationFrame(function() {
    sameHeight(ElementArray, 'md');
  });
}, true);

serialize(obj) → {string}

Converts a JSON object to a serialized string

Parameters:
Name Type Description
obj object

Object to convert
Source:
Returns:

Serialized string

Type
string
Example
import { serialize } from '@carbon/ibmdotcom-utilities'

const obj = {
 param1: 'one',
 param2: 'two',
 param3: 'three',
};

const result = serialize(obj);
console.log(result); // param1=one&param2=two&param3=three

smoothScroll(e, selector, offset)

Utility handles smoothScroll on the anchor element after onClick

Parameters:
Name Type Default Description
e *

event object
selector *

menu item selector id
offset number 0

top offset for the scroll
Source:
Example
import { smoothScroll } from '@carbon/ibmdotcom-utilities';

Here e is event param and seletor is param where you want to apply smoothscroll
<a href="#anchorlinkname" onClick={smoothScroll({ e, selector })}>lorem ipsum</a>

it will scroll into view of target by selecting attribute and assigning to id.
Returns null if no scroll is needed

stripHTML(content) → {null}

Utility returns the text stripping all html tags from it.

Parameters:
Name Type Description
content string

with html tags
Source:
Returns:

content without html tags

Type
null
Example
import { stripHTML } from '@carbon/ibmdotcom-utilities';

content = stripHTML(this.innerHtml);

uniqueid(prefixopt) → {string}

Creates a unique ID to use

Parameters:
Name Type Attributes Default Description
prefix string <optional>
 id

Prefix to set for the id
Source:
Returns:

Unique ID

Type
string
Example
import { uniqueid } from '@carbon/ibmdotcom-utilities';

const id1 = uniqueid(); // id1
const id2 = uniqueid(); // id2
const id3 = uniqueid('prefix'); // prefix3
const id4 = uniqueid('prefix-'); // prefix-4