Skip to content
FrameworkJavaScript

Toolbar API: control the block toolbar

Control the block toolbar and its state.

Edit this page on GitHub

Reaching the editor instance

The methods below run on the editor you created with new Blok(). They are available once editor.isReady resolves.

TypeScript
// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Methods

toolbar.close(options?)

void

Close the toolbar with optional configuration.

When to use

Programmatically dismiss the block toolbar — e.g. after your custom action runs so the UI doesn't linger.

TypeScript
// Standard close. The next mousemove re-opens the toolbar: close() clears the
// hovered block and resets the hover dedup, so BlockHovered fires again.
editor.toolbar.close();

// Close and keep it closed while the pointer stays on the same block
// (skips the hover-state reset, so no BlockHovered is re-emitted for it).
editor.toolbar.close({ setExplicitlyClosed: false });

toolbar.open()

void

Open the toolbar.

When to use

Force the toolbar open for the current block; it normally appears on hover/focus, so use sparingly.

TypeScript
editor.toolbar.open();

toolbar.toggleBlockSettings(openingState?, trigger?, options?)

void

Toggle the block settings menu (☰).

When to use

Open/close the ☰ settings menu in code; pass an explicit boolean to set state rather than flip it.

Parameters

ParameterTypeRequiredDefaultDescription
openingStateboolean—toggle current stateForce the settings menu open (true) or closed (false).
triggerHTMLElement—undefinedElement to anchor the settings popover to.
optionsToolbarBlockSettingsOptions—undefinedPlacement overrides. placeLeftOfAnchor is already true when you pass a trigger element — set it to false to open the popover to the right of the trigger instead.
TypeScript
// Toggle current state
editor.toolbar.toggleBlockSettings();

// Force open
editor.toolbar.toggleBlockSettings(true);

// Force close
editor.toolbar.toggleBlockSettings(false);

// Anchor the settings popover to a custom trigger element.
// Left placement is already the default for an element trigger —
// opt out to open the popover to the right instead:
editor.toolbar.toggleBlockSettings(true, triggerEl, { placeLeftOfAnchor: false });

toolbar.toggleToolbox(openingState?)

void

Toggle the toolbox (+ menu).

When to use

Open/close the + insert (slash) menu programmatically; pass a boolean to force a state.

TypeScript
// Toggle current state
editor.toolbar.toggleToolbox();

// Force open
editor.toolbar.toggleToolbox(true);

toolbar.setHidden(hidden)

void

Runtime setter for `config.hideToolbar`: hide or show the hover toolbar (plus button / drag handle) AND collapse or restore the editor gutter reserved for it — the wrapper's `data-blok-toolbar-hidden` attribute is kept in sync, so no dead space is left behind. The keyboard "/" menu keeps working while hidden.

When to use

The runtime half of the hideToolbar config option — flips both the toolbar behaviour and the reserved gutter, so no dead space is left behind.

Parameters

ParameterTypeRequiredDefaultDescription
hiddenbooleanRequired—true to hide the hover toolbar and collapse the gutter; false to restore both.
TypeScript
// Hide the hover toolbar and collapse its gutter
editor.toolbar.setHidden(true);

// Restore it
editor.toolbar.setHidden(false);

toolbar.setPosition(position)

void

Runtime setter for `config.toolbarPosition`: move the floating block controls between the editor's inline-start and inline-end gutters. The wrapper's `data-blok-toolbar-position` attribute is kept in sync — it drives both the gutter swap and the side the controls dock to — and the block-settings menu mirrors with them, so it never opens over the block it belongs to. An open toolbar is re-laid out in place rather than closed.

When to use

The runtime half of the toolbarPosition config option — moves the controls and the gutter reserved for them together, and mirrors the block-settings menu so it never opens over the block.

Parameters

ParameterTypeRequiredDefaultDescription
position'left' | 'right'Required—'left' for the inline-start gutter (the default), 'right' for inline-end.
TypeScript
// Move the +/⠿ controls to the right of the content column
editor.toolbar.setPosition('right');

// Back to the left gutter
editor.toolbar.setPosition('left');