to-caption

Converts camelCase, PascalCase and delimited strings to captions, for labelling a form field, table column or menu item from the name behind it

Delimiters are dot, underscore, and dash: [ . _ - ]

Examples

foo.bar / foo_bar / fooBar / foo-bar

Foo Bar

_hello_world_

Hello World

thisIsATest

This Is A Test

Usage

npm install --save to-caption

ES module

import toCaption from 'to-caption'

toCaption('helloWorld') // 'Hello World'

CommonJS

const toCaption = require('to-caption')

toCaption('helloWorld') // 'Hello World'

TypeScript declarations are included for both.

Browser

A webpacked UMD build is included at dist/toCaption.js. The function is exported as window.toCaption(...)

<html>
<head>
  <script src="https://unpkg.com/to-caption/dist/toCaption.js"></script>
  <script>
    console.log(toCaption('helloWorld'))
  </script>
</head>
</html>

Rules

• Delimiters are period, dash, and underscore, unless you pass your own
• Leading, trailing and repeated delimiters are ignored
• Each delimiter becomes a single space, and the character after it is uppercased
• The first character is uppercased
• Uppercase letters are prefixed with spaces. This covers every alphabet, so fooÉtat becomes Foo État
• Any other character, such as a slash, a space or a digit, is kept as it is
• null, undefined and anything else that is not a string give an empty string

More samples

This table should give you an idea of the process.

ID | Label | Comment -|-|- this.is.a.test | This Is A Test foo | Foo Foo | Foo foobar | Foobar fooBar | Foo Bar FooBar | Foo Bar foo_bar | Foo Bar foo.bar | Foo Bar foo-bar | Foo Bar foo/bar | Foo/bar | Slash is not a delimiter foo/bar | Foo Bar | delimiters = '/' _foo | Foo foo_ | Foo _foo_ | Foo _foo_bar_ | Foo Bar __foo | Foo foo__ | Foo --foo--bar-- | Foo Bar address2 | Address2 | Digits stay attached address2 | Address 2 | numbers = 'split' parseHTTPResponse | Parse H T T P Response | Every capital starts a word parseHTTPResponse | Parse HTTP Response | acronyms = 'keep' FOOBAR | F O O B A R | See the onAllUppercase option to avoid this behavior FOOBAR | FOOBAR | onAllUppercase = 'keep' FOOBAR | Foobar | onAllUppercase = 'titlecase' FOO_BAR | Foo Bar | onAllUppercase = 'titlecase' FOO_BAR | FOO BAR | acronyms = 'keep'

Options

The second argument is optional, and may be undefined or null. Options combine freely

toCaption('parseHTTP2Response', { acronyms: 'keep', numbers: 'split' }) // 'Parse HTTP 2 Response'

Option | Values | Default -|-|- onAllUppercase | 'keep', 'titlecase' | every capital becomes its own word acronyms | 'keep' | every capital becomes its own word numbers | 'split' | digits stay attached to the letters beside them delimiters | any string | '._-'

Any value not listed, including undefined and null, gives the default

onAllUppercase

toCaption('HELLO', { onAllUppercase: 'keep' }) // 'HELLO'

Sets the behavior when the string is all uppercase: it has at least one letter, and no lowercase letters. A string with no letters at all, such as 123_456, is not all uppercase and is captioned as usual

'keep'

The string is returned exactly as given, delimiters included (_HELLO_WORLD_ stays _HELLO_WORLD_). To keep the capitals and still replace the delimiters, use acronyms: 'keep' instead

'titlecase'

Each delimited word becomes titlecase (HELLO_WORLD becomes Hello World)

'default', undefined, null, or anything else

The string has spaces between each letter, as if each letter was a word (H E L L O)

acronyms

toCaption('parseHTTPResponse', { acronyms: 'keep' }) // 'Parse HTTP Response'

'keep'

A run of capitals stays together. The last capital of a run starts the next word when a lowercase letter follows it, so XMLHttpRequest becomes XML Http Request and thisIsATest is still This Is A Test. An all uppercase string keeps its words whole (HELLO_WORLD becomes HELLO WORLD), unless onAllUppercase says otherwise

'split', undefined, null, or anything else

Every capital starts a word (Parse H T T P Response)

numbers

toCaption('version10Beta3', { numbers: 'split' }) // 'Version 10 Beta 3'

'split'

A space goes between digits and letters, and the word after a number is capitalized (item2name becomes Item 2 Name). A run of digits stays together

'keep', undefined, null, or anything else

Digits stay attached to the letters beside them (Version10 Beta3)

delimiters

toCaption('foo bar/baz', { delimiters: ' /' }) // 'Foo Bar Baz'

A string of the characters that separate words. It replaces the default '._-' and does not add to it, so include those three if you still want them. An empty string means nothing is a delimiter

Compatibility

• Node 12.17 or later, as an ES module or through require. Tested on Node 20, 24 and 25
• The browser build uses Unicode property escapes in regular expressions: Chrome 64, Firefox 78, Safari 11.1 or later

Development

npm run build        # webpack the UMD build into dist/
npm run copyright    # set the copyright year range in LICENSE and every source header
npm run lint         # eslint, including the no-semicolon and single-quote rules
npm test             # mocha, against both the ES module and the CommonJS build
npm run check:types  # verify the published types resolve for every consumer
npm run check:homepage  # confirm the homepage in package.json answers

npm publish runs all of these first, through prepublishOnly

The copyright holder and start year are set once, in config.copyright in package.json. The end year is always the current year, and npm run lint fails on any header that is out of date

The files in test2/ are manual checks: node test2/node_import.js, node test2/node_require.cjs, and test2/test.html in a browser

License

MIT. Check the LICENSE file for all the details.