> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/getsafehtml.md).

# GetSafeHTML

Sanitizes HTML using antisamy policy rules.

The policy can be a string name of a built-in policy, a file path to a custom policy XML file, or a struct for programmatic policy configuration.

**Built-in policies:** `anythinggoes`, `ebay` (default), `myspace`, `slashdot`, `tinymce`

## Method Signature

```
GetSafeHTML( string, [policy], [throwOnError], [force] )
```

### Arguments

| Argument       | Type             | Required | Description                                                                                                   | Default                           |
| -------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `string`       | `string`         | `true`   | The HTML to sanitize                                                                                          |                                   |
| `policy`       | `string\|struct` | `false`  | The policy to use: a string name, file path, or a struct for programmatic configuration                       | `""` (uses default `ebay` policy) |
| `throwOnError` | `boolean`        | `false`  | When `true`, throws an exception if HTML violates policy rules instead of silently returning sanitized output | `false`                           |
| `force`        | `boolean`        | `false`  | When `true` and using a struct policy, evicts it from cache and rebuilds it on demand                         | `false`                           |

## Struct Policy Configuration

When passing a struct as the policy, the following keys are supported for programmatic configuration:

| Key                  | Type     | Description                                                                                             |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `basePolicy`         | `string` | Start from a named policy and override specific parts (e.g., `"ebay"`, `"myspace"`, `"none"` for blank) |
| `overrideMode`       | `string` | `"merge"` (default) or `"override"` — controls how overrides are applied to the base policy             |
| `directives`         | `struct` | Struct of directive key/value pairs (e.g., `{ maxInputSize: 200000 }`)                                  |
| `allowTags`          | `array`  | Array of tag names to allow with "validate" action                                                      |
| `tagRules`           | `struct` | Struct of tag rules (tag name to action string or config struct)                                        |
| `globalAttributes`   | `struct` | Struct of attributes valid on all tags                                                                  |
| `dynamicAttributes`  | `struct` | Struct of wildcard attributes (e.g., `data-*`)                                                          |
| `cssRules`           | `struct` | Struct of CSS property rules                                                                            |
| `allowedEmptyTags`   | `array`  | Array of self-closing tag names                                                                         |
| `requireClosingTags` | `array`  | Array of tag names requiring end tags                                                                   |
| `tagsToEncode`       | `array`  | Array of tag names to entity-encode                                                                     |

## Examples

### Basic sanitization with default eBay policy

```js
result = getSafeHTML( "<b>Hello</b> <script>alert('xss')</script>" )
// result: "<b>Hello</b> "
```

### Using a named policy

```js
result = getSafeHTML( "<b>Hello</b>", "myspace" )
// result: "<b>Hello</b>"
```

### Custom policy via struct — merge mode with directive override

```js
result = getSafeHTML(
    "<b>" & repeatString( "x", 25000 ) & "</b>",
    {
        basePolicy: "ebay",
        overrideMode: "merge",
        directives: { maxInputSize: 50000 }
    }
)
// Returns sanitized HTML with a custom 50KB input limit
```

### Custom policy via struct — override mode (replace rules)

```js
result = getSafeHTML(
    "<b>Hello</b><em>World</em>",
    {
        basePolicy: "ebay",
        overrideMode: "override",
        allowTags: [ "b", "em" ]
    }
)
// Returns: "<b>Hello</b><em>World</em>" (only allows b and em tags)
```

### Building a policy from scratch

```js
result = getSafeHTML(
    "<b>Hello</b>",
    {
        basePolicy: "none",
        allowTags: [ "b" ],
        directives: { maxInputSize: 100000 }
    }
)
// Returns: "<b>Hello</b>" (only allows specified tags)
```

### Force cache eviction and rebuild for struct policies

```js
// First call caches the policy
result1 = getSafeHTML( "<b>test</b>", policyStruct )

// Second call uses cached policy (for performance)
result2 = getSafeHTML( "<b>test</b>", policyStruct )

// Force eviction and rebuild
result3 = getSafeHTML( "<b>test</b>", policyStruct, false, true )
```

### Throwing exceptions on policy violations

```js
try {
    result = getSafeHTML(
        "<script>alert('xss')</script>",
        "ebay",
        true  // throwOnError = true
    )
} catch ( BoxRuntimeException e ) {
    // Catches policy violations
    writeln( "Sanitization failed: " & e.message )
}
```

## Related

* [Canonicalize](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/canonicalize.md)
* [DecodeFor](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/decodefor.md)
* [DecodeForBase64](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/decodeforbase64.md)
* [DecodeForHTML](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/decodeforhtml.md)
* [DecodeForJson](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/decodeforjson.md)
* [DecodeFromURL](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/decodefromurl.md)
* [EncodeFor](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodefor.md)
* [encodeForCSS](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforcss.md)
* [encodeForDN](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodefordn.md)
* [encodeForHTML](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforhtml.md)
* [encodeForHTMLAttribute](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforhtmlattribute.md)
* [encodeForJavaScript](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforjavascript.md)
* [encodeForLDAP](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforldap.md)
* [EncodeForSQL](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforsql.md)
* [encodeForURL](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforurl.md)
* [encodeForXML](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforxml.md)
* [encodeForXMLAttribute](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforxmlattribute.md)
* [encodeForXPath](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/encodeforxpath.md)
* [esapiDecode](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/esapidecode.md)
* [esapiEncode](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/esapiencode.md)
* [IsSafeHTML](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/issafehtml.md)
* [SanitizeHTML](/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/sanitizehtml.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/esapi/reference/built-in-functions/esapi/getsafehtml.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.