flexible-ux / lexical-bundle
A reusable Symfony form type providing a lightweight Lexical (Meta) rich-text editor, wired with AssetMapper, Stimulus and UX Icons.
Package info
github.com/Flexible-User-Experience/lexical-bundle
Type:symfony-bundle
pkg:composer/flexible-ux/lexical-bundle
Requires
- php: >=8.2
- symfony/asset-mapper: ^7.4 || ^8.0
- symfony/config: ^7.4 || ^8.0
- symfony/dependency-injection: ^7.4 || ^8.0
- symfony/form: ^7.4 || ^8.0
- symfony/html-sanitizer: ^7.4 || ^8.0
- symfony/http-kernel: ^7.4 || ^8.0
- symfony/options-resolver: ^7.4 || ^8.0
- symfony/stimulus-bundle: ^2.20 || ^3.0
- symfony/translation: ^7.4 || ^8.0
- symfony/twig-bundle: ^7.4 || ^8.0
- symfony/ux-icons: ^2.20 || ^3.0
Requires (Dev)
- dbrekelmans/bdi: ^1.4
- phpunit/phpunit: ^11.5 || ^12.0 || ^13.0
- symfony/framework-bundle: ^7.4 || ^8.0
- symfony/panther: ^2.4
Suggests
None
Provides
None
Conflicts
- masterminds/html5: <2.8.1
Replaces
None
- dev-main
- v1.1.0
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.1
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.1
- v0.2
- v0.1
- dev-devel
- dev-feature/012-browser-tests-ci
- dev-feature/011-ux-events-css-variables
- dev-feature/010-paste-middleware-relative-links
- dev-feature/009-content-rendering-sanitizer
- dev-feature/008-clean-html-export
- dev-feature/007-presets
- dev-feature/006-required-placeholder-a11y
- dev-feature/005-flex-recipe
- dev-fix/004-assetmapper-relative-import
- dev-feature/003-add-iframe-button
- dev-feature/002-add-namespace-sublevel
- dev-feature/001-add-more-edit-buttons
This package is auto-updated.
Last update: 2026-11-04 09:25:10 UTC
README
A reusable Symfony bundle providing LexicalFormType — a lightweight rich-text editor
form field built on Meta's Lexical, wired for
AssetMapper,
Stimulus and
UX Icons.
The field renders a toolbar (undo / redo, cut / copy / paste — including paste from Word —,
bold, italic, underline, strikethrough, subscript / superscript, remove format, text alignment,
bulleted / numbered lists, indentation, link, unlink, iframe embeds, HTML source editing) and a
contenteditable surface around a hidden <textarea>. The editor reads the
textarea's HTML on load and writes plain, semantic HTML back on every change, so it is a drop-in
replacement for a plain textarea and degrades to that textarea when JavaScript is disabled. No
build step is required — everything runs through AssetMapper's importmap.
Requirements
- PHP 8.2+
- Symfony 7.4 or 8.x with AssetMapper, StimulusBundle and UX Icons
Installation
Make sure Composer is installed globally.
With Symfony Flex
composer require flexible-ux/lexical-bundle
That is the whole installation. Flex registers the bundle in config/bundles.php, adds the Lexical
packages to your importmap.php (from the bundle's assets/package.json) and enables the lexical
Stimulus controller in assets/controllers.json. The bundle's recipe, kept in recipe/
and submitted to symfony/recipes-contrib, additionally
creates config/packages/flexible_ux_lexical.yaml with every application-wide default commented out;
until it is merged, Flex falls back to its auto-generated recipe, which registers the bundle but does
not create that file - add it yourself when you want to change a default (see
Application-wide defaults).
Without Flex
Step 1: Download the bundle
composer require flexible-ux/lexical-bundle
Step 2: Wire the front-end
Add the Lexical packages to your importmap at the constraint the bundle declares in its
assets/package.json — every lexical / @lexical/* package has to be the same version, so require
them together:
php bin/console importmap:require lexical@^0.53.0 @lexical/extension@^0.53.0 @lexical/rich-text@^0.53.0 @lexical/html@^0.53.0 @lexical/clipboard@^0.53.0 @lexical/list@^0.53.0 @lexical/link@^0.53.0 @lexical/history@^0.53.0 @lexical/utils@^0.53.0
Those are the nine packages the controller imports. AssetMapper follows their own imports and adds
what they pull in — the @lexical/extension/* modules, @lexical/selection, @lexical/a11y,
@lexical/dragon and @preact/signals-core — so importmap.php ends up with 44 entries for the
nine you named. Re-running the same command (with the constraint of the bundle version you are on)
is also how you follow a later Lexical bump of the bundle without Flex: it re-pins the nine packages
and refreshes everything they pull in.
Then enable the Stimulus controller in assets/controllers.json:
{
"controllers": {
"@flexible-ux/lexical-bundle": {
"lexical": { "enabled": true, "fetch": "lazy" }
}
}
}
Step 3: Enable the bundle
Register it in config/bundles.php:
// config/bundles.php return [ // ... FlexibleUx\LexicalBundle\FlexibleUxLexicalBundle::class => ['all' => true], ];
That's it. The bundle registers its AssetMapper path, the form theme and the toolbar icons automatically; the editor's CSS is imported by the controller, so there is nothing else to include.
Usage
use FlexibleUx\LexicalBundle\Form\Type\LexicalFormType; $builder->add('description', LexicalFormType::class);
With options:
$builder->add('description', LexicalFormType::class, [ 'label' => 'Description', 'required' => false, 'toolbar' => ['bold', 'italic', 'bullet', 'number', 'link', 'unlink'], 'height' => '320px', ]);
Options
| Option | Type | Default | Description |
|---|---|---|---|
preset |
string |
'default' |
The preset the other options default to: default, full or one configured by the application. |
toolbar |
string[] |
the preset's; default has 14 buttons in six |-separated groups |
Ordered toolbar entries: button names and | separators. |
height |
string |
the preset's; '200px' |
Minimum editable height (any CSS length). |
allowed_link_schemes |
string[] |
the preset's; ['http','https','mailto','tel'] |
URL schemes the link modal accepts. |
allow_relative_links |
bool |
true (the bundle's allow_relative_links key) |
Also accept /path, #fragment and ?query links. |
sanitize |
bool |
true (the bundle's sanitize key) |
Run a changed submission through the bundle's HTML sanitizer. |
Presets
A preset is a named set of the three options above. Two are built in: default, the lean toolbar
every field gets unless told otherwise (history, text formats, lists, indentation, link and embed),
and full, every button there is (the default adds the clipboard buttons, alignment, sub/superscript
and the source editor). Pick one per field, and still override any single option:
$builder->add('body', LexicalFormType::class, ['preset' => 'full']); $builder->add('summary', LexicalFormType::class, ['preset' => 'compact', 'height' => '120px']);
Presets of your own are declared once in the bundle configuration (see
Application-wide defaults); a key a preset leaves out falls back to the
default preset, so compact above only needs to list what makes it compact.
Toolbar and grouping
Available buttons:
undo · redo · cut · copy · paste · paste-word · bold · italic · underline ·
strikethrough · subscript · superscript · remove-format · align-left · align-center ·
align-right · align-justify · bullet · number · indent · outdent · link · unlink ·
iframe · source
Pasting from Word, Outlook or Google Docs just works: every HTML paste (and drop) goes through a
clipboard middleware that recognises Office's markup and cleans it on its way in — conditional
comments and Office namespaces dropped, mso-list paragraphs rebuilt as real, nested
bulleted / numbered lists. The paste and paste-word buttons read the system clipboard through
the asynchronous Clipboard API, so they need a secure context and (browser-dependent) the user's
permission; when access is denied the editor shows a translated hint to paste with
Ctrl+V instead. paste-word forces the Office clean-up for markup the
detection misses — see docs/index.md for details.
The iframe button embeds external content (a video, a map, a form) the way CKEditor's IFrame
dialog did: a modal asks for the URL, an optional width and height, an advisory title and whether
fullscreen is allowed, and the embed is stored as a plain <iframe>. Inside the editor it renders
as a live but inert preview — click it to select it (Backspace removes it, the toolbar
button reopens the dialog to edit it). The frame source must resolve to an http(s) URL; see
docs/index.md for what an imported <iframe> keeps.
The toolbar renders exactly the order you give, and | draws a separator — so grouping is
entirely yours to decide:
'toolbar' => ['bold', 'italic', '|', 'link', 'unlink'], // two groups 'toolbar' => ['bold', 'italic', 'link'], // no separators at all
Every button is optional and independent: only what you list is rendered. A field that does not
want the alignment features simply leaves the align-* entries out (and existing text-align
styles in stored content are still preserved when edited — only the toolbar control disappears):
'toolbar' => ['bold', 'italic', '|', 'bullet', 'number', '|', 'link', 'unlink'], // no alignment 'toolbar' => ['bold', '|', 'align-center'], // or cherry-pick a single alignment button
Leading, trailing and repeated separators are dropped, so a list can never render a stray or doubled
divider. An unknown button name raises a clear InvalidOptionsException listing the valid ones.
The field extends TextareaType, so all textarea/text field options (label, required, attr,
constraints, …) apply too.
Link schemes and relative links
Restrict (or widen) which link schemes the editor may produce — entries may be written with or without
the trailing colon, and anything outside the list is rejected in the link modal. A root-relative path
(/about), a fragment (#top) or a query (?page=2) is accepted as well, because linking the site's
own pages is what a CMS does all day; turn that off with allow_relative_links:
$builder->add('description', LexicalFormType::class, [ 'allowed_link_schemes' => ['https'], // https-only links 'allow_relative_links' => false, // ... and absolute ones only ]);
Required fields, placeholder and labels
The field behaves like the textarea it replaces. A required field (Symfony's default) that is
submitted empty is stopped by the browser as usual; since the browser cannot show its message by the
hidden textarea, the controller shows that same message under the editor, marks the surface
aria-invalid and moves the focus into it. A placeholder passed through attr shows in the
editor while the document is empty. The field's label is linked to the editing surface with
aria-labelledby, so it names the editor for assistive technology and a click on it focuses the
editor; aria-required mirrors the option and the toggle buttons expose their state with
aria-pressed.
$builder->add('description', LexicalFormType::class, [ 'required' => true, 'attr' => ['placeholder' => 'Write something...'], ]);
Application-wide defaults
Rather than repeating options at every call site, set defaults once. The top-level keys are the
default preset every field starts from, and presets adds named ones; every key mirrors a form
option, and per-field options still win:
# config/packages/flexible_ux_lexical.yaml flexible_ux_lexical: toolbar: ['bold', 'italic', '|', 'bullet', 'number', '|', 'link', 'unlink'] height: '320px' allowed_link_schemes: ['https'] presets: compact: toolbar: ['bold', 'italic', '|', 'link', 'unlink'] height: '120px' strict: allowed_link_schemes: ['https']
A preset only lists what it changes: strict above keeps the application's toolbar and height. The
built-in full preset inherits these defaults as well (only its toolbar is fixed), and an application
may redefine it. A typo in a configured toolbar fails at the first cache warm-up, naming the preset.
This is also how a feature is opted out for the whole application at once — the toolbar above,
for instance, has no alignment buttons, so no field gets them unless it overrides the option or picks
a preset that has them.
Run php bin/console config:dump-reference flexible_ux_lexical to see the full reference.
Rendering the stored content
The editor stores plain, semantic HTML: <p>, <strong>, <em>, <u>, <s>, <sub>,
<sup>, <ul> / <ol> / <li>, <a href target rel>, <iframe>, with alignment and indentation
as inline text-align / padding-inline-start styles — no editor classes, no wrapping spans, nothing
a stylesheet of yours has to know about. Render it with the lexical_content filter:
{{ post.body|lexical_content }}
{# <div class="lexical-content"><p>Hello <strong>bold</strong> ...</p></div> #}
The filter runs the HTML through the bundle's sanitizer — Symfony's HtmlSanitizer configured with
exactly what the editor produces: its elements and attributes, the application's
allowed_link_schemes for links, http(s) for frame sources, text-align and
padding-inline-start as the only block styles — and wraps the result in <div class="lexical-content">,
the class the shipped lexical-content.css styles (the editor's own surface carries it too, so the
page looks like the editor). Content the editor wrote passes with nothing removed; anything else is cut down
to the same shape - the wrappers other editors leave behind (<div>, tables, <font>) lose their tag
but keep their text, and <script>, event handlers, media or a javascript: link never make it out. No |raw
needed. lexical_content('prose') picks another class, lexical_sanitize sanitises without the
wrapper, and the sanitizer itself is autowirable as HtmlSanitizerInterface $lexicalHtmlSanitizer
for code that renders or imports stored content outside Twig.
Include the content stylesheet on the pages that render content, for instance from assets/app.js:
import '@flexible-ux/lexical-bundle/styles/lexical-content.css';
The same sanitizer guards the way in: by default a field sanitises what it receives on submission
(the sanitize option, true unless the bundle's sanitize configuration key says otherwise), so a
client without JavaScript, or without the editor's own checks, cannot store what the editor would
not have produced. A field that submits the very string it was rendered with is left alone — that
string is your data, and may legitimately hold markup migrated from another editor.
Extending the editor
The controller dispatches the events Symfony UX controllers use as extension points, on the
field's wrapper and bubbling, so an application controller or a plain listener on document can
hook in without replacing anything:
| Event | When | event.detail |
|---|---|---|
lexical:pre-connect |
Before the editor is built | config: the Lexical extension config (nodes, theme, html.export, dependencies, editable, ...) — mutate it; element: the wrapper |
lexical:connect |
The editor is up and holds the stored document | editor: the LexicalEditor; element |
lexical:disconnect |
Right before the editor is disposed | editor, element — dispatched on document when the wrapper has already left the page |
// assets/controllers/lexical_extras_controller.js import { Controller } from '@hotwired/stimulus'; import { $getSelection, $isRangeSelection, FORMAT_TEXT_COMMAND, COMMAND_PRIORITY_LOW } from 'lexical'; import { HorizontalRuleNode } from '@lexical/extension/HorizontalRuleExtension'; export default class extends Controller { connect() { this.element.addEventListener('lexical:pre-connect', this.onPreConnect); this.element.addEventListener('lexical:connect', this.onConnect); } onPreConnect = (event) => { event.detail.config.nodes.push(HorizontalRuleNode); // a node of your own, or Lexical's event.detail.config.theme.paragraph += ' my-paragraph'; }; onConnect = (event) => { this.unregister = event.detail.editor.registerCommand(FORMAT_TEXT_COMMAND, (format) => { // react to formatting, or return true to swallow it return false; }, COMMAND_PRIORITY_LOW); }; }
Attach it next to the bundle's controller through the field's attr option
('attr' => ['data-controller' => 'lexical-extras'] lands on the textarea, so listen on
document instead, or add the controller to the wrapper in an overridden form theme). The events
bubble, so document.addEventListener('lexical:pre-connect', ...) in assets/app.js is the simplest
place for a change meant for every editor.
Theming
Every colour, radius and font of the editor and of the rendered content is a CSS custom property
with a default on :root, so a theme is a block of variables, not a set of overrides:
/* assets/styles/app.css */ :root { --lexical-accent: #0d6efd; --lexical-accent-dark: #0b5ed7; --lexical-radius: 6px; --lexical-link-color: #0d6efd; } @media (prefers-color-scheme: dark) { :root { --lexical-bg: #1e1e1e; --lexical-color: #e6e6e6; --lexical-toolbar-bg: #2a2a2a; --lexical-border-color: #444; --lexical-button-hover-bg: #3a3a3a; } }
The editor's variables (--lexical-border-color, --lexical-bg, --lexical-color,
--lexical-muted-color, --lexical-toolbar-bg, --lexical-button-hover-bg, --lexical-accent,
--lexical-accent-dark, --lexical-accent-contrast, --lexical-error-color, --lexical-error-bg,
--lexical-radius, --lexical-dialog-shadow, --lexical-backdrop, --lexical-font-mono) are
declared in lexical.css; the content's (--lexical-content-spacing, --lexical-link-color,
--lexical-quote-border-color, --lexical-quote-color, --lexical-code-bg, --lexical-mark-bg) in
lexical-content.css. Rules keep class specificity, so a global reset never wins over them and
your own .lexical-content p rules do.
How it works
The bundle is deliberately split into four layers so each can be understood and overridden on its own:
- PHP —
FlexibleUx\LexicalBundle\Form\Type\LexicalFormTypeexposes thetoolbar/heightoptions as view variables. - HTML — the
lexical_widgetTwig form theme renders the toolbar, the editable surface and the link modal. - JS — the
lexicalStimulus controller mounts Lexical on the editable element and keeps the textarea in sync. - CSS —
assets/styles/lexical.css, the editor's chrome, andassets/styles/lexical-content.css, the stored content (both imported by the controller; the second is also for the pages that render the content). - Rendering — the
lexical_content/lexical_sanitizeTwig filters and theflexible_ux_lexical.html_sanitizerservice behind them and behind thesanitizeoption.
See docs/index.md for customisation, theming and translation details.
Development
composer install vendor/bin/phpunit # unit and integration tests vendor/bin/bdi detect drivers # once: a chromedriver matching your Chrome, into drivers/ php tests/Browser/Harness/build.php # once per Lexical constraint: the harness importmap (needs network) vendor/bin/phpunit --testsuite browser # the editor in a headless Chrome, through Symfony Panther
The browser suite drives the editor in Chrome through Symfony Panther
against the harness application in tests/Browser/Harness, a consumer of the bundle wired the way
composer require wires one (AssetMapper, importmap, StimulusBundle's loader, UX Icons). It covers
what PHPUnit alone cannot: mounting, the untouched stored value, the semantic export and its round
trip, required and placeholder, the label, presets, the link modal and relative links, the Office
paste clean-up, the clipboard, the extension events and the rendering filter. CI runs it on every
push, and a weekly workflow fails when a Lexical release the bundle's constraint does not cover is
out - the cue to read its release notes and bump (php tests/Browser/Harness/build.php '^0.54.0'
rebuilds the harness against another constraint to try one).
License
Released under the MIT License. Bundled icons are from Lucide (ISC License).
