Image insertion using slash menu in BlockNote

[ClementEXWiki]

Currently in BlockNote we have a single way to insert an image: by typing /image, which triggers the image popover (see below), in which one can search for existing images or upload a new one.

In order to improve the user experience, it was decided to replace that with a simple suggestions menu, like the one already existing in CKEditor 4:

The thing is, CKEditor has a fixed toolbar at the top of the editor, which BlockNote lacks. So with that kind of menu, there is no way to open an actual modal to search properly for images with additional filters for instance.

So what UX should we strive for in the new suggestion menu for BlockNote?

1. Mimic the exact same UX/UI as CKEditor 4 (upload button as first item then suggestions)
2. Use the same menu but insert a second item that would open a modal with more complete options (so for instance upload button, modal button, then suggestions)
3. Use the same menu but add a second slash menu item that would open the menu

I would personally go for option n°2, as it would allow access to everything in a single, unified menu. Having a separate slash menu item might be confusing for users, and leaving out the ability to open the advanced modal would be problematic.

What do you think?

(P.S. feel free to tell if anything wasn’t clear in my proposal)

[vmassol]

@ClementEXWiki

it was decided to replace that with a simple suggestions menu

Could you link to the design page (or the forum proposal) so that we can remember what was agreed? I’m asking since I want to verify that the proposal (which is a simple suggestion entry apparently) didn’t loose anything from what we have in CKEditor (which is a modal with several tabs).

Thx

[mleduc]

Nothing is decided yet.

To give a bit of context, in CKEditor 4 (CK4) there are two ways to add an image.

The first one is through the quick action (/image). In this case the user can only search attachments by name (or upload a new one), and the image is inserted with no default parameters.

Image quick action default view:

Image suggestion post filtering in the quick actions, not scoped to the current page:

The second one is through the top menu image button.

In this case, the user is first proposed an exhaustive set of tabs, each offering a way to search and add an image (gallery, tree, upload, icon, url).

Once the image is selected, a second step allows customizing the image before inserting it.

In the case of Blocknote, we don’t have a top bar, and the impact of this choice on the quick actions is what is discussed here.

Option 1 - keep it simple

Only offer to insert the image through the quick actions. Users can customize the image by editing them once inserts.

Cons:

• We lose all the advanced selection options.

Option 2 - Add an entry at the top of the quick actions.

In the first image of this proposal (from CK4), you can see an “Upload image” action.
We can replace it with a “Navigate images” entry that would open the modal that used to be opened through the top menu image button in CK4.
Note: We can keep the “Upload image” action too if we want to keep having a way to quickly upload and insert an image.

In summary, the user story is: /img → enter → type to filter images or press enter to select the “Navigate images” option

• /img → select “Image”
• select “Navigate images” → image modal is opened → usual image selection and insertion flow
• type more to filter → image inserted

Option 3 - Add to distinct quick actions

Close to option 3, but the “Navigate images” is moved one level up.
When typing /img, the user is offered two choices:

1. Quick insert
2. Navigate images

The user story is:

• /img
  • select “Quick insert” → upload or type more to filter → image inserted
  • select “Navigate images” → image modal is opened → usual image selection and insertion flow

Option 4 - Add back a top menu

Mentioning it for exhaustiveness, but I wouldn’t go that road. It does not match standard “block” editor design. It also uses more vertical space, which makes the editor harder to integrate in space-limited parts of the UI (in-place field editing, LD cells…).

I’m -1 for options 1 and 4.
I’m equally +1 for options 2 and 3, but I’m unsure which choice is the best.

Thanks!

cc @tkrieck for the UX aspects and @mflorea for the editor expertise.

[tkrieck]

@ClementEXWiki

The thing is, CKEditor has a fixed toolbar at the top of the editor, which BlockNote lacks.

Can’t we have the toolbar fixed in BN as well? BlockNote - Static Formatting Toolbar.

I don’t see any issue with having a top toolbar in the main editor. It might be actually the best option to lessen the friction for current CK4 (and possibly Confluence) users.

Regarding the options from Manuel:

@mleduc

Option 1 - keep it simple

I don’t mind it, but it does increase friction when users need image options (borders, for example, I use them a lot).
So a 0 from my POV

@mleduc

Option 2 - Add an entry at the top of the quick actions.

This one is more flexible, users can simply insert images OR jump into the dialog without hassles.
+1 from me

@mleduc

Option 3 - Add to distinct quick actions

I don’t like it since it puts a decision point in front of the user right away.
-1

@mleduc

Option 4 - Add back a top menu

Like I wrote when starting this reply, I don’t see it as being exclusive over the other ones for the main document screen. We could have Option 2 and 4 for flexibility in exchange of a bit more UI space.

For space restricted uses like in LiveData cells or text area inputs, then I agree that a fixed bar is not ideal. My point here is that there are uses for both UXs.

Also 0

Thanks!

[vmassol]

My POV:

There are 2 orthogonal questions:

• Option 2 vs 3 (answer: 2/3)
• Whether we want or not option 4 (answer: yes/no/later)

Option 5 - filePanel tabs

This option is maybe more BlockNote-idiomatic than 2 or 3.

BlockNote’s File Panel already is a tabbed picker (Upload/Embed), it appears automatically when you insert an image block with no URL or hit “Replace file”, and it’s fully replaceable via the filePanel slot (see their Uppy File Panel example).

So instead of bolting a bespoke modal onto the slash menu, XWiki could replace the FilePanel with the XWiki image picker (gallery / tree / upload / icon / URL as tabs). Then /image → empty image block → XWiki picker, with no extra menu entry, no decision point, and — the bonus — the same advanced picker on replace, not just on insert. It also degrades correctly in cramped editors.

My opinion:

• Option 1: -1, it’s not really possible since we would loose too many features and we wouldn’t be able to migrate users from CK4 to BN.
• Option 2: +1
• Option 3: -0
• Option 5: +1
• Option 4: -0 but only because we have the use case of cramped editors (in-place field editing, LiveData cells, comment). Now it’s not all or nothing. We could imagine that it is configurable, and depending where the editor is used to have a static top toolbar or not.

What CC says about option 4:

Is a fixed toolbar “not standard block editor design”?

Not really. Block editors split into two camps, and the split correlates with the product, not with block-ness:

Toolbar-less camp (note-taking): Notion, Craft, Coda. Insertion is slash + the hover + handle + drag-and-drop; Coda’s docs explicitly sell the contextual-only toolbar as giving “docs more space for your content.”

Fixed-toolbar-available camp (document/enterprise authoring):

• WordPress Gutenberg — the most deployed block editor in existence — has a Top toolbar preference that pins block tools into a fixed header, alongside a permanent + inserter in that header. Insert-media from a fixed bar is the norm there.

• Confluence Cloud — a ProseMirror block editor, and the closest thing to XWiki’s target user — lets users pin the toolbar fixed at the top, and Atlassian’s own doc says that when fixed, “more elements such as media, tables, and emojis will appear”. In other words Confluence puts the insert actions in the fixed bar specifically, and drops them from the floating variant for lack of room. That’s a direct counterexample: the industry’s leading block-based wiki does exactly what option 4 proposes.

So the accurate framing is: it’s a legitimate, well-precedented choice with a cost — not a violation of block-editor design. Worth correcting on the thread, because “not standard” is doing a lot of load-bearing work in a −1.

Manuel’s real argument survives

His second sentence is the strong one and I’d concede it: vertical space, and the fact that XWiki renders BlockNote in space-constrained slots (in-place field editing, LiveData cells, comments). Notion and Confluence never do this — they render one editor, full-page. That constraint is genuinely XWiki-specific.

But it argues for per-instance configuration, not for never having a toolbar — which is exactly Thiago’s “there are uses for both UXs”, and exactly what Confluence does by making it user-pinnable. BlockNote makes this a render-time prop, so a full-page editor and a LiveData-cell editor can differ trivially.

One nuance that mildly weakens the pro-toolbar discoverability case: BlockNote’s side menu + button already opens the slash menu on hover, so mouse users who never learn / do have a discoverable insertion path today. The honest argument for the top bar is migration friction for CK4/Confluence users, which is Thiago’s actual point — not raw discoverability.

Thx

[ClementEXWiki]

On a tangent note, I am not keen on pasting AI answers directly into the forum comments, as it’s a slippery slope before we start getting AI slop all over the place.

Apart from that, I think a fixed toolbar could be interesting, as we must keep in mind that many of our users may not find the slash menu as intuitive: there’s less discovery, it’s more complicated to find some specific options, and a fixed toolbar avoids having to type what you want before actually getting to the action.

I believe most users prefer mouse navigation instead of keyboard too.

UI-wise not sure how well it would look, but on paper I’m very interested in having a fixed toolbar for BlockNote.