Core API — Halka Editor

Constructor

typescript

new HalkaEditor(root: HTMLElement, options?: {
  plugins?: HalkaPlugin[];
  shortcuts?: boolean;  // default true
  inline?: boolean;     // inline mode (no block wrapper)
})

Content

Name	Type	Description
`getHTML()`	`string`	Current inner HTML
`setHTML(html)`	Replace all content	Replace all content
`insertHTML(html)`	Insert at selection	Insert at selection
`insertText(text)`	Insert plain text	Insert plain text

Text formatting

Apply semantic inline formatting and block types. Clear formatting removes tags; it does not remove inline styles.

Name	Type	Description
`toggleInlineFormat(format)`	bold, italic, underline, code, strikethrough, sub, sup	bold, italic, underline, code, strikethrough, sub, sup
`toggleBlockFormat(format)`	h1, h2, h3, blockquote, pre, p	h1, h2, h3, blockquote, pre, p
`transforms.clearFormatting()`	Remove semantic tags (strong, em, u, code, etc.)	Remove semantic tags (strong, em, u, code, etc.)
`hasFormat(format)`	`boolean`	Check active format

Collapsed cursor inside a format + toggle turns format off for the next typed characters only (existing text is unchanged)
Collapsed cursor outside a format sets a pending format — typed characters stay wrapped until toggled off
No zero-width spaces or empty tags on toggle; DOM updates when you type
Built-in shortcuts: Mod+B (bold), Mod+I (italic), Mod+U (underline)

typescript

editor.toggleInlineFormat('bold');
editor.toggleBlockFormat('h2');
editor.transforms.clearFormatting();

Inline & block styles

Colors, font family, font size, and text alignment via CSS. clearStyles() removes style attributes only.

Name	Type	Description
`setInlineStyle(prop, value?)`	Apply or remove inline CSS on selection	Apply or remove inline CSS on selection
`setBlockStyle(prop, value?)`	Apply or remove block CSS on current block	Apply or remove block CSS on current block
`clearStyles()`	Remove style attributes in scope; unwrap empty spans	Remove style attributes in scope; unwrap empty spans
`getStyle(property)`	Computed style at selection	Computed style at selection

If a span already wraps the selection, inline style is updated in place
Collapsed caret with font-size or font-family sets a pending style — typed text is wrapped in a styled span
Color and background-color at a collapsed caret apply to the current block (not pending)
Removing the only style on a span unwraps it entirely

typescript

editor.setInlineStyle('color', '#e11d48');
editor.setBlockStyle('text-align', 'center');
editor.clearStyles();

clearStyles vs clearFormatting

clearStyles() — collapsed: current block; range: selection root. Finds all [style] elements, removes attributes, unwraps empty spans, then normalizes.

clearFormatting() — removes semantic tags (strong, em, u, code, etc.) without touching style attributes.

Selection

Access via editor.selection. Selection is saved on blur and restored before operations automatically.

Name	Type	Description
`getRange() / setSelection(range)`	Get or set DOM Range	Get or set DOM Range
`selection.preserveSelection(cb)`	Mutate DOM, restore selection	Mutate DOM, restore selection
`selection.isAtBlockStart() / isAtBlockEnd()`	`boolean`	Block boundaries

Block delete

When the cursor is at a block boundary, Backspace and Delete merge or remove blocks instead of only deleting characters. This is built into the core input handler — no API to call.

Backspace at the start of a block merges with the previous block
Delete at the end of a block merges with the next block
Empty blocks are removed when appropriate
Disabled in inline mode (inline: true)

Inline mode

Pass inline: true for compact single-line-style editing (footnotes, dialog fields). The editor root has no block wrapper; block formatting and block delete are disabled.

typescript

const editor = new HalkaEditor(root, { inline: true });

See Svelte UI for the in-repo InlineEditor component built on this mode.

Query & transforms

Name	Type	Description
`query.isActive(tag)`	`boolean`	Format active at cursor
`query.getCurrentBlock()`	Current block element	Current block element
`query.findClosest(tag)`	Nearest ancestor with tag	Nearest ancestor with tag
`transforms.toggleMark(tag)`	Toggle inline wrapper	Toggle inline wrapper
`transforms.wrap / unwrap(tag)`	Wrap or unwrap selection	Wrap or unwrap selection

Built-in shortcuts

Enabled by default (shortcuts: true). Plugin shortcuts are documented on each plugin page.

Shortcut	Action
`Mod+B`	Toggle bold
`Mod+I`	Toggle italic
`Mod+U`	Toggle underline

Transactions & events

typescript

editor.runTransaction(() => {
  // DOM mutations — auto-normalizes and emits change
});

editor.on('change', (html) => { /* save */ });
editor.on('formatChange', () => { /* toolbar */ });