Docs

Widgets

Every attribute, property, theme option and event of <typomat-preview>, with its values and default.

For how to use them, see the preview widgets guide. To see them working, see the widgets page.

HTML

<script src="https://engine.typomat.app/typomat/widget.js" async></script>
<typomat-preview></typomat-preview>

Attributes

All are optional. A value the widget can't use falls back to the default, and removing an attribute does the same. Changes take effect at once. The theme attributes are below.

Attribute	Values	Default	Meaning
`variant`	`mini` or `full`	`mini`	A preset. `mini` is `line`; `full` is `line grid paragraph parameters`, and `request` too with `show-request`. `show` wins when given.
`show`	Pieces, space-separated: `line waterfall grid paragraph parameters request`	The variant's	What shows, top to bottom, each once. A word it doesn't know is skipped and reported in `ignored`. If it knows none, the variant's pieces show.
`show-request`	Present, or `"false"`	Off	Adds `request` to the `full` preset.
`text`	Up to 120 characters	`Handgloves`	The line's and the waterfall's text. Line breaks and control characters become spaces. Blank gives the default.
`size`	10–160 pixels	32 with the `mini` preset, otherwise picked from the width (40–128)	The line's size. The line shrinks to fit the widget, and never grows past this.
`sizes`	4 to 8 numbers, each 8–200 pixels, separated by spaces or commas	`14 24 48 96`	The waterfall's sizes, a row each. Fewer than four numbers gives the default; past eight, the rest are dropped.
`groups`	Any of `letters figures accented extended`	All four	The grid's tabs, in this order. One group shows no tabs.
`paragraph`	Up to 600 characters	A pangram	The paragraph's text. Line breaks and control characters become spaces.
`lines`	1–20	5	The paragraph's height, in lines. Longer text is cut off; typed text scrolls to keep the caret in view.
`align`	`start` or `center`	`start`	For the line, the waterfall and the paragraph.
`editable`	Present, `line`, `paragraph`, `line paragraph`, or `"false"`	Off	Lets visitors type into the line or the paragraph. Present on its own means the line.
`placeholder`	Up to 120 characters	None	Shown muted in an empty editable line, and gone with the first keystroke. Without one, the line starts with `text`.
`controls`	`size`, `theme`, or `size theme`	None	Controls for the visitor: a slider for the line's size, and a light/dark switch.
`parameters`	A JSON object	The engine's defaults	The parameters, by name, as `POST /api/v1/fonts` takes them. Broken JSON counts as none.
`param-<name>`	A number		One parameter, laid over `parameters`: `param-weight="120"`. Names ignore case and dashes, so `param-x-height` is `xHeight`.
`name`	Up to 64 characters	`Typomat Font`	The font name in the `request` piece's body. The API uses the same default.
`label`	Up to 120 characters	`Font preview`	The widget's name for screen readers, and the iframe's title.
`theme`	A JSON object		Every theme option at once, `dark` included. The theme attributes below are laid over it.

Properties

For your page's script. Each can be set before the script has loaded, and is picked up when it does.

Property	Takes	Meaning
`parameters`	An object, or a JSON string	Laid over the `parameters` and `param-*` attributes, so your script has the last word. Setting the `parameters` attribute again drops it.
`theme`	An object, or a JSON string	Laid over the `theme` attribute and the theme attributes. Setting the `theme` attribute again drops it.
`show`	A string, or an array of piece names	In place of the `show` attribute, until that attribute changes.

Theme

Each option is an attribute of its own, or a key of the theme JSON attribute or property. Order of precedence, last wins: the theme attribute, the theme attributes, the theme property.

Option	Values	Default	Meaning
`mode`	`light`, `dark` or `auto`	`light`	`auto` follows the visitor's system setting, and changes with it. Anything else is `light`.
`background`	A colour	`#FFFFFF` light, `#0A0A0A` dark	Behind everything. `transparent` lets your page show through.
`ink`	A colour	`#0A0A0A` light, `#FFFFFF` dark	The letters, the labels and the mark.
`accent`	A colour	`#1A2BFF` light, `#FFD400` dark	The current tab's underline, the selection, the Copy button and the size slider.
`muted`	A colour	`#6B6B6B` light, `#9A9A9A` dark	Notes, headings, the other tabs, the grid's rules and the placeholder.
`font`	A font-family list of up to 6 names	Typomat's own UI font	For the labels, tabs and notes, never the letters. Only fonts the visitor's device has, and generic families.
`radius`	0–48 pixels	8	The corners.
`padding`	0–64 pixels	16	The space inside the edge.
`dark`	An object of `background`, `ink`, `accent` and `muted`		Colours used only while the widget is dark. In the `theme` JSON or property only.

A colour: #rgb, #rgba, #rrggbb or #rrggbbaa; rgb(), rgba(), hsl() or hsla() with plain numbers, commas or spaces, and an optional alpha; or transparent. Up to 64 characters. Colour names, var() and calc() are ignored.
A font list: Up to six comma-separated names, each up to 48 letters, digits, spaces, dashes and underscores, quoted or not. One bad name drops the whole list. Generic families (serif, sans-serif, monospace, system-ui, ui-serif, ui-sans-serif, ui-monospace, ui-rounded, cursive) work, and system-ui, sans-serif is added at the end.
Pixels: A number, a string of one, or one ending in px: 12, "12", "12px". Other units give the default.
Which colours: light: the light defaults under your colours. dark: the dark defaults under your colours, then dark. auto follows the system: light as light, dark with only dark over the dark defaults. The visitor's light/dark switch (controls="theme") keeps your colours in your own mode and uses the defaults, and dark, in the other.

Pieces

The words show takes, top to bottom in the order given. variant="mini" is line; variant="full" is line grid paragraph parameters, with request after them given show-request.

Piece	Shows
`line`	One line of `text`, as large as `size` and the width allow.
`waterfall`	`text` at several sizes, a row each. A row too wide for the widget is drawn as large as fits, never cut.
`grid`	Every character, a group at a time, with tabs to switch.
`paragraph`	A wrapped paragraph, a fixed number of lines tall.
`parameters`	The parameters as the engine reads them: known names only, clamped to their ranges.
`request`	The JSON body `POST /api/v1/fonts` would get for them, with a Copy button.

typomat-status

A CustomEvent on the element, sent once the widget has its first settings and whenever what it reports changes. It doesn't bubble. Its detail has four arrays of strings:

Field	Lists
`unknown`	Parameter names that aren't Typomat's. Left out of the drawing and the request.
`invalid`	Parameters whose value isn't a number. Left out. If the `parameters` attribute is the text `[object Object]`, this starts with a hint: pass `JSON.stringify(...)` or set the property.
`missing`	Characters of your own `text` and `paragraph` that Typomat has no drawing for. Never anything a visitor typed.
`ignored`	Words in `show`, `groups`, `editable`, `controls` or `align` that mean nothing to the widget.

Limits

Text: The line and waterfall's text and the placeholder up to 120 characters, the paragraph up to 600, the name up to 64, the label up to 120. Longer is cut.
Parameters: The first 200 names. Values are clamped to each parameter's range.
One update: Everything the element sends at once, as JSON, up to 32,000 characters. A bigger one is dropped, and the widget keeps showing the last.
Height: Set by the widget, up to 4,000 pixels.

Content Security Policy

What a page with its own policy adds to it, and all it needs: the loader adds no style text to your page, so style-src needs nothing.

Content-Security-Policy

script-src https://engine.typomat.app;
frame-src https://engine.typomat.app;