String UtilitiesAPI reference for string manipulation functionstypeAPI Reference
Categories

String Utilities

The String utilities provide a set of functions for working with strings in JavaScript. These functions help in manipulating, transforming, and analyzing string data efficiently.

Functions

kebabToCamel

function kebabToCamel(str = '', { separator = '_' } = {})

Converts a kebab-case string to camelCase. Digit-leading segments are preserved with an underscore prefix to enable lossless round-trips with camelToKebab.

Parameters

Name Type Description
str string The kebab-case string to convert
options object Optional configuration
Options
Name Type Default Description
separator string _ Character used to encode digit-leading segments

Returns

The camelCase version of the input string.

Example

import { kebabToCamel } from '@semantic-ui/utils';


console.log(kebabToCamel('background-color')); // 'backgroundColor'
console.log(kebabToCamel('grid-2x2')); // 'grid_2x2'
console.log(kebabToCamel('heading-1')); // 'heading_1'
console.log(kebabToCamel('arrow-down-a-z')); // 'arrowDownAZ'

camelToKebab

function camelToKebab(str = '', { lossless = false, separator = '_' } = {})

Converts a camelCase string to kebab-case. Underscore-digit sequences are decoded back to hyphen-digit to enable lossless round-trips with kebabToCamel.

By default, a leading uppercase character is silently lowercased to produce a valid HTML attribute name. If lossless is true, leading uppercase is preserved — the output may start with a hyphen (e.g. FooBar → -foo-bar), which is not a valid attribute name but allows an exact round-trip back through kebabToCamel.

Parameters

Name Type Description
str string The camelCase string to convert
options object Optional configuration
Options
Name Type Default Description
lossless boolean false Preserve leading uppercase for exact round-trip. Output may not be a valid attribute name.
separator string _ Character used to decode digit-leading segments

Returns

The kebab-case version of the input string.

Example

import { camelToKebab } from '@semantic-ui/utils';


console.log(camelToKebab('backgroundColor')); // 'background-color'
console.log(camelToKebab('grid_2x2')); // 'grid-2x2'
console.log(camelToKebab('heading_1')); // 'heading-1'
console.log(camelToKebab('arrowDownAZ')); // 'arrow-down-a-z'


// PascalCase is normalized by default
console.log(camelToKebab('FooBar')); // 'foo-bar'


// lossless preserves leading uppercase for exact round-trip
console.log(camelToKebab('FooBar', { lossless: true })); // '-foo-bar'

capitalize

function capitalize(str = '')

Capitalizes the first character of a string.

Parameters

Name Type Description
str string The string to capitalize

Returns

The input string with its first character capitalized.

Example

import { capitalize } from '@semantic-ui/utils';


console.log(capitalize('hello')); // 'Hello'
console.log(capitalize('WORLD')); // 'WORLD'

capitalizeWords

function capitalizeWords(str = '')

Capitalizes the first character of each word in a string.

Parameters

Name Type Description
str string The string to capitalize

Returns

The input string with the first character of each word capitalized.

Example

import { capitalizeWords } from '@semantic-ui/utils';


console.log(capitalizeWords('hello world')); // 'Hello World'
console.log(capitalizeWords('THE QUICK BROWN FOX')); // 'The Quick Brown Fox'

toTitleCase

function toTitleCase(str = '')

Converts a string to title case, taking into account common English articles, conjunctions, and prepositions.

Parameters

Name Type Description
str string The string to convert to title case

Returns

The input string converted to title case.

Example

import { toTitleCase } from '@semantic-ui/utils';


console.log(toTitleCase('the quick brown fox')); // 'The Quick Brown Fox'
console.log(toTitleCase('a tale of two cities')); // 'A Tale of Two Cities'

toTitleCase.config

The stop words that stay lowercase mid-title live in toTitleCase.config.stopWords. Style guides disagree here — AP capitalizes longer prepositions, Chicago lowercases them all — so the list is editable once at app boot, and humanize’s titleCase mode reads the same vocabulary.

import { toTitleCase } from '@semantic-ui/utils';


toTitleCase.config.stopWords.push('versus');
console.log(toTitleCase('cats versus dogs')); // 'Cats versus Dogs'

joinWords

function joinWords(words, options = {})

Joins an array of words into a string with customizable separators and formatting.

Parameters

Name Type Description
words array The array of words to join
options object Optional configuration object
Options
Name Type Default Description
separator string ’, ’ The separator between words
lastSeparator string ’ and ’ The separator before the last word
oxford boolean true Whether to use an Oxford comma
quotes boolean false Whether to wrap words in quotes
transform function null A function to transform each word

Returns

A string of joined words according to the specified options.

Example

import { joinWords } from '@semantic-ui/utils';


const fruits = ['apple', 'banana', 'cherry'];


console.log(joinWords(fruits));
// 'apple, banana, and cherry'


console.log(joinWords(fruits, { oxford: false }));
// 'apple, banana and cherry'


console.log(joinWords(fruits, { quotes: true }));
// '"apple", "banana", and "cherry"'


console.log(joinWords(fruits, { transform: word => word.toUpperCase() }));
// 'APPLE, BANANA, and CHERRY'

getArticle

function getArticle(word, settings = {})

Determines the appropriate indefinite article (‘a’ or ‘an’) for a given word, using a vowel check plus an exceptions vocabulary for words whose sound contradicts their spelling (hour, university).

Parameters

Name Type Description
word string The word to determine the article for
settings object Optional settings object
Settings
Name Type Default Description
capitalize boolean false Whether to capitalize the article

Returns

The appropriate indefinite article (‘a’ or ‘an’) for the given word.

Example

import { getArticle } from '@semantic-ui/utils';


console.log(getArticle('apple')); // 'an'
console.log(getArticle('banana')); // 'a'
console.log(getArticle('hour', { capitalize: true })); // 'An' (exceptions vocabulary)
console.log(getArticle('university')); // 'a' (sounds like "you")

getArticle.config

The exceptions vocabulary lives in getArticle.config.exceptions, a lowercased word mapped to its article, checked before the vowel heuristic. It ships seeded with the common sound-contradicts-spelling words and is editable once at app boot.

import { getArticle } from '@semantic-ui/utils';


getArticle.config.exceptions.faq = 'an';
console.log(getArticle('FAQ', { includeWord: true })); // 'an FAQ'

truncate

function truncate(text, length, options = {})

Truncates text to a specified length with intelligent word boundary handling and Unicode support.

Parameters

Name Type Description
text string The text to truncate
length number Maximum length of the output
options object Optional configuration
Options
Name Type Default Description
suffix string ‘…’ Text to append when truncated
wordBoundary boolean true Whether to truncate at word boundaries
locale string ‘en’ Locale for word segmentation

Returns

The truncated text with suffix if needed, or original text if shorter than length.

Example

import { truncate } from '@semantic-ui/utils';


// Basic usage
console.log(truncate('This is a long text that needs truncating', 20));
// 'This is a long text…'


// Disable word boundary
console.log(truncate('This is a long sentence', 15, { wordBoundary: false }));
// 'This is a very…'


// Custom suffix
console.log(truncate('This is a test', 10, { suffix: ' [more]' }));
// 'This [more]'


// Handles emojis correctly
console.log(truncate('Hello 👋 World 🌍', 10));
// 'Hello 👋…'


// Locale-aware segmentation
console.log(truncate('こんにちは世界です', 8, { locale: 'ja' }));
// 'こんにちは…'

These string utilities provide a robust set of tools for working with strings in JavaScript, enhancing productivity and code readability. The notes highlight some of the unique aspects and potential limitations of certain functions.

tokenize

function tokenize(str = '')

Converts a string into a token by replacing spaces with hyphens and removing non-word characters.

Parameters

Name Type Description
str string The string to tokenize

Returns

A tokenized version of the input string.

Example

import { tokenize } from '@semantic-ui/utils';


console.log(tokenize("Hello World!")); // "hello-world"
console.log(tokenize("User's Name_123")); // "users-name-123"

humanize

function humanize(str = '', options = {})

Converts a machine identifier into human-readable label text, the display-side inverse of tokenize. Splits snake_case, kebab-case, camelCase, and PascalCase, keeping acronym runs intact, and sentence-cases the result. Common lowercase acronyms (id, url, api) are rescued by a built-in vocabulary you can extend app-wide through humanize.config.

Parameters

Name Type Description
str string The identifier to humanize
options object Optional configuration
Options
Name Type Default Description
titleCase boolean false Title-case the result instead of sentence case, keeping stop words lowercase
dropId boolean true Drop a trailing id segment, e.g. user_id becomes User
constantCase boolean false Treat input as CONSTANT_CASE, sentence-casing shouting enums like IN_PROGRESS instead of preserving them as acronyms
terms object — Per-call term overrides ({ oauth: 'OAuth' }), a lowercased token mapped to its display string, layered over humanize.config.terms

Returns

The humanized label, or '' for empty or non-string input.

Example

import { humanize } from '@semantic-ui/utils';


// Basic usage
console.log(humanize('first_name')); // 'First name'
console.log(humanize('user-profile')); // 'User profile'
console.log(humanize('createdAt')); // 'Created at'


// Keeps acronyms whole, including plurals
console.log(humanize('getHTTPResponse')); // 'Get HTTP response'
console.log(humanize('getURLsFromPage')); // 'Get URLs from page'


// Drops a trailing id by default
console.log(humanize('user_id')); // 'User'
console.log(humanize('order_id', { dropId: false })); // 'Order ID'


// Built-in vocabulary rescues common lowercase acronyms
console.log(humanize('api_url')); // 'API URL'
console.log(humanize('avatar_url')); // 'Avatar URL'


// Title case for headers, respecting stop words
console.log(humanize('terms_of_service', { titleCase: true })); // 'Terms of Service'


// Sentence-case a shouting enum for a status label
console.log(humanize('IN_PROGRESS', { constantCase: true })); // 'In progress'

humanize.config

humanize.config holds the global defaults plus a terms vocabulary, a lowercased token mapped to its exact display string. It ships seeded with { id: 'ID', url: 'URL', api: 'API' }. Set it once at app boot and every call inherits it, so a large codebase pins its vocabulary in one place. A per-call terms option layers over it for one-off overrides.

import { humanize } from '@semantic-ui/utils';


// set an app-wide vocabulary once
humanize.config.terms.sku = 'SKU';
humanize.config.terms.oauth = 'OAuth';


console.log(humanize('product_sku')); // 'Product SKU'
console.log(humanize('oauth_token')); // 'OAuth token'


// a per-call term layers over the global vocabulary
console.log(humanize('gpu_count', { terms: { gpu: 'GPU' } })); // 'GPU count'

escapeHTML

function escapeHTML(string)

Escapes HTML special characters in a string. Returns an empty string for falsy input.

Parameters

Name Type Description
string string The string to escape

Returns

A new string with HTML special characters escaped, or '' if the input is falsy.

Example

import { escapeHTML } from '@semantic-ui/utils';


const str = '<script>alert("XSS")</script>';
console.log(escapeHTML(str)); // "&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;"


console.log(escapeHTML(null)); // ''
console.log(escapeHTML(undefined)); // ''
console.log(escapeHTML('')); // ''

unescapeHTML

function unescapeHTML(string)

Converts HTML entities back to their original characters. The inverse of escapeHTML.

Parameters

Name Type Description
string string The string containing HTML entities to unescape

Returns

A new string with HTML entities converted back to characters.

Example

import { unescapeHTML } from '@semantic-ui/utils';


console.log(unescapeHTML('&lt;div&gt;Hello&lt;/div&gt;')); // '<div>Hello</div>'
console.log(unescapeHTML('rock &amp; roll')); // 'rock & roll'

reverseString

function reverseString(str = '', options = {})

Reverses a string while properly handling Unicode grapheme clusters including emojis, flags, skin tones, and combined characters.

Parameters

Name Type Description
str string The string to reverse
options object Optional configuration
Options
Name Type Default Description
locale string ‘en’ Locale for grapheme segmentation

Returns

The reversed string with grapheme clusters preserved.

Example

import { reverseString } from '@semantic-ui/utils';


// Basic usage
console.log(reverseString('hello')); // 'olleh'
console.log(reverseString('hello world')); // 'dlrow olleh'


// Handles emojis correctly
console.log(reverseString('Hello 👋')); // '👋 olleH'
console.log(reverseString('🎉🎊🎈')); // '🎈🎊🎉'


// Preserves complex grapheme clusters
console.log(reverseString('🇺🇸🇬🇧')); // '🇬🇧🇺🇸' (flag emojis)
console.log(reverseString('Hello 👋🏽')); // '👋🏽 olleH' (emoji with skin tone)

These string utilities provide helpful tools for working with strings and text manipulation in JavaScript, enhancing string processing capabilities and security in web applications.

Previous
Regular Expressions
Next
Template Compiler