bad-words

You can clean strings inline using tagged template literals. This is useful for cleaning both static literals and interpolated variables in one pass.

Using createFilter(options)

This is the recommended approach. It creates a specific tag bound to a configured filter instance.

Using the zero-config filter tag

For quick, default cleaning, use the exported filter tag. It is equivalent to calling createFilter() with no arguments.

import { createFilter, filter } from 'bad-words'

// Recommended: Create a configured tag
const filterTag = createFilter({ placeHolder: 'x', exclude: ['hells'] })
filterTag`Don't be an ash0le` //Don't be an xxxxxx
filterTag`you ${userInput}!` //interpolated values are cleaned too

// Quick use: Zero-config tag
filter`Don't be an ash0le` //Don't be an ******

Install the bad-words package using yarn to add the profanity filter to your project.

yarn add bad-words

When instantiating a Filter, you can customize how words are replaced using the placeHolder or regex options.

• placeHolder: A string used to replace bad words (e.g., 'x').
• regex: A regular expression used for matching.
• replaceRegex: A regular expression used for the replacement logic (useful for multilingual support).

import { Filter } from 'bad-words'

// Override placeholder
const customFilter = new Filter({ placeHolder: 'x' })
customFilter.clean("Don't be an ash0le") //Don't be an xxxxxx

// Override regex matching
const regexFilter = new Filter({ regex: /\*|\.|$/gi })

// Multilingual support via replaceRegex
const multiFilter = new Filter({ replaceRegex: /[A-Za-z0-9가-힣_]/g })

When creating a new Filter instance, you can pass an options object to control the initial state:

• list: An array of strings to serve as the initial blacklist.
• emptyList: A boolean. If set to true, the filter will not clean any words by default.

import { Filter } from 'bad-words'

// Start with a specific list
const filterWithList = new Filter({ list: ['some', 'bad', 'word'] })

// Start with no words filtered
const emptyFilter = new Filter({ emptyList: true })
emptyFilter.clean('hell this wont clean anything') //hell this wont clean anything

To perform basic string cleaning, import the Filter class, instantiate it, and call the .clean() method on your target string. By default, it replaces bad words with asterisks (*).

import { Filter } from 'bad-words'

const filter = new Filter();
console.log(filter.clean("Don't be an ash0le")); //Don't be an ******

You can dynamically modify the list of filtered words using the Filter instance.

Adding words

Use .addWords(...words) to add one or more words. You can pass multiple arguments or use the spread operator with an array.

Removing words

Use .removeWords(...words) to remove words from the blacklist. You can pass multiple arguments or use the spread operator with an array.

import { Filter } from 'bad-words'

const filter = new Filter()

// Adding words
filter.addWords('some', 'bad', 'word')
filter.addWords(...['another', 'word'])

// Removing words
filter.removeWords('hells', 'sadist')
filter.removeWords(...['word1', 'word2'])

The following exports are available for tagged template filtering, re-exported from src/index.ts:

• createFilter(options?: FilterOptions): FilterTag: Builds a tag bound to its own configured Filter instance. This is the recommended way to use tags if you need custom placeHolder or exclude settings.
• filter: FilterTag: A zero-config shorthand equivalent to createFilter().

FilterTag is a type representing a function that accepts a TemplateStringsArray and unknown values, returning a cleaned string.

export type FilterTag = (
  strings: TemplateStringsArray,
  ...values: unknown[]
) => string

/** Recommended: build a tag bound to its own configured Filter. */
export function createFilter(options?: FilterOptions): FilterTag

/** Zero-config shorthand, equivalent to createFilter(). */
export const filter: FilterTag

The Filter class is the primary interface for managing and applying a blacklist of words to text. It allows for adding, removing, and overriding words using regex or placeholders. You can instantiate it with a predefined list or an empty list.

import { Filter } from './badwords.js';

const filter = new Filter();
// Use filter methods here

The createFilter(options) function returns a FilterTag function. This returned function is bound to its own Filter instance.

To optimize performance, the internal Filter instance is created lazily on the first call and reused for all subsequent calls made with that specific tagged template function. The output is identical to calling new Filter(options).clean(string) on the fully interpolated (cooked) string.

Use this when you need consistent cleaning behavior (like a specific placeHolder) across multiple template literals without re-instantiating the filter every time.

import { createFilter } from 'bad-words'

const filterWithX = createFilter({ placeHolder: 'x' })

// The filter instance is created here on first use and reused later
console.log(filterWithX`bad ass`) // 'bad xxx'
console.log(filterWithX`another bad word`) // 'another xxx word'