### Customize escaping function for value of attributes
By specifying the handler function with `safeAttrValue`:
```javascript
function safeAttrValue (tag, name, value) {
// Parameters are the same with onTagAttr (without options)
// Return the value as a string
}
```
### Customize CSS filter
If you allow the attribute `style`, the value will be processed by [cssfilter](https://github.com/leizongmin/js-css-filter) module. The cssfilter module includes a default css whitelist. You can specify the options for cssfilter module like this:
```javascript
myxss = new xss.FilterXSS({
css: {
whiteList: {
position: /^fixed|relative$/,
top: true,
left: true,
}
}
});
html = myxss.process('<script>alert("xss");</script>');
```
If you don't want to filter out the `style` content, just specify `false` to the `css` option:
```javascript
myxss = new xss.FilterXSS({
css: false,
});
```
For more help, please see https://github.com/leizongmin/js-css-filter
### Quick Start
#### Filter out tags not in the whitelist
By using `stripIgnoreTag` parameter:
+ `true` filter out tags not in the whitelist
+ `false`: by default: escape the tag using configured `escape` function
Example:
If `stripIgnoreTag = true` is set, the following code:
```html
code:<script>alert(/xss/);</script>
```
would output filtered:
```html
code:alert(/xss/);
```
#### Filter out tags and tag bodies not in the whitelist
By using `stripIgnoreTagBody` parameter:
+ `false|null|undefined` by default: do nothing
+ `'*'|true`: filter out all tags not in the whitelist
+ `['tag1', 'tag2']`: filter out only specified tags not in the whitelist
Example:
If `stripIgnoreTagBody = ['script']` is set, the following code:
```html
code:<script>alert(/xss/);</script>
```
would output filtered:
```html
code:
```
#### Filter out HTML comments
By using `allowCommentTag` parameter:
+ `true`: do nothing
+ `false` by default: filter out HTML comments
Example:
If `allowCommentTag = false` is set, the following code:
```html
code:<!-- something --> END
```
would output filtered:
```html
code: END
```
## Examples
### Allow attributes of whitelist tags start with `data-`
```javascript
var source = '<diva="1"b="2"data-a="3"data-b="4">hello</div>';
var html = xss(source, {
onIgnoreTagAttr: function (tag, name, value, isWhiteAttr) {
if (name.substr(0, 5) === 'data-') {
// escape its value using built-in escapeAttrValue function
return name + '="' + xss.escapeAttrValue(value) + '"';
}
}
});
console.log('%s\nconvert to:\n%s', source, html);
```
Result:
```html
<diva="1"b="2"data-a="3"data-b="4">hello</div>
convert to:
<divdata-a="3"data-b="4">hello</div>
```
### Allow tags start with `x-`
```javascript
var source = '<x><x-1>he<x-2checked></x-2>wwww</x-1><a>';
var html = xss(source, {
onIgnoreTag: function (tag, html, options) {
if (tag.substr(0, 2) === 'x-') {
// do not filter its attributes
return html;
}
}
});
console.log('%s\nconvert to:\n%s', source, html);
```
Result:
```html
<x><x-1>he<x-2checked></x-2>wwww</x-1><a>
convert to:
<x><x-1>he<x-2checked></x-2>wwww</x-1><a>
```
### Parse images in HTML
```javascript
var source = '<imgsrc="img1">a<imgsrc="img2">b<imgsrc="img3">c<imgsrc="img4">d';
var list = [];
var html = xss(source, {
onTagAttr: function (tag, name, value, isWhiteAttr) {
if (tag === 'img' && name === 'src') {
// Use the built-in friendlyAttrValue function to escape attribute
// values. It supports converting entity tags such as < to printable
// characters such as <
list.push(xss.friendlyAttrValue(value));
}
// Return nothing, means keep the default handling measure
}
});
console.log('image list:\n%s', list.join(', '));
```
Result:
```html
image list:
img1, img2, img3, img4
```
### Filter out HTML tags (keeps only plain text)
```javascript
var source = '<strong>hello</strong><script>alert(/xss/);</script>end';
var html = xss(source, {
whiteList: [], // empty, means filter out all tags
stripIgnoreTag: true, // filter out all HTML not in the whilelist
stripIgnoreTagBody: ['script'] // the script tag is a special case, we need
