TypeSafe HTML templates using TypeScript. No need to learn a template library.
npm install typed-html
HTML templates have never been this easy. Type safe using plain TypeScript with a minimal runtime footprint.
No need to learn a template language, if you know TypeScript, you're set.
This:
``typescript
// example.tsx
const item = 'item';
const icon = 'icon-add';
const ul =
;
typeof ul; // string
const button = ;
typeof button; // string
console.log(ul);
console.log(button);
`
Prints:
`html`
Install:
`bash`
npm install --save typed-html
Configure your TypeScript compiler for JSX:
`json`
{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "elements.createElement"
}
}
Although we're configuring the compiler to use React, this is not what is being used.
Instead, we redirect all jsx element to typed-html's elements.createElement.
Now create a \*.tsx file. For example: example.tsx with the following content:
`typescript
// example.tsx
import * as elements from 'typed-html';
const w = 'world';
const helloWorld =
Hello {w}
;typeof helloWorld; // => Just a string of course
`
However, the following piece of code will NOT compile:
`typescript`
; // => Error: Property 'foo' does not exist on type 'HtmlAnchorTag'
Typed HTML supports both NodeJS and (since 2.0) the browser.
For use in the browser, either load typed-html as a module, or use a bundler like webpack or rollup to bundle the package for you.
`ts`
// Direct ES import:
import * as elements from './node_modules/typed-html/dist/elements.js';
// OR, when using a bundler like rollup or webpack
import * as elements from 'typed-html';
All template scenarios are supported with plain TypeScript.
Conditional template with ?
`typescript`Random > 0.5: {Math.random() > .5 ? yes : 'no'}
Repeat a template with Array.map
`typescript`
const items = ['item', 'item2'];
;
{items.map(i =>
Want a helper template? Just call a function
`typescript`
function listItem(n: number) {
return
}
{[1, 2].map(listItem)}
#### Using a helper template like an element
Want a helper component? Create a function that implements CustomElementHandler and you can call it like an HTML element.
`typescript
import {Attributes, CustomElementHandler} from "typed-html"
function Button(attributes: Attributes | undefined, contents: string[]) {
return
Prints:
`html
`#### React-style children
It's possible to write React-style components as well. Consider the example below.
`typescript
import {Attributes, CustomElementHandler} from "typed-html"function Button({ children, ...attributes }: Attributes) {
return
;
}console.log();
`Prints:
`html
`Sanitization
Security is NOT a feature. This library does NOT sanitize.
`ts
const script = '';
const body = {script};
`Will result in:
`html
`If you need sanitization, you can use something like sanitize-html.
Supported HTML
All HTML elements and attributes are supported, except for the svg.
* Supported html elements: https://dev.w3.org/html5/html-author/#the-elements
* Supported html events: http://htmlcss.wikia.com/wiki/HTML5_Event_Attributes
Missing an element or attribute? Please create an issue or a PR to add it. It's easy to add.
$3
Void elements (elements without closing tags) are supported, however you should close them in TypeScript.
`typescript
const img =
; // => Error! JSX element 'img' has no corresponding closing tag.
` In the example above, closing the image tag is required for valid TSX code:
`typescript
const img =
; // => '
'
`See this code for a list of supported void elements.
$3
All HTML attributes support a string value, however some attributes also support a
number, Date or boolean(or absent value) type:`typescript
;
// =>
;
;
;
;const date = new Date('1914-12-20T08:00');
;
// =>
updated;
old;
// =>
`Custom elements
You can add custom elements by adding them to the intrinsic elements yourself:
`typescript
// MyCustomElements.d.tsdeclare namespace JSX {
interface CustomElement {
customAttribute?: string;
}
interface IntrinsicElements {
myCustomElement: CustomElement;
}
}
`Now you can use it:
`typescript
// UseCustomElement.ts
import * as elements from 'typed-html';const myElement =
console.log(myElement);
`This prints:
`html
`$3
Custom attribute names are already supported out-of-the-box for attributes with a dash (
-) in the name. For example: `typescript
`$3
As a browser is case insensitive when it comes to element and attribute names, it is common practice to use kebab case for this. However
is not allowed in TypeScript. Therefore typed-html will transform to .This transformation also works for custom attributes you define on a custom element yourself. For example:
`typescript
`Becomes
`html
` How this all works
The way this works is by using TypeScript's jsx support, but not for jsx/react interoperability. Instead, it defines the normal html tags as
IntrinsicElements in the JSX namespace.At runtime, the
elements.createElement function is called for every html tag. It simply converts the given element to a string with minimal overhead.This:
`typescript
{[1, 2].map(i => - {i}
)}
`Compiles to:
`javascript
elements.createElement("ol", { start: 2 }, [1, 2].map(function (li) {
return elements.createElement("li", null, li);
}));
`Which translates to:
`html
- 1
- 2
``