https://github.com/jaredkrinke/literal-html

Simple and unsafe HTML/XML templates for TypeScript, using tagged template literals
https://github.com/jaredkrinke/literal-html

deno tagged-literals templates

Last synced: 11 months ago
JSON representation

Simple and unsafe HTML/XML templates for TypeScript, using tagged template literals

• Host: GitHub
• URL: https://github.com/jaredkrinke/literal-html
• Owner: jaredkrinke
• License: mit-0
• Created: 2021-11-12T17:53:51.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2021-12-08T05:24:57.000Z (over 4 years ago)
• Last Synced: 2025-05-11T00:11:33.184Z (about 1 year ago)
• Topics: deno, tagged-literals, templates
• Language: TypeScript
• Homepage:
• Size: 16.6 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# literal-html

Simple and unsafe HTML/XML templates for TypeScript, using [tagged template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).

**This library should not be used with untrusted strings!**

## Syntax

Tagged template literals in JavaScript start with a tag (`html` or `xml` for this library) and are enclosed in backticks (e.g. `` html`text goes here` ``).

Values are inserted as JavaScript expressions enclosed in braces, prefixed by a dollar sign (e.g. `` html`
${value}
` ``).


For literal-html, if the expression evaluates to an object with a single key, the key indicates the type of escaping that is required. For example, `{attr: "&"}` is an object with `attr` as its key and `"&"` as its (string) value. This tells literal-html to escape the value as an attribute value. For example, `` html`` `` would be escaped as ``.

Supported types and keys:

| Format | Escapes | Notes |

|---|---|---|

| `${...}` | &<>'" | Supports `number` in addition to `string` |

| `${{content: ...}}` | &<> | |

| `${{attr: ...}}` | &<>'" | |

| `${{scriptString: ...}}` | <"\ | Namely for use in JSON-LD |

| `${{param: ...}}` | `encodeURIComponent()` | For URL query parameters |

| `${{verbatim: ...}}` | (none) | Only use with previously escaped strings |

## Examples

### General usage

```javascript

import { html, xml } from "https://deno.land/x/literal_html/mod.ts";

const value = ...; // Some string to be inserted

// Strings are escaped conservatively by default:

const fragmentHTML = html`
${value}
`;

const fragmentXML = xml`${value}`;


// You can specify the type of escaping required using an object with a single key, e.g. {attr: ...} for an attribute`:

const fragment3 = html``;

// To eliminate escaping altogether use the "verbatim" key:

const fragment4 = html`
${{verbatim: "This will NOT be escaped at all!"}}
`;

```


Examples of each type of escape follow.

### Default escaping (escapes: &<>'")

```javascript

const value = "what's  do? this & \"that\"!";

const result = html`
${value}
`;


// Result: 
what's <this> do? this & "that"!

```


### Content between start and end tags (escapes: &<)

```javascript

const value = "what's  do? this & \"that\"!";

const result = html`
${{content: value}}
`;


// Result: 
what's <this> do? this & "that"!

```


### Attribute value (escapes: &<")

```javascript

const value = "what's  do? this & \"that\"!";

const result = html``;

// Result: 

```

### HTML/JSON script string (escapes: <"\\)

```javascript

const value = 'A < "B" \\ C';

const result = html`{ "name": "${{scriptString: value}}" }`;

// Result: { "name": "A \x3C \"B\" \\ C" }

```

### Query parameters/URI components (escapes using `encodeURIComponent()` and escaping &<>'")

```javascript

const value = "what's  do? 'this' & \"that\"!";

const result = html`
Link
`;


// Result: 
Link

```


### Verbatim strings (no escaping)

This should only be used with strings that have already been properly escaped.

```javascript

const result = html`
${{verbatim: "Line 1
Line 2
"}}
`;


// Result: 
Line 1
Line 2


```


This is especially useful for conditional inclusion:

```javascript

const alt = "An image";

const result = html``;

// Result: 

```

Or applying templates to arrays of values:

```javascript

const listItems = ["<", ">", "&"];

const result = html`
${{

    verbatim: listItems

        .map(x => html`
${x}
`)

        .join("")

}}
`;


// Result: 


<

>

&



```