Bad Words Filter

4.0.0 · active · verified Tue Apr 21

bad-words is a JavaScript library designed for filtering profanity and undesirable words from text. The current stable version is 4.0.0, which ships with TypeScript types and requires a Node.js environment version 8.0.0 or higher, or an ES2016+ compatible browser environment. While the release cadence is not strictly defined, major versions introduce significant changes, such as the removal of global string prototype modifications and the shift to modern class instantiation. Key features include a highly customizable filter that allows for placeholder overrides, advanced regex-based filtering (including multilingual support), the ability to dynamically add or remove words from the blacklist, and the option to instantiate with an empty list for specific use cases. It also incorporates Soundex support for fuzzy word comparisons, providing a robust and flexible solution for content moderation across various applications.

Common errors

```
TypeError: String.prototype.clean is not a function
```
cause Attempting to use the deprecated global String.prototype.clean method.

fix Instantiate the Filter class: 'const filter = new Filter(); filter.clean(text);'
```
SyntaxError: Unexpected token 'export'
```
cause Running ESM 'import' syntax in a CommonJS-only Node.js environment or older browser that doesn't support modules.

fix Ensure your Node.js project is configured for ESM (e.g., 'type: module' in package.json), or use CommonJS 'const { Filter } = require('bad-words');' for older environments.
```
TypeError: Filter is not a constructor
```
cause Attempting to instantiate 'Filter' when it's not correctly imported or accessed from a CommonJS require, often due to incorrect destructuring.

fix For CommonJS, use 'const { Filter } = require('bad-words');' or 'const Filter = require('bad-words').Filter;' to correctly get the class from the module's exports.

Warnings

breaking The global String.clean() method was deprecated in v0.5.0 and completely removed in subsequent major versions (likely v1.0.0 or v2.0.0). Direct string prototype modification is no longer supported for filtering.
Fix: Instantiate a new Filter class: 'const filter = new Filter(); filter.clean(text);'
breaking As of version 2.0.0, bad-words requires an environment supporting ES2016 features or a transpiler like Babel. Older Node.js versions (below 8.0.0) are not supported.
Fix: Ensure your Node.js environment is v8.0.0 or higher, or use a build step with Babel for browser compatibility.
gotcha Prior to v1.1.0, the library used a 'factory mess' pattern for instantiation. Since v1.1.0, normal class instantiation via 'new Filter()' is the standard, aligning with modern JavaScript practices.
Fix: Always use 'new Filter()' for instantiation, as the factory pattern is no longer supported.
gotcha When filtering, if you want to allow all words initially and only blacklist specific ones, instantiate the filter with 'emptyList: true' to prevent default bad words from being pre-loaded.
Fix: const filter = new Filter({ emptyList: true }); filter.addWords('my-custom-bad-word');

Install

npm install bad-words npm
yarn add bad-words yarn
pnpm add bad-words pnpm

Imports

Filter
wrong:
```
const Filter = require('bad-words')
```
correct:
```
import { Filter } from 'bad-words'
```
The primary class for creating filter instances. For CommonJS, use 'const { Filter } = require('bad-words');' or 'const Filter = require('bad-words').Filter;' to correctly access the named export.
FilterOptions
```
import type { FilterOptions } from 'bad-words'
```
TypeScript type definition for the configuration object passed to the Filter constructor.
clean
wrong:
```
String.prototype.clean('some bad word')
```
correct:
```
new Filter().clean('some bad word')
```
The global String.prototype.clean method was deprecated in v0.5.0 and removed in later major versions. Always instantiate the Filter class and use its 'clean' method.

Quickstart

Demonstrates basic instantiation, cleaning text, customizing the placeholder, and dynamically adding words to the filter list.

import { Filter } from 'bad-words';

// Create a new filter instance with default settings
const filter = new Filter();

// Clean a string, replacing bad words with asterisks
const cleanText = filter.clean("Don't be an ash0le, this is a heck of a situation.");
console.log(cleanText);
// Expected output: "Don't be an ******, this is a **** of a situation."

// Customize the placeholder character
const customFilter = new Filter({ placeHolder: 'x' });
const customCleanText = customFilter.clean("This content is pretty lame.");
console.log(customCleanText);
// Expected output: "This content is pretty xxxx."

// Add custom words to the filter's blacklist
customFilter.addWords('lame', 'heck');
const updatedCleanText = customFilter.clean("This content is pretty lame and a heck of a mess.");
console.log(updatedCleanText);
// Expected output: "This content is pretty xxxx and a xxxx of a mess."

view raw JSON →