JSPM

@azamani/badwords-filter

2.0.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q28703F
  • License MIT

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

Package Exports

  • @azamani/badwords-filter
  • @azamani/badwords-filter/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@azamani/badwords-filter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Bad Words Filter

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

npm version License: MIT

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 badwords-filter

Quick Start

const BadWordsFilter = require('badwords-filter');

// 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('badwords-filter');

// 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('badwords-filter');
const result = filterBadWords('Some text', 'english', '*');

TypeScript Support

Full TypeScript definitions are included:

import BadWordsFilter, { BadWordMatch, BadWordsFilterOptions } from 'badwords-filter';

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