Underscore.string: String Utilities

3.3.6 · maintenance · verified Sun Apr 19

Underscore.string is a comprehensive JavaScript library designed to augment native string capabilities, offering a wide array of utility functions for common string manipulations. Originally conceived as an extension for Underscore.js, it has evolved into a fully standalone utility, capable of independent use. The current stable version is 3.3.6. It provides functionalities such as `slugify` for URL-friendly strings, `numberFormat` for localized number formatting, `capitalize` for proper casing, and `levenshtein` for calculating string edit distances. While it can be integrated with Underscore.js or Lo-Dash via mixins, this approach is discouraged due to potential naming conflicts with core methods like `include` and `reverse`. The library is consumable in Node.js environments using CommonJS `require` statements and in browsers through a UMD build, which exposes a global `s` object. A key architectural advantage is the ability to import individual functions, which significantly helps in reducing bundle sizes when using module bundlers like Browserify or Webpack, as opposed to including the entire library. Its release cadence has transitioned from frequent updates to a more maintenance-focused schedule, with the last significant update being the 3.x series, followed by minor patches. It remains a robust option for projects requiring extensive string utility functions.

Common errors

```
ReferenceError: s is not defined
```
cause The `s` global or `s` variable from `require('underscore.string')` was not properly loaded or imported before use.

fix For Node.js, ensure you have `var s = require('underscore.string');` at the top of your file. For browsers, ensure `underscore.string.js` is loaded via a `<script>` tag before your code executes, or via an AMD loader.
```
TypeError: _.include is not a function
```
cause You are attempting to use `_.include` (or `_.contains`, `_.reverse`, `_.join`) from `underscore.string` after mixing it into Underscore.js/Lo-Dash. These functions are dropped by `underscore.string` during the mixin process because of name collisions with the host library.

fix Avoid using `_.mixin(s.exports())`. Instead, use `underscore.string` as a standalone module (e.g., `s.include(...)`) or use the equivalent functions provided by Underscore.js/Lo-Dash directly.
```
SyntaxError: Cannot use import statement outside a module
```
cause You are attempting to use ES Module `import` syntax (e.g., `import s from 'underscore.string'`) in a CommonJS environment (e.g., a `.js` file not treated as a module, or older Node.js versions) without proper transpilation.

fix For CommonJS environments, use `var s = require('underscore.string');`. If you need ESM syntax, ensure your project is configured to treat files as ES Modules (e.g., `"type": "module"` in `package.json`) and/or use a bundler/transpiler like Babel or Webpack.

Warnings

breaking Upgrading from 2.x to 3.x introduced several breaking changes. Functions like `s.include`, `s.contains`, `s.reverse`, and `s.join` were removed to prevent collisions with Underscore.js methods. `s.chars` behavior changed, argument orders for `s.count` were altered, and `s.chop` was removed.
Fix: Consult the 3.0.0 changelog (https://github.com/epeli/underscore.string/blob/master/CHANGELOG.markdown#300) for a comprehensive list of changes and adapt your code accordingly.
gotcha Mixing `underscore.string` into Underscore.js or Lo-Dash using `_.mixin(s.exports())` can lead to collisions. Specifically, `include`, `contains`, `reverse`, and `join` from `underscore.string` are dropped during mixin because Underscore.js already defines them, potentially leading to unexpected behavior if your code relies on `underscore.string`'s versions.
Fix: It is generally not recommended to use the `mixin` approach. Prefer importing `underscore.string` as a standalone object (`var s = require('underscore.string')`) and calling its methods directly (e.g., `s.slugify(...)`).
gotcha When using bundlers like Browserify or Webpack for client-side applications, `require('underscore.string')` (the full library) will include all functions, even if you only use a few. This can significantly increase your bundle size.
Fix: To optimize bundle size, import individual functions directly, e.g., `var slugify = require('underscore.string/slugify');`. This allows tree-shaking (if configured) to eliminate unused code.

Install

npm install underscore.string npm
yarn add underscore.string yarn
pnpm add underscore.string pnpm

Imports

s
wrong:
```
import s from 'underscore.string';
```
correct:
```
var s = require('underscore.string');
```
Primarily a CommonJS library. ESM imports are not directly supported without transpilation or bundler configuration.
slugify
wrong:
```
var s = require('underscore.string'); s.slugify(...);
```
correct:
```
var slugify = require('underscore.string/slugify');
```
Importing individual functions directly is recommended for bundlers like Browserify to minimize bundle size.
s (global)
wrong:
```
var s = window.s;
```
correct:
```
s.capitalize('hello');
```
When used in a browser environment via the UMD build (e.g., from `dist/underscore.string.js`), the library exposes itself as a global `s` object.

Quickstart

Demonstrates requiring the full library for chaining and individual functions for specific utilities, alongside a number formatting example.

var s = require('underscore.string');
var slugify = require('underscore.string/slugify');

console.log(slugify('Hello world from individual import!'));
// => "hello-world-from-individual-import"

var text = '   epeli  is a great   developer   ';
var processedText = s(text).trim().capitalize().replace('epeli', 'John').value();
console.log(processedText);
// => "Epeli is a great John   developer"

// Example of number formatting
console.log(s.numberFormat(1234567.89, 2, '.', ','));
// => "1,234,567.89"

view raw JSON →