Skip to content

Format library: Add a special characters inserter - #86338

Open
annezazu wants to merge 16 commits into
WordPress:trunkfrom
annezazu:add/special-characters-format
Open

annezazu wants to merge 16 commits into
WordPress:trunkfrom
annezazu:add/special-characters-format

Conversation

@annezazu

@annezazu annezazu commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

What?

Closes #86336

This PR adds a "Special characters" item to the rich text "More" menu. It opens a searchable grid of special characters and inserts the chosen one at the cursor as plain text. I tried to learn both from the recent and similar work in #83538 as well as the 10up plugin.

Why?

The Classic editor (TinyMCE) has a "Special character" tool, but the block editor doesn't. Today users copy and paste characters from somewhere else, use their operating system's character viewer, or install a plugin such as 10up's Insert Special Characters. This came up again when hiding the Classic block was discussed for 7.1 (comment).

How?

  • New format: core/special-characters in @wordpress/format-library. It is never applied to content. It registers only to add its menu item, and the character is inserted with insert(), so saved content contains only the character itself.
  • Picker: it is built on the Design System Autocomplete in inline grid mode, following the pattern reviewed in Add emoji picker with Autocomplete grid  #83538 (Notes emoji picker).
    • The search field is a combobox and keeps focus. The arrow keys move a highlight through the grid, across sections.
    • Enter inserts the highlighted character. After typing, the top result is highlighted, so "euro" + Enter inserts €.
    • "No characters found." comes from Autocomplete.Empty. There are no extra live-region announcements, since filtering is synchronous.
    • The popover has a fixed width and height, so it doesn't resize as results change.
  • Characters: about 200, in headed sections: Punctuation, Currency, Symbols, Math, Arrows, Latin, Greek. Each one has a translatable name, which is its accessible name and what search matches against. Search ignores case and accents, and also matches the character itself. A strip at the bottom shows the highlighted character's name and code point.
  • Not included yet: a keyboard shortcut, a main toolbar button, and an API for plugins to add characters. These are out of scope for a first version, as discussed in Add a special characters inserter to the format library #86336.

Prior art and credit: 10up/insert-special-characters, by Adam Silverstein, John Watkins, Jeffrey Paul and the 10up team, and #83538 for the Autocomplete grid pattern.

Open questions

- Icon: this uses the typography icon as a placeholder. Nothing in @wordpress/icons fit really well. TinyMCE used Ω. @WordPress/gutenberg-design might need help here!
- Character set: which categories and characters should a first version include? A smaller set means less to translate.

  • Fonts: a character the font can't draw shows as an empty box. Should we hide those characters, or is that acceptable?
  • Escape closes the popover even with a search typed. Add emoji picker with Autocomplete grid  #83538 behaves the same way.

Testing Instructions

  1. Open a post and add a Paragraph block with some text. Place the cursor inside the text.
  2. In the block toolbar, open the "More" dropdown (the chevron) and choose "Special characters".
  3. Click a character. It is inserted at the cursor, the popover closes, and the cursor sits after the new character.
  4. Select some text, open the picker, and pick a character. It replaces the selection.
  5. Search for "euro" and press Enter. € is inserted.
  6. Search for "zzz". "No characters found." appears, and the popover keeps its size.
  7. Save the post and check the code editor: only the characters were added, with no extra markup.

Testing Instructions for Keyboard

  1. With the cursor in a paragraph, open the "More" dropdown with the keyboard and choose "Special characters". Focus moves to the search field.
  2. Press Down, then use the arrow keys. The highlight moves through the grid and from one section into the next, while focus stays in the search field. The preview strip shows the highlighted character's name.
  3. Press Enter. The character is inserted and focus returns to the text, right after it.
  4. Reopen the picker and press Tab. Focus stays in the search field (no Tab stop on the grid's scrolling area).
  5. Press Escape. The popover closes and the cursor is back where it was.

Screenshots or screencast

special.characters.mp4

Use of AI Tools

This PR was written with Claude Code (Claude Opus 5.5). It researched the plugin and #83538, and wrote the code, tests and this description. I reviewed the changes and tested them in the editor.

🤖 Generated with Claude Code

Adds a "Special characters" item to the rich text "More" menu. It opens
a searchable grid of about 200 characters in headed sections (currency,
punctuation, math, arrows, Latin and Greek letters, symbols), led by a
"Frequently used" section stored per user in preferences. The character
is inserted as plain text at the caret.

The picker is built on the Design System Autocomplete in grid mode, so
focus stays in the search field while the arrow keys move through the
grid, following the pattern reviewed in WordPress#83538.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@annezazu annezazu added [Type] Enhancement A suggestion for improvement. [Feature] Writing Flow Block selection, navigation, splitting, merging, deletion... labels Nov 5, 2026
@annezazu
annezazu requested a review from ellatrix as a code owner November 5, 2026 01:11
@github-actions github-actions Bot added the [Package] Format library /packages/format-library label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: annezazu <annezazu@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: ellatrix <ellatrix@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

@jeffpaul

jeffpaul commented Nov 5, 2026

Copy link
Copy Markdown
Member

Icon

I recommend Ω as yes that's what TinyMCE users / what folks know from the Classic Block and is also what Insert Special Characters uses (and if this PR is going to land in core then I'll likely close our plugin so keeping the same icon will help those users migrate to using the core function).

@jeffpaul

jeffpaul commented Nov 5, 2026

Copy link
Copy Markdown
Member

Character set: which categories and characters should a first version include? A smaller set means less to translate.

Early on with Insert Special Characters we got a couple requests for characters we didn't include by default, so I'd recommend ensuring those are included where feasible.

From 1.0.3:

Many new special characters (e.g., em dash, en dash, hair space, thin space, no-break space, en space, em space, zero width non-joiner, non-breaking hyphen) and groupings (Currency, Punctuation, Greek).

From 1.0.4:

Many new special characters (e.g., ⅐, ⅑, ⅒, single quotation marks, ß, ẞ, Ć, ć, Ḉ, ḉ) and grouping (Music)

I worked pretty hard early on in the plugin in the https://github.com/Dayjo/react-character-map upstream repo, so you could use the character map set from there as a guide as that's essentially the base of what we formed for ISC.

@jeffpaul

jeffpaul commented Nov 5, 2026

Copy link
Copy Markdown
Member

Fonts: a character the font can't draw shows as an empty box. Should we hide those characters, or is that acceptable?

Oh man this was such a pain in the butt early on in support requests, trying to figure out why some characters didn't appear for folks. Net result was this FAQ item https://github.com/10up/insert-special-characters/#how-come-i-do-not-see-all-the-special-characters that might help inform your decision here.

@ellatrix

ellatrix commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Should we scope this down by omitting the recent character thing for now? It's already searchable. TinyMCE did not have that right? I don't mind either way, just a suggestion.

@jeffpaul

jeffpaul commented Nov 5, 2026

Copy link
Copy Markdown
Member

Last item (for now, happy to follow up any questions/requests for review) is that should this PR get merged (and thus make its way to a core release) I will plan to archive/close the Insert Special Characters plugin. With that in mind, I'd appreciate it if we could credit the folks in https://github.com/10up/insert-special-characters/blob/develop/CREDITS.md who helped evolve that plugin as the base for what's being considered here (and all those lovely contributors would get to see the essence of their work get into core and gather a prop for their effort).

@jeffpaul

jeffpaul commented Nov 5, 2026

Copy link
Copy Markdown
Member

Should we scope this down by omitting the recent character thing for now? It's already searchable. TinyMCE did not have that right? I don't mind either way, just a suggestion.

That's certainly reasonable, though that was an early feature request we had from many folks and eventually added in 1.0.5 with the most and last used character palettes. Live preview here.

@Mamaduka Mamaduka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we scope this down by omitting the recent character thing for now

+1. Let's ship minal version and we can add this as needed.

@jasmussen

Copy link
Copy Markdown
Contributor

Nice work, interesting solution.

First I want to connect some dots, where @hanneslsm opened #55565 asking specifically for a type of markup to direct word-breaks. Relatedly, there's #71521 which goes in a different direction, but also this solution discussion which ponders whether special characters should live in a submenu flyout. Wherever we go with this PR, we should follow up on those older issues and PRs.

This PR does an elegant thing of having a single menu item that opens a emoji-picker-like. This is scalable and pretty clean, one take-away is that @adamsilverstein and @Mamaduka should be aware of this as far as the emoji picker they have been looking. Ideally what we build between the two is identical: this is one interface, one glyph inserter whether it's emoji or "special characters"—it's all unicode.

The question then also becomes, is it also a place to insert HTML markup? How about URL encoded characters? Non-breaking spaces can be both the unicode glyph, but it can also be &nbsp;. 55565 asks for the <wbr /> tag, arguably U+200B ZERO WIDTH SPACE or &#8203; is similar but it's not a perfect match to it, and there's also U+00AD(soft hyphen), or &shy; which is an invisible hyphen that only appears when a word breaks.

Do all of those belong in this interface? If not, why not?

All that aside, pretty elegant solution, and notably we've had requests from a lot of theme devs (@beafialho comes to mind) for a glyph insertion tool. The next step there is to enable those glyps to be used instead of icons in places like the menu burger icon, next/prev buttons, and the like.

@t-hamano

t-hamano commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Should we scope this down by omitting the recent character thing for now

+1. Let's ship minal version and we can add this as needed.

+1. Since frequently used characters are persisted per user via @wordpress/preferences, the key and value format becomes something we have to keep backward compatible once it ships. I'd prefer to start with a minimal version that doesn't store any user data, and add this in a follow-up once we know it's needed.

@adamsilverstein

adamsilverstein commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Very cool, I'll give this a test! I like how closely this matches the emoji picker we are working on and agree with @jasmussen they should ultimately be the same component, just showing different choices.

The question then also becomes, is it also a place to insert HTML markup?

maybe making the character list extensible (which I see the 10up plugin also does) helps address this.

@annezazu

annezazu commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Thank you all for jumping in here 🤠. Exciting to wake up to.

I like how closely this matches the emoji picker we are working on and agree with @jasmussen they should ultimately be the same component, just showing different choices.

This is scalable and pretty clean, one take-away is that @adamsilverstein and @Mamaduka should be aware of this as far as the emoji picker they have been looking. Ideally what we build between the two is identical: this is one interface, one glyph inserter whether it's emoji or "special characters"—it's all unicode.

I'm sorry I didn't communicate this better but, as I was working on this, I realized how much the problem space overlaps so I tried to re-use and also make different decisions based on what was done there with the emoji picker already. It's also why I tagged those folks in. I'm in complete agreement 🤝.

Reading over the feedback, here's where I am seeing agreement and next steps:

  • Align the pickers across this PR and the emoji PR.
  • Drop "Frequently used" as out of scope. Hilariously, that was my original plan but I got excited with seeing the implementation with the emojis.
  • Use Ω as the icon. Makes sense.
  • Add the characters @jeffpaul noted folks want/should be easy to add.
  • Credit the plugin's contributors.

I'm going to work on the above today.

- Open the picker with Autocomplete.Popup, positioned at the caret
  through Autocomplete.Positioner, instead of the components Popover.
- Remove the "Frequently used" section and the @wordpress/preferences
  dependency, to start without stored user data.
- Use the Classic editor's icon, the editor-customchar Dashicon (Ω).
- Add a Music section, more fractions, ẞ, Ć, ć, Ḉ and ḉ.
- Drop an outdated @ts-expect-error: block-editor is typed now.
- Add a CHANGELOG entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@annezazu

annezazu commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Alright, pushed some changes! Here's what it looks like now:

Screen.Recording.2026-11-05.at.11.40.49.AM.mov
  • Dropped "Frequently used".
  • Use Ω as the icon. This looks a bit funky but does the trick.
  • The picker now opens in Autocomplete.Popup, the same building block the emoji picker uses, instead of the old Popover.
  • Added ⅐ ⅑ ⅒ and the other missing fractions, ẞ, Ć, ć, Ḉ and ḉ, and a new Music section (♩ ♪ ♫ ♬ ♭ ♮ ♯). The invisible characters listed (special spaces, zero width non-joiner, non-breaking hyphen) are not included since that's an open question.
  • Removed the outdated @ts-expect-error comment.

During this, I found a weird overflow issue with some of the longer named items and fixed that so the name wraps onto a second line instead, and the popup stays the same size.

@annezazu

annezazu commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

To state the obvious, I’ll need some solid tech reviews of the code if anyone has a chance to do a deeper review. I welcome pushing commits here, taking over the PR, etc. I just saw this getting lost in the shuffle and wanted to get it moving. I’ll keep doing updates too!

@adamsilverstein

Copy link
Copy Markdown
Member

I discovered some potential accessibility improvements testing locally. I'm recording with voiceover with Claude's help and will share screencasts.

@adamsilverstein

Copy link
Copy Markdown
Member

I used Claude to perform some accessibility review and testing using voiceover on my mac and recorded this screencast using the feature with a couple of places that could use improvement indicated:

86338-special-characters-voiceover.mp4

Logs: 86338-voiceover-log.tsv

Here is a list of the issues it identified:

  1. The popup is an unnamed dialog. Because the search input sits inside the popup, Base UI gives it role="dialog", and nothing labels it. VoiceOver says "Search special characters Search and 1 more item dialog" - the dialog itself has no name. Adding aria-label={ title } to <Autocomplete.Popup> fixes it. The grid already carries the same label, so it may be worth renaming that one (eg. "Characters") to avoid hearing it twice.
  2. Every arrow press is very noisy. Each cell is read as "<name> blank", followed by every name in the row, eg. "Em dash blank column 2, row En dash Em dash Figure dash Ellipsis Bullet Middle dot Left single quotation mark Right single quotation mark". The "blank" likely comes from the glyph being aria-hidden while the name is only in aria-label, so putting the name in visually hidden text inside the cell may help.
  3. Search results are silent. Typing "dash" gives no result count. Searching "zzz" shows "No characters found.", but VoiceOver only echoed the typed letters - the Empty live region was not spoken in testing, possibly because it is added to the page at the same moment as its text. A debounced Autocomplete.Status or speak() with something like _n( '%d character found.', '%d characters found.' ) (and the empty message) would cover both.
  4. Section changes are silent. Arrowing from Punctuation into Currency reads the cell only; the "Currency" group label is never announced.
  5. No interaction tests yet. The unit tests cover the data and search. An e2e test for the keyboard path (open from the More menu, type "euro", Enter, check the caret; reopen, Escape) would catch focus regressions.

Smaller things: the preview strip is aria-hidden, so the code point (eg. U+2014) is only available visually; an aria-description on each cell could expose it. An explicit "Euro sign inserted." announcement would also be a nice touch, though VoiceOver reading the caret position already gives some confirmation.

To me these all feel like valid issues - especially the search feedback ones - and things we could improve (nice to have rather than blockers that break the functionality) although I defer to @joedolson for feedback here.

@joedolson

Copy link
Copy Markdown
Contributor

Thanks, @adamsilverstein!

I'd consider 2 and 3 to be blocking issues - they essentially reduce the ability to actually locate and select a character to almost zero, which is a major barrier. I'd also consider the fact that the code point isn't available non-visually to be a fairly major issue; that's a clear inequality of information availability between sighted and non-sighted users.

I'll note, however, that the aria-description attribute still has extremely limited support, and isn't a recommended way to provide description information.

The other issues are all legitimate, but they don't actually block the user from using the feature.

- Name each cell with visually hidden text, "Em dash (U+2014)", instead
  of aria-label over a hidden glyph, which VoiceOver read as "blank".
  The code point, until now only shown in the preview strip, is part of
  the name.
- Name each row after its section, so arrowing reads the cell and its
  section instead of every name in the row, and announces new sections.
- Announce the search result count, or "No characters found.", through
  Autocomplete.Status once typing pauses. The visible empty message is
  hidden from screen readers so it isn't spoken twice.
- Name the popup, which is a dialog, and rename the grid "Characters".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@annezazu

annezazu commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Thank you! This was super helpful. Submitted some changes to address the main points. Here's a summary:

  • The popup is now a dialog named "Special characters". The grid was renamed "Characters", so the name isn't read twice. Woohoo!
  • Addressed arrowing being noisy:
    • "blank": each cell's name was only in aria-label, with the visible character hidden, so VoiceOver read the cell as blank. The name is now visually hidden text inside the cell.
    • Fix rows having no names so they now are named after its respective section.
  • Search result rows are named "Search results".
  • Fixed search results being silent so that the result count ("3 characters found.") or "No characters found." is announced once typing pauses for half a second. It goes through Autocomplete.Status which seems to be what's recommended via DS. The visible empty message is hidden from screen readers so it isn't spoken twice.

Picking a cell closes the picker in the same event that writes the
cell's value into the search field. React batches both updates, so the
picker unmounts before the field can show the value, and the guard
had nothing left to prevent.
@mirka

mirka commented Nov 9, 2026

Copy link
Copy Markdown
Member

Both the block shift and the focus trapping regressions turned out to be a symptom of incorrect Autocomplete.Popup usage. I fixed the implementation to use a normal Popover as intended, and added a story to document this in #86520. The portal and other workarounds are removed now.

These first few use cases are really important to surface documentation gaps and solidify patterns, so thanks!

Other notable changes

  • Removed the item-press check in the search field's onValueChange. Picking a cell closes the picker in the same update that writes the cell's value into the field, so the value never shows. With and without the check, the field stayed empty after both a click and Enter.

  • Accessibility: Removed the result count announcement, because filtering is synchronous. The top result is highlighted as soon as the user types, and the search field exposes it through aria-activedescendant. Autocomplete.Empty is now used as designed and announces "No characters found." itself.

    This is our current documented guidance based on WCAG and the APG, so if this needs changing for some reason, we should consider changing the guidance instead of just changing one implementation.

  • Styles: the Popover surface now provides the padding, border and shadow. The grid starts at the same edge as the search field, and a classic scrollbar sits at the popover's edge instead of against the last column.

One testing note: In Firefox, Escape leaves focus on <body> instead of the paragraph. This also happened before these changes, so it's a preexisting browser issue.

…rs-format

# Conflicts:
#	packages/format-library/CHANGELOG.md
Now that the Design System list body pins group labels while their
items scroll, use it as the grid's scroller instead of a custom one.
It also stays out of the Tab order and pads the scroll so a
highlighted cell does not stop under a stuck heading, so the picker
no longer needs its own sticky heading styles, scroll padding or
tabIndex.

A wrapper keeps the fixed height and holds Autocomplete.Empty, which
is a live region and cannot go inside the grid. While there are no
results, a spacer holds the grid's width, so the popover does not
narrow when Chromium leaves a classic scrollbar's gutter out of an
empty scroller's width.
@mirka

mirka commented Nov 11, 2026

Copy link
Copy Markdown
Member

I added built-in sticky header support in #86535, so I went ahead and integrated that here too. I'll continue to work on some layout improvements in Autocomplete to make this kind of implementation simpler, but not a blocker for this PR.

@ciampo

ciampo commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

@mirka happy to give this a review once you think it's ready for it

@mirka

mirka commented Nov 11, 2026

Copy link
Copy Markdown
Member

#86652 is going to land soon so I'll do some additional CSS simplification here after that.

An inline Autocomplete.List and Autocomplete.Empty now follow a
surrounding CSS grid instead of the popup's named grid areas, so the
fixed-height results wrapper can be a grid with an auto row for the
empty message and the rest for the list. The flex column and the
List's own class are no longer needed.
Comment on lines +339 to +342
{ /* Required by `trap-focus`, so screen reader users can leave. */ }
<VisuallyHidden render={ <Popover.Close /> }>
{ __( 'Close' ) }
</VisuallyHidden>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pressing Tab from the search field focuses this Close button, but VisuallyHidden keeps both the button and its focus indicator clipped. Could we make it visible, at least while focused, so keyboard users can see where focus went?

Comment on lines +207 to +224
onOpenChange={ ( nextOpen: boolean, { reason } ) => {
if ( nextOpen ) {
return;
}
onClose();
// Escape: put the caret back where the character would have
// gone. Clicking elsewhere leaves focus where it landed.
if ( reason === 'escape-key' ) {
onFocus();
}
} }
>
<Popover.Popup
className="format-library-special-characters__popover"
// There is no trigger to return to: the format puts the caret
// back itself, and only after Escape or a pick.
initialFocus={ inputRef }
finalFocus={ false }

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Activating Close leaves focus on <body>, while Escape returns it to the editor. Could we also call onFocus() for close-press so users can continue editing after dismissing the picker?

@Mamaduka

Copy link
Copy Markdown
Member

Did we make a decision for cases like non-breaking space? Saw this report (#86735); the new inserter seems like a good place for it.

…tton

- Add the non-breaking space (U+00A0) to Punctuation. It has no visible
  glyph, so its cell and the preview strip show "NBSP", and search also
  matches "nbsp" through a new `keywords` field.
- Make the Close button that `trap-focus` requires a visible icon button
  beside the search field, so keyboard users can see where Tab moves focus.
- Return the caret to the text after Close, as Escape already does.
- Add e2e tests for Enter on a search result, the non-breaking space,
  Escape, and the Close button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions
github-actions Bot requested review from aduth and ciampo November 13, 2026 19:04
@annezazu

Copy link
Copy Markdown
Contributor Author

@Mamaduka thanks for connecting that here! To keep this scoped well, I'd be game to add just a non-breaking space for now since that's more clearly visible in the editor with 7.2. Here's the approach I took in the recent commit.

First, I had Claude do some research around how other tools show this option:

  • Unicode's own code charts: spaces and other invisible characters are drawn as a dashed box with the abbreviation inside, such as "NBSP". This is the closest thing to a standard, and font and character-viewer tools often copy it.
  • Microsoft Word (Insert → Symbol → Special Characters): it doesn't put these in a grid of glyphs. It lists them by name as text, e.g. "Nonbreaking Space", with the keyboard shortcut next to it.
  • TinyMCE (the Classic editor): its character map lists the non-breaking space as a nearly empty cell, so it's hard to find without hovering.
  • ISO keyboard symbol (U+237D): there is a dedicated symbol for a non-breaking space. Few people recognise it, and many fonts can't draw it, so it would show up as an empty box. This touches on the fonts problem already discussed.

I went back and forth with a boxed NBSP vs just showing NBSP.

Screenshot 2026-11-13 at 10 59 33 AM

Ultimately, I went with just showing NBSP as the box looked janky. @jasmussen I need your design wisdom here once more when you have time:

Screenshot 2026-11-13 at 11 01 47 AM

If you search "space" it appears. I also used AI to address @ciampo's comments and I hope I've interpreted it all correctly (let me know if not). Here's a quick rundown of the changes:

  • Added the non-breaking space, shown as the plain "NBSP" label. Appears via search with "space" or "NBSP".
  • A visible Close button next to the search field.
  • The cursor going back to the text after Close, the same as after Escape.
  • The new e2e test file, test/e2e/specs/editor/various/format-library/special-characters.spec.ts.

Of note, for the close field, I noticed when you have the search selected then hover over close, it's a bit cramped:

Screenshot 2026-11-13 at 11 04 56 AM

Not a deal breaker but felt worth noting for now. I'm not sure DS wise how best to handle that.

@adamsilverstein

Copy link
Copy Markdown
Member

Ultimately, I went with just showing NBSP as the box looked janky

Inserting a non- breaking space worked well for me. One thing I noticed after inserting it was it was treated differently than other special characters:

  • It showed as a dot/bullet, not as the NBSP symbol I had selected
  • when my caret was next to the • a new non breaking space control appeared in the toolbar that let me "Replace non-breaking space"

Maybe those are both working as expected, it just seemed a bit surprising to me while I was testing it. Here is a quick screencast:

screencast.2026-11-14.08-05-56.mp4

@jasmussen

jasmussen commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Tricky one. Your explorations are good, and we're getting there. But two things come to mind, the font size feels too loud at 20px. The challenge: there's not a good token size we can use here, and the next one down is 15px (lg). There's been discussions about bumping that to 16, and the base to 14, and 16 could just about work, but even that feels slightly small. In all cases, the font weight also feels very black. The problem is the same with font weight, where the regular 400 token feels too bold for these symbols. I mention this purely for the design system angle, as a question: do we need to refine or should this interface not use DS tokens? CC: @jameskoster @ciampo @mirka. Here it is, 20px font size, font weight 400:

image

Here's what I think would look good, 18px font size, 300 font weight:

image

Here's the smaller 15px font size token, with the regular 400 weight:

image

Probably no immediate action item, Anne, just noting as this surfaces token questions.


In-canvas representation

On the particular question of how to show invisible characters like nbsp and others, it's an industry wide challenge with precedence. You researched some of this yourself, but I'd expand that it goes beyond what we show in this panel, to what is shown in canvas after the fact. Right now we show a blue dot, a unique icon in the block toolbar and a tooltip:

image

I think that's recent, I don't recall seeing the PR for it. It's not terrible, but it's not ideal either: if you have a blue site background, the blue dot will be invisible. I'm almost certain that previously we'd show a tofu-box. My recommendation for what we should show in-canvas instead of any character that shows the blue dot, would be a small space the true width of the invisible character, but then a "marked" background, e.g. like this:

There is a non-breaking space between the next two words: hello world.

The precise colour of the marking should be seeded from currentColor so it's always based on the text colour to ensure contrast. Something likebackground-color: color-mix(in srgb, currentColor 40%, transparent)'.

The marking should also be paired with a min-width of, say, 0.5 or 1ch, so even zero-width-space is shown as a character.


The actual glyph representation in the picker

For the symbol itself, the challenge here is: do we show a generic kitbash of letters representing a unicode code-point, like you have? Or do we show something else?

It's pretty key because depending on what we want to show in this character picker, and how we want to show it, our room for movement gets limited. NBSP is one character, but U+200B is another, 2 characters wider than NBSP. If you can tune the font-size contextually for that kitbash, I'd encourage you to see if you could fit "U+" and four characters, or just <wbr />, which is a wide piece. We're quickly running out of space there, and in all cases, the icons will make little sense until you hover them, or unless you search. Which thankfully shows us this:

image

Since users are looking for the behaviour, this helps a lot, just like it does when searching for emoji.

But to expand on the NBSP (non-breaking space) and U+200B (zero-width space), these are unlike the other glyphs in the picker, because they are not glyphs, they are behavioural characters. One ensures two words are glued together, the other can help define where you want a word to break if you want it to break (similar to <wbr />). No icon can ever really communicate the behaviour. At most we can hope for providing a point of comparison for someone browsing the picker to differentiate between the non breaking space and the zero-width space, through recognizing the codepoints.

In other words, even if it is janky, your proposal of a tight NBSP is probably our best bet if we want to keep the emoji picker interface—though do try to make the font size for those kitbash icons as small as you can, so you can ideally fit 6 characters. You might have to word break after all, even if you omit the dashed box. Be sure to also compress the line-height in that case.

Edit: scratch those 6 characters, you can use the acronyms: NBSP, ZWSP, ZWNJ, SHY, WJ, NNBSP. 5 chars max.


The alternative here is to stop fighting the grid layout, and embrace a row layout. Instead of showing a grid of glyphs, show what they will render at as a small preview on the left, and then the title on the right, just like what you show on-focus at the bottom, but for each special-character glyph.

I realise that's quite a change from the emoji picker interface we're all otherwise happy with, so I'm not actually proposing you do this. But I think it's important to mention as an alternative. It can even spell out other paths forward, such as keep the special characters inserter as an emoji picker, but include only glyphs in it. Make a separate menu item for "behavioural characters", including non-breaking space, word break, and so on.

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jasmussen, I'm not sure whether 18px belongs in the shared font-size scale or where it would fit. We can definitely try it as an exception for the glyphs in this picker, at least to start. They're previews of the characters you can insert. I'd keep the labels on the existing scale.

A token for a lighter weight of 300 seems more straightforward. Before settling on either change, I'd compare the current 20px/400 with 18px/400 and 18px/300 across our supported browsers and operating systems. We saw with 500 and 600 how much depends on the font face the browser uses. Even in Chrome on macOS, € gets lighter at 300 while ∈ looks the same at both weights. Earlier font-weight discussion

For NBSP, I'd keep the abbreviation in the grid and show the full name and code point in the preview. If we add more invisible characters, I'd try named rows for those so people can browse by what the characters do. The currentColor marker sounds worth exploring separately in RichText, where we can check contrast, line wrapping, and caret movement.

}, [ categories, isSearching, query ] );

function onSelect( option: CharacterOption ) {
onChange( insert( value, option.value ) );

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inserting € in the middle of a link splits it into two links and leaves the euro sign outside both. Could we preserve the active formats when inserting the character and cover that case in the editor test?

// and does not jump when it opens above the text.
display: grid;
grid-template-rows: auto minmax(0, 1fr);
height: 260px;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On a mobile viewport, the character name and code point fall below the screen, and scrolling doesn't bring them into view. Could the results list shrink to the popover's available height so the preview stays visible?

[ character.name, ...( character.keywords ?? [] ) ].join( ' ' )
);
if (
character.char === trimmed ||

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Searching for é and pressing Enter inserts an en dash because “En dash” also matches the normalized e. Could we put an exact character match first?

@jasmussen

Copy link
Copy Markdown
Contributor

Thanks for the response Marco, just noting that from it I read that: if we change font size and weight, we should do it locally for this component for now, not (yet) create new tokens for it. I think this is especially important if we're pondering bumping the font size tokens by 1px. Is that fair?

@mirka

mirka commented Nov 17, 2026

Copy link
Copy Markdown
Member

I noticed when you have the search selected then hover over close, it's a bit cramped

I think I'd prefer a "visible only while focused" button, like a skip link, rather than a permanently visible close button. Something like this?

CleanShot.2026-11-17.at.20-35-29.mp4

No strong opinion on the exact placement or style. It could even be a text label button.

- Keep the formats at the caret on the inserted character, so inserting
  inside a link no longer splits it. Covered by a new e2e test.
- List an exact character match first, so searching "é" and pressing
  Enter inserts "é" rather than "En dash".
- Cap the content at the positioner's available height and shrink the
  results first, so the search field and preview stay on screen on
  small viewports.
- Show the Close button only while focused, like a skip link.
- Size the glyphs at 18px and weight 300, local to this picker.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@annezazu

Copy link
Copy Markdown
Contributor Author

Catching up on the feedback here. Thanks for the patience as I was out earlier this week and then played some catch up.

  • Inserting a character inside a link (or bold text etc) no longer splits it. The character gets the same formatting. Tried to add an e2e test for this but it prob needs to be checked. Thanks @ciampo! Video demo below.
  • Prioritized exact match so that searching é and pressing Enter now inserts é rather than "En dash". Again, thank you @ciampo.
  • Fixed the sizing on small viewports so the results shrink first ensuring the search field and the preview stay visible. Shared a video below.
  • Added a close button on tab following @mirka's suggestion. I added it near the top though rather than at the bottom. I'm not sure why but visually tha felt better to me. Again it's visible in the videos below.
  • Added @jasmussen's 18px / 300 locally for the glyphs only with no new tokens. I'm happy to revert the weight if cross browser checks make 300 look inconsistent or rough for any reason. Just seemed like a solid next step.
  • For NBSP, the grid keeps the abbreviation and the preview shows the full name and code point ("No-break space (U+00A0)"), as suggested.

General video showing updated NBSP, inserting inside a linik fix, exact match, and close button:

Screen.Recording.2026-11-19.at.3.29.39.PM.mov

Video showing smaller viewport:

Screen.Recording.2026-11-19.at.3.31.45.PM.mov

Btw, just want to say thank you @jasmussen for such a thoughtful, recent comment. I worry about expanding scope too much but I also want to be sure this scales well.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Writing Flow Block selection, navigation, splitting, merging, deletion... [Package] Format library /packages/format-library [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a special characters inserter to the format library

10 participants