markdownEditor

markdownEditor is a field for writing and previewing Markdown content. It behaves like a standard input field, so it supports label, helper text, required indicator, validation message, tooltip, and data binding.

XML Element

markdownEditor

Java Class

JmixMarkdownEditor

Attributes

id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - justifySelf - label - maxHeight - maxWidth - minHeight - minWidth - mode - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - valueChangeMode - valueChangeTimeout - visible - width

Handlers

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - ModeChangeEvent - statusChangeHandler - validator

Elements

tooltip - validators

Basics

Use markdownEditor when users need to enter Markdown with quick formatting controls and an instant preview.

<markdownEditor id="markdownEditor"
                themeNames="toolbar-align-end"
                label="Markdown Editor"
                helperText="Markdown is supported. Use the toolbar or keyboard shortcuts to format text."
                placeholder="Write your content here..."/>
markdown editor

The component value is a String containing raw Markdown markup.

Data Binding

Like other field components, markdownEditor can be bound to an entity attribute using the dataContainer and property attributes.

<markdownEditor id="descriptionField"
                dataContainer="orderDc"
                property="description"
                label="Description"/>

Bind the component to a String entity attribute that stores Markdown text.

Modes

The editor has two modes selectable in the header:

  • Edit lets users enter and format Markdown text.

  • Preview renders the current value as formatted HTML.

The default mode is Edit.

You can set the initial mode declaratively using the mode XML attribute.

<markdownEditor id="markdownEditorField"
                mode="PREVIEW"/>

If readOnly = true, the component shows only the rendered preview. The toolbar and mode tabs are hidden, and the value cannot be changed.

The current mode can also be read and changed programmatically using the server-side API. When the mode changes, the component fires a ModeChangeEvent containing the new mode and a flag indicating whether the change was initiated by the user or by the application.

Toolbar Actions

In Edit mode, the mode tabs and formatting toolbar share the same header row. If there is not enough horizontal space, extra toolbar actions are moved to the overflow menu at the end of the row.

Toolbar buttons reflect the formatting active at the current caret position. Clicking an already active formatting button removes the corresponding formatting.

Wrap Formats

These actions operate on the current selection, or on the caret position when nothing is selected.

Action Shortcut Apply Remove

Bold

Cmd/Ctrl+B

Wraps the selected text with **. If nothing is selected, inserts **** and places the caret between the markers.

Removes surrounding **.

Italic

Cmd/Ctrl+I

Wraps the selected text with _. If nothing is selected, inserts __ and places the caret between the markers.

Removes surrounding _.

Code

Cmd/Ctrl+E

Wraps the selected text with a single backtick. If nothing is selected, inserts two backticks and places the caret between them.

Removes surrounding backticks.

Link

Cmd/Ctrl+K

Wraps the selection as [text](url). If nothing is selected, inserts [](url) and places the caret inside [].

Removes the surrounding Markdown link markup.

Line Formats

These actions work with the current line, or with every selected line when multiple lines are selected.

Action Apply Remove

Heading

Adds the ## prefix at the beginning of the line.

Removes the ## prefix.

Quote

Adds the > prefix at the beginning of the line.

Removes the > prefix.

Unordered list

Adds the - prefix at the beginning of the line.

Removes the - prefix.

Ordered list

Adds the 1. prefix at the beginning of the line.

Removes the numeric list prefix.

Task list

Adds the - [ ] prefix at the beginning of the line.

Removes the - [ ] prefix.

When multiple lines are selected and all of them already have the target format, clicking the toolbar button removes it from all selected lines. Otherwise, the format is applied to all selected lines that do not already have it.

Keyboard Navigation

The component supports keyboard navigation across three logical focus areas:

  • Mode tabs

  • Toolbar

  • Text area

Tab moves focus between these areas. Arrow keys navigate inside the active area. Press Escape in the toolbar to return focus to the text area.

If some toolbar actions are moved into the overflow ยทยทยท menu, the first menu item receives focus when the menu opens. In the menu, ArrowUp and ArrowDown move between items, while Escape and Tab close the menu and return focus to the overflow button.

Formatting changes integrate with the browser undo stack, so standard shortcuts work as expected:

  • Cmd/Ctrl+Z undoes formatting and typing changes.

  • Cmd/Ctrl+Shift+Z or Ctrl+Y redoes formatting and typing changes.

Theme Variants

Use themeNames attribute to set a component theme.

Variant Description Supported By

helper-above-field

Renders the helper above the field, below the label.

Aura, Lumo

toolbar-align-start

Aligns toolbar buttons to the start side of the header, taking the current text direction into account.

Aura, Lumo

toolbar-align-center

Centers toolbar buttons within the header and hides the divider.

Aura, Lumo

toolbar-align-end

Aligns toolbar buttons to the end side of the header, taking the current text direction into account, and hides the divider.

Aura, Lumo

CSS Properties

You can customize the component using CSS custom properties in the application theme or by setting them through the css attribute.

<markdownEditor id="markdownEditCss"
                css="--jmix-markdown-editor-default-width: 32rem;
                     --jmix-markdown-editor-header-background: var(--lumo-contrast-5pct);"/>
Property Description Supported By

--jmix-markdown-editor-default-width

Sets the default component width.

Aura, Lumo

--jmix-markdown-editor-header-background

Sets the background of the shared header row containing tabs and the toolbar.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-padding

Controls toolbar button padding.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-width

Controls toolbar button border width.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-color

Controls toolbar button border color.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-border-radius

Controls toolbar button border radius.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-text-color

Controls toolbar button text color.

Aura, Lumo

--jmix-markdown-editor-toolbar-button-background

Controls toolbar button background.

Aura, Lumo

--jmix-markdown-editor-tab-padding

Controls tab padding.

Aura, Lumo

--jmix-markdown-editor-tab-text-color

Controls tab text color.

Aura, Lumo

--jmix-markdown-editor-tab-background

Controls tab background.

Aura, Lumo

Internationalization

All user-visible strings have English defaults and can be overridden independently.

The component provides default captions for:

  • Tabs: Edit, Preview

  • Toolbar actions: Heading, Bold, Italic, Quote, Code, Link, Unordered list, Ordered list, Task list

  • Overflow menu button

  • Toolbar accessible name

If the application overrides only part of these strings, all other captions continue to use their default values.

Validation

To check values entered into the markdownEditor component, you can use a validator in a nested validators element.

Because the component value is stored as a raw Markdown string, validators such as notBlank and size are useful for checking whether the content is present and within the expected length.

The following predefined validators are available for markdownEditor:

XML Element

validators

Predefined validators

custom - notBlank - notEmpty - notNull - size

Attributes

Common attributes serve the same purpose for all components. The following attributes are specific to markdownEditor:

Name

Description

Default

mode

Sets the editor mode.

EDIT

Handlers

Common handlers are configured in the same way for all components. The following handlers are specific to markdownEditor.

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

Name

Description

ModeChangeEvent

JmixMarkdownEditor.ModeChangeEvent fired when the editor switches between Edit and Preview mode. The event contains the new mode and a flag indicating whether the change was initiated by the user or by the application.

See Also

See also markdown for rendering Markdown content without editing capabilities.