is-bad-word

A powerful, multi-language profanity filter library for JavaScript/Node.js. Filter bad words in 9 languages with highly customizable options.

Features

• 9 Built-in Languages: English, French, Arabic, Darija (Moroccan Arabic), Spanish, Dutch, Hindi, Italian, Japanese
• Highly Customizable: Enable/disable filter, custom placeholders, whitelist words, custom word lists
• Method Chaining: Fluent API for easy configuration
• TypeScript Support: Full type definitions included
• Zero Dependencies: Lightweight and fast
• Case Insensitive: Matches words regardless of case
• Smart Word Boundaries: Proper handling for different scripts (Latin, Arabic, CJK)
• Save Original: Optionally save original text before filtering

Installation

npm install is-bad-word

Quick Start

const BadWordsFilter = require('is-bad-word');

// Create filter with default English language
const filter = new BadWordsFilter();

// Filter text
const result = filter.clean('This is some fuck text.');
console.log(result); // This is some **** text.

// Check if text contains bad words
if (filter.isProfane('Some text to check')) {
  console.log('Bad words detected!');
}

Supported Languages

| Language | Code | Script | Word Count | |----------|------|--------|------------| | English | english | Latin | 78+ words | | French | french | Latin | 90+ words | | Arabic | arabic | Arabic | 37+ words | | Darija | darija | Arabic | 37+ words | | Spanish | spanish | Latin | 68+ words | | Dutch | dutch | Latin | 180+ words | | Hindi | hindi | Latin (romanized) | 95+ words | | Italian | italian | Latin | 175+ words | | Japanese | japanese | Japanese | 180+ words |

Configuration Options

const filter = new BadWordsFilter({
  enabled: true,           // Enable/disable the filter (default: true)
  saveOriginal: false,     // Save original text (default: false)
  placeHolder: '*',        // Replacement character (default: '*')
  replaceRegex: null,      // Custom regex for replacement
  separatorRegex: /\s+/,   // Regex to split words
  excludeWords: [],        // Words to whitelist (ignore)
  wordsList: [],           // Custom word list (overrides default)
  language: 'english'      // Default language (default: 'english')
});

Usage Examples

Basic Filtering

const BadWordsFilter = require('is-bad-word');

// Default English filter
const filter = new BadWordsFilter();
console.log(filter.clean('This is shit!'));
// Output: This is ****!

// With custom placeholder
const filter2 = new BadWordsFilter({ placeHolder: '#' });
console.log(filter2.clean('This is shit!'));
// Output: This is ####!

Enable/Disable Filter

const filter = new BadWordsFilter({ enabled: false });
console.log(filter.clean('fuck this')); // fuck this (not filtered)

filter.setEnabled(true);
console.log(filter.clean('fuck this')); // **** this (filtered)

Save Original Text

const filter = new BadWordsFilter({ saveOriginal: true });
const cleaned = filter.clean('This is fuck bad');
console.log(cleaned);              // This is **** bad
console.log(filter.getOriginal()); // This is fuck bad

Whitelist Words (excludeWords)

// Exclude specific words from filtering
const filter = new BadWordsFilter({
  excludeWords: ['damn', 'hell']
});

console.log(filter.isProfane('damn'));  // false (whitelisted)
console.log(filter.isProfane('fuck'));  // true (not whitelisted)

// Add more words to whitelist
filter.addExcludeWords(['ass']);

Custom Word List (wordsList)

// Override default dictionary completely
const filter = new BadWordsFilter({
  wordsList: ['badword1', 'badword2', 'customword']
});

console.log(filter.isProfane('fuck'));      // false (not in custom list)
console.log(filter.isProfane('badword1'));  // true (in custom list)

// Or set it later
filter.setWordsList(['new1', 'new2']);

Multiple Languages

// Set language in constructor
const filter = new BadWordsFilter({ language: 'french' });
console.log(filter.isProfane('merde')); // true

// Or change language dynamically
filter.setLanguage('spanish');
console.log(filter.isProfane('mierda')); // true

// Load additional languages
filter.loadLanguage('italian');
filter.loadLanguage('dutch');

// Load all languages at once
filter.loadAllLanguages();

// Filter against multiple languages
const result = filter.clean('fuck merde mierda', ['english', 'french', 'spanish']);

Detecting Bad Words

const filter = new BadWordsFilter();

// Simple check
if (filter.isProfane('This has fuck in it')) {
  console.log('Contains profanity!');
}

// Alias method
filter.hasBadWords('fuck'); // true

// Find all bad words with details
const matches = filter.detect('fuck this shit');
console.log(matches);
// Output: [
//   { word: 'fuck', language: 'english', index: 0 },
//   { word: 'shit', language: 'english', index: 10 }
// ]

Adding/Removing Words

const filter = new BadWordsFilter();

// Add custom words to current language
filter.addWords(['customword', 'anotherword']);

// Add to specific language
filter.addWords(['palabra'], 'spanish');

// Remove words from filter
filter.removeWords(['damn', 'hell']);
filter.removeWords(['merde'], 'french');

Method Chaining

const filter = new BadWordsFilter()
  .setLanguage('english')
  .loadLanguage('french')
  .loadLanguage('spanish')
  .setPlaceHolder('#')
  .addWords(['customword'])
  .setExcludeWords(['damn'])
  .setEnabled(true);

const result = filter.clean('This has customword and damn');
// Output: This has ########## and damn

Get Information

const filter = new BadWordsFilter().loadAllLanguages();

// Get loaded languages
console.log(filter.getLanguages());
// Output: ['english', 'french', 'arabic', ...]

// Get words for a language
console.log(filter.getWords('english').length); // 78+

// Get supported languages (static method)
console.log(BadWordsFilter.getSupportedLanguages());
// Output: ['english', 'french', 'arabic', 'darija', 'spanish', 'dutch', 'hindi', 'italian', 'japanese']

API Reference

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable or disable the filter | | saveOriginal | boolean | false | Save the original input string | | placeHolder | string | '*' | Character used to replace profane words | | replaceRegex | RegExp | null | Custom regex for replacement | | separatorRegex | RegExp | /\s+/ | Regex to split string into words | | excludeWords | string[] | [] | Words to ignore (whitelist) | | wordsList | string[] | [] | Custom words list (overrides default) | | language | string | 'english' | Default language for filtering |

Methods

| Method | Returns | Description | |--------|---------|-------------| | clean(text, languages?) | string | Filter profane words from text | | filter(text, languages?) | string | Alias for clean() | | isProfane(text, languages?) | boolean | Check if text contains profane words | | hasBadWords(text, languages?) | boolean | Alias for isProfane() | | detect(text, languages?) | BadWordMatch[] | Find all profane words with details | | loadLanguage(language, filePath?) | this | Load a language's word list | | loadAllLanguages() | this | Load all 9 built-in languages | | setLanguage(language) | this | Set the default language | | setEnabled(state) | this | Enable or disable the filter | | setPlaceHolder(char) | this | Set the placeholder character | | setExcludeWords(words) | this | Set words to exclude (whitelist) | | addExcludeWords(words) | this | Add words to the exclude list | | setWordsList(words, language?) | this | Override the word list | | addWords(words, language?) | this | Add words to a language's list | | removeWords(words, language?) | this | Remove words from a language's list | | getOriginal() | string\|null | Get original text (if saveOriginal enabled) | | getLanguages() | string[] | Get list of loaded languages | | getWords(language?) | string[] | Get words for a language | | static getSupportedLanguages() | string[] | Get all supported language names |

Types (TypeScript)

interface BadWordsFilterOptions {
  enabled?: boolean;
  saveOriginal?: boolean;
  placeHolder?: string;
  replaceRegex?: RegExp;
  separatorRegex?: RegExp;
  excludeWords?: string[];
  wordsList?: string[];
  language?: string;
}

interface BadWordMatch {
  word: string;      // The matched word
  language: string;  // Which language matched
  index: number;     // Position in the original text
}

Legacy Function

For backwards compatibility:

const { filterBadWords } = require('is-bad-word');
const result = filterBadWords('Some text', 'english', '*');

TypeScript Support

Full TypeScript definitions are included:

import BadWordsFilter, { BadWordMatch, BadWordsFilterOptions } from 'is-bad-word';

const options: BadWordsFilterOptions = {
  placeHolder: '#',
  excludeWords: ['damn']
};

const filter = new BadWordsFilter(options);

const cleaned: string = filter.clean('text');
const isProfane: boolean = filter.isProfane('text');
const matches: BadWordMatch[] = filter.detect('text');

Use Cases

• Chat Applications: Filter user messages in real-time
• Comment Systems: Clean user-submitted content
• Social Media: Moderate posts and comments
• Gaming: Filter player names and chat
• Forums: Automatic content moderation
• Email Systems: Filter inappropriate content
• Content Management: Pre-publish content checking

Performance

• Uses compiled RegExp for fast matching
• Word lists are loaded once and cached
• Zero external dependencies
• Minimal memory footprint

Node.js Compatibility

Requires Node.js 14.0.0 or higher.

Contributing

Contributions are welcome! You can:

1. Add new languages
2. Improve existing word lists
3. Report bugs
4. Suggest features

License

MIT License - see LICENSE for details.

Changelog

v2.0.0

• New class-based API with method chaining
• Added configuration options: enabled, saveOriginal, excludeWords, wordsList
• Renamed methods: clean(), isProfane(), detect()
• Added 5 new languages (Spanish, Dutch, Hindi, Italian, Japanese)
• TypeScript definitions included
• Legacy function maintained for backwards compatibility