This page is generated from HOOKS.md in the Typography Stylist source. Edit it there — edits made here are kept, but they stop this page from being updated until the conflict is resolved.
The window.typostHooks System
Typography Stylist provides a lightweight action/filter system on window.typostHooks that mirrors WordPress PHP hooks. It is available in both the inline editor (block-editor.js) and the Typography Stylist block (edit.js).
// Actions — execute callbacks, no return value
window.typostHooks.addAction(hookName, callback, priority);
window.typostHooks.doAction(hookName, ...args);
window.typostHooks.removeAction(hookName, callback);
// Filters — execute callbacks, return modified value
window.typostHooks.addFilter(hookName, callback, priority);
window.typostHooks.applyFilters(hookName, value, ...args);
window.typostHooks.removeFilter(hookName, callback);
Parameters:
hookName(string) — The hook name to register or fire/removecallback(function) — The function to execute. Must be a named or stored reference for removalpriority(number, optional) — Execution order, lower runs first (default: 10)
Removing hooks: To remove a callback, you must pass the same function reference that was used when adding it. Anonymous functions cannot be removed — store the callback in a variable first:
// Store the callback so it can be removed later
var myFilter = function(state, editorType) {
if (editorType === 'inline') {
state.customField = 'value';
}
return state;
};
window.typostHooks.addFilter('typost_current_editor_state', myFilter, 10);
// Later, to clean up:
window.typostHooks.removeFilter('typost_current_editor_state', myFilter);
Container lifecycle: Each hook point renders a <div class="typost-hook-point" data-hook="..."> and fires its action once per container mount — actions do not re-fire on ordinary editor re-renders, so render your UI once and manage its own state from there. The font-dependent hook points (typost_weight_control, typost_inline_after_font_controls, typost_qft_after_font_controls, typost_inspector_after_font_weight) are keyed to the active font: when the font changes, the old container (and everything you rendered into it) is destroyed, a fresh container mounts, and the action fires again with the new state. Don’t cache references to these containers across font changes.
Inline Editor Hook Points
These hooks fire inside the inline editor modal (the “T” toolbar button popover). Each receives a container DOM element and the editor’s current state.
| Hook Name | Location | Typical Use |
|---|---|---|
typost_inline_modal_top | After sticky notice, before font controls | Paragraph styles dropdown |
typost_inline_after_font_controls | After font weight selector | Variable font axes |
typost_inline_before_features | Before “Individual Features” section | Glyphs panel |
typost_inline_after_features | After feature toggle panels | Additional feature sections |
typost_inline_modal_bottom | Before action buttons | Custom actions |
window.typostHooks.addAction('typost_inline_modal_top', function(containerEl, state) {
// containerEl is a <div> — render your UI into it
// state contains: selectedFont, selectedFontId, selectedFontWeight,
// selectedFeatures, letterSpacing, lineHeight, etc.
}, 10);
Quick Feature Toggle Hook Points
These hooks fire inside the Typography Stylist block’s Quick Feature Toggle popover (appears when text is selected within the block).
| Hook Name | Location | Typical Use |
|---|---|---|
typost_qft_modal_top | After drag notice | Paragraph styles dropdown |
typost_qft_after_font_controls | After font weight | Variable font axes |
typost_qft_before_features | Before feature summary | Glyphs panel |
typost_qft_after_features | After feature toggles | Additional sections |
window.typostHooks.addAction('typost_qft_modal_top', function(containerEl, state) {
// state contains: fontId, fontWeight, fontSize, letterSpacing,
// lineHeight, features, etc.
}, 10);
The typost_qft_after_font_controls state also includes inlineFontFamilyAtSelection (the numeric font ID of an inline font at the current selection, if any) so extensions can prefer the inline font over the block-level fontId.
Since 2.2.2 the typost_weight_control and typost_qft_after_font_controls states also include fontVariationSettings (string) — the data-font-variation-settings value of the innermost styled span at the current selection, falling back to the block attribute, '' when neither is set. The inspector-side hook states (typost_weight_control in the sidebar, typost_inspector_after_font_weight) carry the block attribute. Extensions should initialize axis controls from this instead of walking the DOM selection, which fails in an iframed editor canvas.
Inspector Controls Hook Points
These hooks fire inside the Typography Stylist block’s sidebar Inspector Controls.
| Hook Name | Location | Typical Use |
|---|---|---|
typost_inspector_top | Before all panels (top of sidebar) | Paragraph styles dropdown |
typost_inspector_after_font_weight | After Font Weight panel | Variable font axes panel |
typost_inspector_before_features | Before OpenType Features panel | Glyphs panel |
typost_inspector_after_features | After OpenType Features panel | Additional feature panels |
window.typostHooks.addAction('typost_inspector_after_font_weight', function(containerEl, state) {
// state contains: fontId, features
}, 10);
Block Toolbar Buttons
Since 2.3.0. The other hook points hand you a container element to render into; this one is a filter returning descriptors, because a toolbar button rendered from a foreign React root would sit outside the toolbar’s roving tabindex and break keyboard navigation. Core renders your descriptor as a real ToolbarButton.
Buttons appear next to the Typography Stylist button — in the Typography Stylist block’s toolbar (qft) and, for rich text blocks, in the inline format toolbar (inline).
window.typostHooks.addFilter('typost_editor_toolbar_buttons', function(buttons, editor) {
return buttons.concat([{
id: 'my-panel', // required, unique — used as the React key
icon: MyIconComponent, // component or dashicon name
label: 'My Panel', // tooltip + accessible name
isActive: false, // optional pressed state
editors: ['qft'], // optional; omit to appear in both editors
onClick: function(context) { openMyPanel(context); },
}]);
}, 10);
// Register during script load. If your extension registers later (async or
// conditional loading), tell the editors to re-render:
window.typostHooks.doAction('typost_editor_toolbar_buttons_changed');
Descriptors without an id or a callable onClick are dropped.
The click context carries everything the panel needs, because no host modal was opened to gather it:
| Field | qft | inline |
|---|---|---|
source | 'qft' | 'inline' |
clientId | block client ID | — |
capturedSelection | {start, end, text, length} or null | — |
savedSelectionStart / savedSelectionEnd | — | offsets, or null |
selectedText | selected text ('' when none) | selected text ('' when none) |
state | resolved editor state | resolved editor state |
accessibility | — | word-boundary state (see below) |
reopenHost | false | false |
context.state carries two style ids: paragraphStyleId is the style on the block (or, in the inline editor, at the selection), and selectionParagraphStyleId (since 2.3.0) is the data-style-id of the span that covers the whole selected text, 0 when no single style does (a style over part of the selection does not count). In the inline editor the two are the same value. A panel that applies to a selection should treat the second as “active”; the block’s style says nothing about the selected words.
typost_extension_panel_closed (since 2.3.0, typostHooks action, (source, { range, reopenHost })). Opening a second Modal from inside the inline editor’s modal makes WordPress close the inline modal. A panel launched from inside it fires this action when it closes so the inline modal reopens where the author was; range is the host’s saved selection ({ start, end }) as received from the typost_inline_modal_top / typost_inline_modal_opened hook state, and reopenHost: false means “do not reopen” (launched from the toolbar). typost_glyphs_panel_closed is the older, Glyphs-specific name for the same contract and keeps working.
typost-paragraph-style-apply-cancelled (since 2.3.0, document CustomEvent). Both editors ask before a paragraph style replaces styling the selected text already carries. When the author cancels, the editor fires this event with detail: { source: 'inline' | 'qft', paragraphStyleId } instead of applying, so the panel that dispatched typost-apply-block-properties can put its previous state back. Listen for it if your UI shows the applied style before the apply resolves.
context.accessibility (inline editor) carries the word-boundary notice the editor’s own modal would have shown, because a panel opened from the toolbar bypasses that modal entirely:
{
wordBoundaryWarning: '', // '' when the selection is fine, or off in Settings → Accessibility
canConvert: false, // whether the conversion is offered as the fix
convertBlockedMessage: '', // why it isn't: a lock, a restrictive parent, or (since the
// notice recommends converting) a block type with no mapping
settingsUrl: '…&tab=accessibility',
}
If your panel can create inline spans, show this warning. To offer the fix, dispatch the conversion — it replaces the block, so close your UI at the same time:
document.dispatchEvent(new CustomEvent('typost-convert-to-block', {
detail: { source: 'inline', clientId: context.clientId || null },
}));
Two more details matter:
- Use
context.state, not thetypost_current_editor_statefilter. That filter is only answered by the block holding the caret, so a block selected from List View would report the default font. The context state is resolved for the block whose toolbar was clicked. reopenHost: falsemeans no host modal was open. If your panel closes by firingtypost_glyphs_panel_closed, pass the flag through so the editors do not open a modal the author never asked for:
window.typostHooks.doAction('typost_glyphs_panel_closed', source, {
clientId: context.clientId,
range: context.range,
reopenHost: context.reopenHost !== false,
});
Insertion still goes through the typost-insert-content event exactly as it does from inside the editor panels — core has already recorded the selection from the context, so inserted text lands at the selection and successive insertions advance the caret.
Weight Control Replacement
typost_weight_control (Filter)
Filter that determines whether the standard weight dropdown should be replaced by a custom control. Return 'default' for the normal dropdown, 'hidden' to suppress the weight control entirely (no wrapper section, no hook container — used e.g. for variable fonts without a wght axis), or any other value (e.g., 'variable') to replace it with a hook container.
window.typostHooks.addFilter('typost_weight_control', function(type, fontId) {
// Return 'variable' to replace the dropdown with a custom control
if (fontHasVariableWeightAxis(fontId)) {
return 'variable';
}
// Return 'hidden' to render no weight control at all
if (fontShouldHideWeights(fontId)) {
return 'hidden';
}
return type; // 'default' = normal dropdown
}, 10);
Parameters:
type(string) — Current control type ('default'initially)fontId(number) — The active font’s numeric ID
Recognized return values: 'default' (normal dropdown), 'hidden' (no control rendered), anything else (hook container fired via the action below).
Checked in three locations: inline editor, Quick Feature Toggle, Inspector Controls.
typost_weight_control (Action)
When the filter returns a non-default value, the core renders a hook container (<div data-hook="typost_weight_control">) and fires this action. Render your custom weight control into the container.
window.typostHooks.addAction('typost_weight_control', function(containerEl, state) {
// Render a custom weight slider into containerEl
// state varies by editor:
// inline: { selectedFontId, fontWeight, selectedFont, ... }
// qft: { fontId, fontWeight, inlineFontFamily, inlineFontWeight, ... }
// inspector: { fontId, fontWeight }
}, 10);
Convert to Block Capability
typost_can_convert_to_block (Filter)
Since 2.3.0.
Filters whether the inline editor offers Convert to Typography Stylist Block for the current selection. The core answer is computed each time the inline modal opens, from three facts:
- The selected block is a
core/headingorcore/paragraph(nothing else has a conversion mapping). canRemoveBlock()is true — the block is not locked, and not inside a locked template or pattern.canInsertBlockType( 'typost/block', rootClientId )is true — the parent block allowstypost/blockamong its inner blocks.
Point 3 is the one that surprises people. A block that restricts its children with allowedBlocks will refuse a Typography Stylist block unless it lists one, so the conversion is genuinely impossible there. When that happens the modal now says so and names the parent block, rather than silently rendering nothing.
If your theme or plugin has a container block that should accept Typography Stylist blocks, add typost/block to that block’s allowedBlocks list — that is the real fix, and it also makes the block insertable by hand. Use this filter only when the capability genuinely needs to be decided elsewhere.
window.typostHooks.addFilter('typost_can_convert_to_block', function(canConvert, context) {
// context = { clientId, blockName, rootClientId, reason, parentTitle }
if (context.reason === 'parent' && context.parentTitle === 'My Container') {
return true; // this container handles typost/block itself
}
return canConvert;
}, 10);
Parameters:
canConvert(boolean) — Core’s answer.context.clientId(string) — Selected block’s client ID.context.blockName(string) — Selected block’s name.context.rootClientId(string) — Parent block’s client ID (''at the top level).context.reason(string) — Why core said no:'none'(it said yes),'unsupported','already','locked','parent'.context.parentTitle(string) — Parent block’s human title, or''.
Returning true clears the reason, so no stale explanation is shown next to a working button. Returning false hides the action without an explanation — if you want the user told why, keep the capability and disable your own container instead.
Admin jQuery Events
typost:font-saved
jQuery event triggered on $(document) after a font’s settings are saved in the admin. Use this to save extension-specific data that was injected into the font edit form.
$(document).on('typost:font-saved', function(e, data) {
// data.fontId — Font string ID (e.g., 'kit-123-inter')
// data.type — Font type: 'uploaded', 'adobe', or 'manual'
// data.$card — jQuery element of the font card
// data.waitUntil — Since 2.1.0: register a promise the post-save refresh waits on
var request = saveMyExtensionData(data.fontId, data.type); // e.g. $.ajax(...)
if (typeof data.waitUntil === 'function') {
data.waitUntil(Promise.resolve(request));
}
});
waitUntil (since 2.1.0): after a font save, core refreshes the font list in place over the REST API (before 2.3 it reloaded the whole page). If your extension saves its own data asynchronously on this event, register the request via data.waitUntil(promise) — core waits for all registered promises to settle (with a 5-second cap) before refreshing, instead of the old fixed 1500 ms timeout your request had to race. Because the refreshed font-list fragment is server-rendered through the same template functions as the page itself, data your extension saved here is reflected in the swapped-in markup exactly as it would be after a reload.
typost:fonts-added
jQuery event triggered on $(document) after new fonts are successfully added in the admin — a webfont kit ZIP upload or an Adobe Fonts kit. Use this to post-process brand-new entries before the font list refreshes in place (e.g. the bundled Variable Fonts module auto-detects fvar axes here).
$(document).on('typost:fonts-added', function(e, data) {
// data.type — How the fonts were added: 'uploaded' or 'adobe'
// data.fonts — Array of the new font entries as returned by the REST endpoint
// (each has id, font_id, and source-specific fields like
// css_content for uploads or css_url/font_family for Adobe)
// data.$message — jQuery element of the form's message area (append notices here)
// data.waitUntil — Register a promise the post-add refresh waits on
var work = processNewFonts(data.fonts); // e.g. detection + $.ajax saves
if (typeof data.waitUntil === 'function') {
data.waitUntil(work);
}
});
waitUntil: same contract as typost:font-saved, but with a 15-second cap — listeners here may download and parse font binaries, which takes longer than a settings save. The refresh also waits a minimum delay so the success notice stays readable.
typost:font-list-refreshed
jQuery event triggered on $(document) after core swaps the Custom Fonts list in place (after a font save, add or delete — since 2.3 the page does not reload). The new cards are in the DOM and typostAdmin holds the refreshed data. Run here any setup your extension does on the font cards at page load; the old markup, and anything you set on it, is gone. Since 2.3.1.
$(document).on('typost:font-list-refreshed', function(e, data) {
// data.region — the #typost-fonts-region element that was re-rendered
$(data.region).find('.my-extension-font-options').each(initMyOptions);
});
The bundled Variable Fonts module uses this to hide the weight checkboxes again for fonts set to “hide weights”, and the Detect axes button for Adobe and custom fonts when the browser font parser is not available.
Lifecycle Hooks
typost_inline_modal_opened
Fired when the inline editor modal opens.
window.typostHooks.addAction('typost_inline_modal_opened', function(state) {
// state is the full editor state at time of opening
// Use this to refresh data, re-render panels, etc.
}, 10);
typost_inline_modal_closed
Fired when the inline editor modal closes.
window.typostHooks.addAction('typost_inline_modal_closed', function() {
// Clean up any event listeners or timers
}, 10);
State Communication
Reading Editor State
Use the typost_current_editor_state filter to read the current editor state:
// Get state from whichever editor is active
var state = window.typostHooks.applyFilters('typost_current_editor_state', {}, 'inline');
// or
var state = window.typostHooks.applyFilters('typost_current_editor_state', {}, 'qft');
The returned state object includes:
- Inline editor:
editorType,fontId,explicitFontId,fontWeight,explicitFontWeight,selectionFontWeight,fontStyle,explicitFontStyle,textCase,fakeSmallCaps,fontSize,fontSizeMin,fontSizePreferred,fontSizeMax,letterSpacing,lineHeight,features,paragraphStyleId,fontVariationSettings - QFT editor:
editorType,fontId,explicitFontId,fontWeight,explicitFontWeight,selectionFontWeight,fontStyle,explicitFontStyle,fontSize,fontSizeMin,fontSizePreferred,fontSizeMax,letterSpacing,lineHeight,features,paragraphStyleId,selectionParagraphStyleId,hasSelection,selection,block,fontVariationSettings,initialHang,textCase,fakeSmallCaps,layeredConfigId,content,tagName
Since 2.3.4 the QFT state also tells a consumer when text is selected in the block (#303). hasSelection is true when the Quick Feature Toggles apply to an expanded range (the live selection, or the one captured when the modal opened). selection is then an editor state for that text alone: fontId/explicitFontId, fontWeight/explicitFontWeight, fontStyle/explicitFontStyle, fontSize, fontSizeMin, fontSizePreferred, fontSizeMax, fitMaxSize, letterSpacing, lineHeight, features, fontVariationSettings and, since 2.3.5 (#309), textCase/fakeSmallCaps, each the value set on the selected text (its spans, or the paragraph style of a data-style-id span), never the block’s or the theme’s; 0, '', 'inherit', [] or true (fakeSmallCaps) when the text sets none. It has no initialHang (block-only). With a caret only, hasSelection is false and selection is null. The bundled Paragraph Styles panel in the QFT modal captures, diffs and applies on selection when hasSelection is true; the Inspector’s panel always uses the block-level keys. block holds the block attributes’ own explicitFontId, explicitFontWeight and explicitFontStyle: the top-level explicit keys take these from the selected text first, so a panel that works on the whole block reads them from block instead.
Since 2.3.0 both editors report the font style on two channels ('' inherit, 'normal', 'italic', or 'oblique' — the built-in Font Style controls only offer the first three, but 'oblique' set by an extension through the apply event round-trips the full pipeline: span serialization, state reporting, and paragraph-style persistence/CSS). fontStyle is the rendered style at the selection — text italicized by an enclosing <em>/<i> reports 'italic' even without its own setting; use it to render the right face (previews, the Glyphs panel’s face pick). explicitFontStyle is only what was set — a data-fontstyle span, the popover’s Font Style choice, or the block attribute — and is what consumers that persist the value must read: the bundled Paragraph Styles module captures it into saved styles, so semantic emphasis can’t be baked into a style whose CSS could neither reproduce nor reset it.
Since 2.3.2 the font weight also has two channels. fontWeight is the weight rendering at the selection: a weight span, the paragraph style on the selected text (its data-style-id; a <strong> inside the style span still renders bold), <strong> (QFT), then the block’s or the theme’s weight. Use it to draw previews and pick the face. selectionFontWeight is only the weight stored on the selected text, and '' when the text inherits its weight. A data-fontweight counts as stored only when it renders: on a span with no data-style-id, or with its own inline font-weight (no CSS reads the attribute, and a span under a paragraph style can keep it without the inline declaration). A consumer that writes a span into the selection (the Glyphs panel’s insertions) writes only this one: an inherited weight written inline overrides the style’s class and stays behind when the style or the block weight changes later (#254).
Since 2.3.3 the font and the weight each have an explicit channel, like explicitFontStyle. fontId is the font rendering at the selection: for text with no font of its own, it is the plugin font the theme gives the text (the Glyphs panel browses that font). explicitFontId is only a font set on the text: a data-font-id span, the font of the paragraph style on the selected text, the popover’s font choice, or the block attribute, and 0 when the text inherits its font. explicitFontWeight is only a weight set on the text: a stored span weight, the weight the author picked in the popover, the weight of the paragraph style on the selected text, or (QFT) the block attribute; '' when the text inherits its weight from the block, the theme or <strong>. The QFT state never reports '': the block’s fontWeight attribute always has a value (default '400'), and the block writes it. Consumers that persist values read these two: the bundled Paragraph Styles module compares, saves and detaches only them, so the theme’s font and weight are not written into a style or onto a span (#278). explicitFontWeight differs from selectionFontWeight: it includes the popover pick, the style’s weight and the block attribute. A provider that does not report the explicit keys (an older version, an extension’s editor) is read through fontId and fontWeight, as before.
The paragraphStyleId field contains the active paragraph style ID (integer), or 0 if no style is applied. Extensions can use this to detect whether the current selection/block is associated with a saved style.
The layeredConfigId field contains the active layered font configuration ID (integer), or 0 if no layered font is applied. The content and tagName fields provide the block’s current text content (HTML) and heading tag (e.g., h2) for use by extensions that need to render previews.
Since 2.1.0 the QFT/inspector state also includes animationConfigId (integer, 0 when unset) — the active animation configuration ID used by the Animations extension.
Since 2.3.2 the QFT/inspector state also includes initialHang (number in em, 0 when off): how far the block moves its first letter into the margin (First Letter Hang). The inline editor does not report it, because the hang works through ::first-letter, which cannot reach an inline span. Treat an absent key as “not supported here”, not as 0. The per-line values of a fit-to-width block are content, like its line sizes, and are not in the state.
Since 2.3.3 both editors report textCase ('' Default, 'none' Normal, 'uppercase', 'lowercase', 'capitalize', 'small-caps', or 'all-small-caps') and fakeSmallCaps (boolean, true when unset; only meaningful with the two small caps values). The QFT/inspector state reports the block’s setting at the top level; the case of the selected text is in selection (since 2.3.5). The inline editor reports the case stored on the selected span (data-textcase / data-fakesmallcaps), or the popover’s choice while it is open; a theme’s case or a case that only comes from a paragraph style’s class is not the span’s own and reports ''. Treat an absent key (an older version) as “not supported here”.
Writing Editor State
Dispatch a typost-apply-block-properties CustomEvent to programmatically apply properties to the editor. This is a generic mechanism — any extension can use it to set block attributes and inline editor state.
document.dispatchEvent(new CustomEvent('typost-apply-block-properties', {
detail: {
properties: {
fontId: 12,
fontWeight: '700',
fontStyle: 'italic', // Optional (since 2.3.0): '' inherit / 'normal' / 'italic' / 'oblique'
letterSpacing: 50,
features: ['liga', 'dlig', 'ss01'],
fontVariationSettings: '"wght" 700, "wdth" 100', // Optional: variable font axes
initialHang: 0.15, // Optional (since 2.3.2): first letter hang in em; 'qft'/'inspector' only
textCase: 'uppercase', // Optional (since 2.3.3): case; '' Default, 'none' Normal, …
fakeSmallCaps: false, // Optional (since 2.3.3): with 'small-caps'/'all-small-caps' only
},
source: 'inline', // or 'qft' or 'inspector'
// Optional: class-based styling (used by the bundled Paragraph Styles module)
paragraphStyleId: 3, // Integer style ID
styleClass: 'typost-ps-3', // CSS class for Typography Stylist blocks
// Optional (since 2.3.0): scope the paragraph style to the selected
// text instead of the whole block. Omit for block-level, the default.
applyTo: 'selection',
// Optional (since 2.3.4): the style was just saved from the
// selected text; skips the "replaces that styling" question when
// the selection has one set of values
savedFromSelection: true,
// Optional (inline source only, since 2.1.0): animation config ID —
// written to the span as data-animation-id (Animations extension)
animationId: 2,
},
}));
Each editor listens for this event and applies properties matching its source. The inline editor triggers a debounced apply; the QFT/inspector editors set block attributes directly, with one exception: a 'qft' event’s fontVariationSettings is applied to the current text selection as an inline <span class="typost-styled" data-font-variation-settings="..."> (falling back to the block attribute when the caret isn’t inside styled text) — the 'inspector' source remains block-level. Only fields present in properties are updated — missing fields preserve current state.
fontVariationSettings values are validated on every apply path (each comma-separated entry must match the "axis" number format); an invalid value is treated as empty rather than partially applied, so it clears the property instead of reaching a style string.
Targeting (since 2.2.2): every Typography Stylist block registers this listener, so the event is handled only by the block it targets — for source: 'qft' that is the block whose Quick Feature Toggles modal is open, and for source: 'inspector' the currently selected block. Previously every mounted block applied the event.
Note: This event was renamed from typost-apply-paragraph-style in v2.0.0 to reflect its generic purpose.
Class-based styling fields:
paragraphStyleId— When set (non-zero), the inline editor storesdata-style-idon the span and skips inlinestyle(CSS class provides rendering). Data attributes (data-font-id,data-features, etc.) are still set for font detection.styleClass— When set, the Typography Stylist block stores this as a block attribute. Thesave()function outputs the class on the element and skips inline styles. The editor always renders inline styles for visual preview regardless ofstyleClass.applyTo— Since 2.3.0.'selection'makes a Typography Stylist block wrap the selected text in a<span class="typost-styled" data-style-id="N">instead of writing block attributes, so styling one word leaves its neighbours alone. Send it only when you know a selection was captured; with a collapsed caret (or any other value) the apply stays block-level, which is what a paragraph style normally means. AparagraphStyleIdof0withapplyTo: 'selection'detaches the style from the selection: since 2.3.4 the block writes the style’s values onto the text in place of itsdata-style-id(as data attributes plus inline declarations, sizes in the style’s unit), so the text keeps its look; a value the span declares itself stays. Before 2.3.4 it only removed the attribute. With no style span in the selection it does nothing. The Inspector’s panel does not send it; since 2.3.4 the Quick Feature Toggles’ panel does when text is selected (#303).savedFromSelection— Since 2.3.4.truewhen the style was just built from the selected text’s values (the panel’s Save, Save as New, and the re-apply after Update Style). Both editors normally ask before a style replaces styling the selected text carries (typost-paragraph-style-apply-cancelledbelow); with this flag they skip the question when every selected character has the same values, because the style was built from them. The flag alone never skips it: each editor checks the selection itself, and a selection with more than one set of values still asks. Since 2.3.5 (#309) the case counts like the other values: the Quick Feature Toggles capture it, so a span with a case of its own no longer makes the block ask when the selection has one set of values.
Extension config references (numeric block attributes):
properties.layeredConfigId— Layered Fonts extension. Saved asdata-layered-config-idon the visual heading.properties.animationConfigId— Since 2.1.0. Animations extension. Saved asdata-animation-config-idon the visual (aria-hidden) heading only; the screen-reader heading is never touched. The inline format additionally allows adata-animation-idattribute ontypost-styledspans. Extensions consume these via arender_blockfilter on the frontend.
Inserting Content
Dispatch a typost-insert-content CustomEvent to insert text at the cursor (or replace the current selection) in the editor, optionally wrapping the inserted text in a <span class="typost-styled"> element. This is the generic insertion bridge used by extensions like the Glyphs Panel.
document.dispatchEvent(new CustomEvent('typost-insert-content', {
detail: {
source: 'inline', // or 'qft' — must match the editor being targeted
text: 'A', // Character(s) to insert (max 50 chars; e.g., 'fi' for a ligature)
// Optional: wrap the inserted text in a typost-styled span.
// Omit (or pass null) to insert plain text that inherits surrounding formatting.
attributes: {
'data-features': 'ss01',
'data-font-id': '12',
'style': 'font-feature-settings: "ss01" 1; font-family: var(--font-12)',
},
// Optional targeting (recommended): capture these from the hook state
// snapshot when your UI launches. They keep insertion working after the
// host editor modal closes (which resets its internal selection state).
clientId: 'abc-123', // QFT only: block clientId from the hook snapshot
range: { start: 0, end: 10 }, // Fallback text range to insert into/replace
// Optional (since 2.2.2): swap semantics — after inserting, the
// editor keeps the inserted text SELECTED instead of collapsing the
// caret, so the extension's next insertion replaces the same text.
// Use for pick-a-variant UIs (e.g. the Glyphs Panel alternates view);
// omit for sequence insertion.
swap: true,
},
}));
Behavior:
- Selection vs cursor: If text is selected, the insertion replaces it; with a collapsed cursor, the text is inserted in place. Both editors fall back to selection bounds captured before their modal stole focus (inline: saved selection state; QFT:
capturedSelection), then todetail.range. If no selection information exists in the QFT context, the text is appended to the end of the block content. - Targeting: Every Typography Stylist block listens for this event. When
detail.clientIdis set, only the matching block handles it; without it, only the block whose QFT popover is currently open does. In the inline editor, only the live (mounted) format component instance handles the event. - Format continuity: The inserted text copies the formats of the character it replaces (or, for a collapsed cursor, the preceding character), so inserting inside styled text behaves like typing. When
attributesis provided, the typost format on just the inserted range is replaced with those attributes — include any context features indata-featuresyou want preserved on the inserted text. - Styling preservation (since 2.2.0): When
attributesreplaces an existing typost format, the replaced format’s other styling —data-fontsize/data-fontsize-min/-preferred/-max,data-letterspacing,data-lineheight,data-fontweight, and theirstyledeclarations — is merged into the new span automatically (your attributes always win per-property;data-features,data-feature-settings,data-font, anddata-font-idare never inherited, andfont-variation-settingscarries over only whendata-font-idis unchanged). Extensions therefore only need to send what they own. - Caret: After insertion the caret collapses to the end of the inserted text — unless
detail.swapis set (since 2.2.2), in which case the inserted text stays selected so the extension’s next insertion replaces it. - Clearing inherited features (since 2.2.2): Because a plain (
attributes: null) insertion inherits the replaced character’s formats, it can never remove a feature — a base-glyph swap over an alternate would re-inherit the alternate. To restore a plain form, send anattributesobject without feature keys (plus whatever font/weight you want kept): feature attributes are payload-owned in the merge, so the inherited alternate is dropped while sizing/spacing survive. - Frontend rendering: The
styleattribute carries the actual CSS (same convention as the editors’ own apply logic). Includedata-font-idwhen the inserted text uses a different font than its surroundings so the frontend@font-facedetection enqueues the font.
Availability: Handled by both the inline editor (format type typost/features) and the Typography Stylist block.
Indexed alternates (data-feature-settings): The comma-tag data-features format implies "tag" 1 and cannot express indexed alternates like font-feature-settings: "salt" 2. For those, set the raw value in a data-feature-settings attribute (registered on the typost/features format) and put the full value in style. List any plain index-1 tags in data-features as usual. The inline editor preserves data-feature-settings when other properties are re-applied to the span, and appends newly toggled tags that aren’t already present in the raw value. A toggle does override the raw value’s own clauses for its tag (since 2.3): enabling a tag drops a "tag" 0 clause (an indexed "salt" 2 is kept as the more specific setting), and disabling a tag drops every clause for it — see pruneRawFeatureSettings() in utils.js, also exposed on window.typostSharedUtils.
The same raw attribute is how an insertion turns a feature off on the span it creates — font-feature-settings: "swsh" 0 — which is what the Glyphs Panel’s base cell writes when the alternate it replaces comes from a block-level feature or a paragraph style (an inline-format reset alone would leave the alternate active through CSS inheritance). Put the "tag" 0 clauses in data-feature-settings, list only the tags that stay on in data-features, and mirror the full value in style.