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.
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-filterQuick 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 badWhitelist 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 damnGet 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:
- Add new languages
- Improve existing word lists
- Report bugs
- 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