draw.io is a JavaScript, client-side editor for general diagramming.
Dialog Style Guide
All new dialogs using CustomDialog should follow these patterns for consistent
appearance. CSS classes are defined in /src/main/webapp/styles/grapheditor.css.
Auto-Height
Pass null for the height parameter in showDialog(). The Dialog constructor
measures elt.scrollHeight after the element is in the DOM and sizes the dialog
automatically. Never compute dialog heights manually with height += N increments.
var dlg = new CustomDialog(this, div, okFn, null, mxResources.get('export'), helpLink);
this.showDialog(dlg.container, 360, null, true, true);
Viewport Overflow
.geDialog is capped at viewport height by max-height: 100%. When the natural
dialog height exceeds the viewport (small screens, expanded sections), the
content area becomes scrollable so the footer stays reachable:
- CustomDialog: the wrapper is a flex column. Content sits in a scrollable
middle region (
flex: 1 1 auto; min-height: 0; overflow-y: auto). The button row isflex: 0 0 autoand stays pinned at the bottom. - Other dialogs: a CSS safety net (
.geDialog > :first-child) appliesmax-height: 100%; overflow-y: autoso the content scrolls if it overflows — buttons inside scroll with the content but remain reachable. - Close button (
.geButton): positioned-absolute sibling of the content, so it stays at the top-right regardless of scroll.
Spacing (handled by CustomDialog and Dialog)
- Dialog padding: 24px on all sides (
.geDialogCSS) - Title margin-bottom: 16px (
.geDialog h3CSS) - Buttons margin-top: 34px (default in
CustomDialog) - Container padding-bottom: 10px (
CustomDialogadds this to prevent margin collapse) - Dialog chrome:
Dialogconstructor adds 48px to both width and height for padding
These produce equal visual spacing above (34px) and below (34px = 10px + 24px) the button row. Do not override these values in individual dialogs.
Sections (geDialogSection)
Group related controls in rounded section containers:
var section = document.createElement('div');
section.className = 'geDialogSection';
// ... add rows to section ...
div.appendChild(section);
Row spacing is uniform and CSS-driven. Every row inside a section
(geDialogFormRow, geDialogCheckRow, geDialogInlineFields) is spaced a
uniform 6px from the previous one; the first visible row sits flush against the
section's 10px top padding. This is handled centrally in grapheditor.css — do
not add per-row margin-top (it only breaks the uniform rhythm). Because the
gap is between rows regardless of type, a section can freely mix form rows, check
rows and inline fields and they stay evenly spaced.
For the same reason, always wrap controls in a proper row class (or use
addCheckbox(..., useCheckRow=true)): row classes carry min-height: 28px, so
mixing a bare addCheckbox (no useCheckRow, which appends a raw
<input><label><br>) with row-based controls in one section yields inconsistent
row heights. A bare checkbox gets the same 6px fallback gap, but prefer
useCheckRow=true everywhere. If a first row can be hidden conditionally, remove
it from the DOM (e.g. cb.checkRow.parentNode.removeChild(cb.checkRow)) rather
than display:none — otherwise the now-visually-first row still loses its
:first-child top reset.
Collapsible "Advanced" Section (addAdvancedSection)
For options that aren't needed in the common case (e.g. Edit / Layers / Tags
in the Publish Link, HTML Embed, and Embed Image dialogs), use
EditorUi.addAdvancedSection(parent). It renders the same collapsible header
the Format panel uses (.geCollapsibleTitle + rotating CSS triangle, content
wrapped in .geCollapsibleContent) and the inner container is a regular
geDialogSection so checkbox rows look identical to the always-visible
section above it.
var advanced = this.addAdvancedSection(div); // labelKey defaults to 'advanced'
var advSection = advanced.content; // geDialogSection inside
this.addCheckbox(advSection, mxResources.get('layers'),
true, null, null, null, null, null, true);
this.addCheckbox(advSection, mxResources.get('tags'),
true, null, null, null, null, null, true);
Collapsed by default. The helper recomputes the enclosing .geDialog's
height on every toggle so the new rows are not clipped by the dialog's
overflow:hidden (the Dialog constructor only measures once, at open time).
Do not pass an explicit height to showDialog — keep null so the initial
measurement covers the collapsed state cleanly.
To keep multiple separate section cards inside the collapsed area, append
additional geDialogSection divs to advanced.wrapper (the collapsible
container); advanced.content then serves as the first card (see the
Page Setup dialog).
Form Rows (geDialogFormRow)
Use for label + input pairs (text fields, selects):
var row = document.createElement('div');
row.className = 'geDialogFormRow';
var lbl = document.createElement('span');
lbl.className = 'geDialogFormLabel';
mxUtils.write(lbl, mxResources.get('zoom') + ':');
row.appendChild(lbl);
var input = document.createElement('input');
input.setAttribute('type', 'text');
row.appendChild(input);
section.appendChild(row);
Checkbox Rows (geDialogCheckRow)
Use addCheckbox with useCheckRow=true (9th parameter) for consistent checkbox
layout with flex alignment:
var cb = this.addCheckbox(section, mxResources.get('shadow'),
false, null, null, null, null, null, true);
For indented sub-options (e.g., "Layers" under "Lightbox"):
cb.checkRow.style.paddingLeft = '24px';
Inline Fields (geDialogInlineFields / geDialogInlineField)
Use for side-by-side fields (e.g., Width + Height):
var row = document.createElement('div');
row.className = 'geDialogInlineFields';
var field = document.createElement('div');
field.className = 'geDialogInlineField';
// ... add label + input to field ...
row.appendChild(field);
section.appendChild(row);
Dialog Title
A plain <h3> — all styling comes from the central .geDialog h3 rule
(centered, 16px bottom margin, flex-shrink: 0 for flex-column layouts):
var hd = document.createElement('h3');
mxUtils.write(hd, title);
div.appendChild(hd);
Never set inline styles on dialog titles; if a special layout genuinely needs different margins (e.g. a title inside a header row), the inline override is the documented exception, not the norm.
Edit Button (Lightbox Dialogs)
Use addEditButton which creates a geDialogCheckRow with an indented select:
var editSection = this.addEditButton(optSection, lightbox);
var edit = editSection.getEditInput();
Alignment of Dialog Items
Radio/checkbox rows (geDialogCheckRow) use flexbox with align-items: center.
When a radio button is followed by an input or select, both elements sit after
the radio's right margin (8px). The CSS rule .geDialogCheckRow select adds
margin-left: 8px by default — this is intended for selects that follow a
checkbox + label. When a select sits directly after a radio button (same position
as a text input in another row), reset the margin so both align:
pageSelect.style.marginLeft = '0';
For geDialogFormRow, the geDialogFormLabel span provides a fixed-width left
column (min-width: 100px). All inputs and selects use flex: 1 to fill the
remaining space. The row has a column-gap: 8px so the label never butts against
the control even when a long (e.g. German) label grows past the 100px column — do
not add per-control marginLeft inside a form row, and if a longer label needs
more room, increase the dialog width rather than overriding min-width on
individual labels.
Multi-Line Rows (geDialogFormRowTop)
geDialogFormRow centers the label vertically, which is correct for
single-line rows. When the row's content spans multiple lines — stacked
controls (e.g. the Page Setup paper-size panel) or wrapping hint text —
add geDialogFormRowTop so the label top-aligns with the first content
line instead of floating against the middle of the block:
row.className = 'geDialogFormRow geDialogFormRowTop';
The class sets align-items: flex-start and pads the label so it sits
optically on the first line. Do not top-align single-line rows — mixed
alignments within one dialog read as a bug.
Typography
Dialogs inherit the app font (.geEditor, 14px system stack). Never set
font family, size or weight inline in a dialog — every text role has a
central rule:
| Role | Size / weight | Where it comes from |
|---|---|---|
| Title | ~16px bold | plain <h3> (see Dialog Title) |
| Labels, checkbox text, body | 14px normal | inherited — no styling needed |
| Controls (input, select, textarea) | 13px normal | .geDialog CSS; selects that borrow .geBtn for sizing are forced back to normal weight by .geDialog select |
| Buttons | 14px / weight 550 | .geBtn — buttons only, never text |
| Hint / muted secondary text | 12px muted | .geDialogHint |
| Collapsible section header | 13px | addAdvancedSection (.geCollapsibleTitle) |
geDialogHint covers all muted secondary text: explanatory hints
describing what an option does (e.g. the lightbox-animation note in Page
Setup), unit suffixes next to compact inline inputs (e.g. "ms"),
de-emphasized checkbox labels in dense header rows, and empty-state
placeholders. The current value of an entry (e.g. the Initial View
status) is content, not a hint — it uses the regular text style.
Component stylesheets that define their own micro-typography (e.g. the
cell/tag selector chips in the Animation dialog) keep their own sizes
and weights but reuse the hint palette,
light-dark(var(--secondary-text-color), var(--dark-secondary-text-color))
— don't fork new muted grays.
Truncated text: .geDialog uses line-height: 1em, so an
auto-height element that truncates with overflow: hidden; text-overflow: ellipsis clips glyph descenders (e.g. the "g" in
German "Vorgegeben"). Give such elements line-height: normal so the
line box has full glyph height; the ellipsis still handles horizontal
overflow.
If a new dialog needs a size or weight this table doesn't cover, add a class and a table row — one-off inline font styles are how inconsistencies creep in.
Non-Resizable Dialogs
Most dialogs are non-resizable. Do not pass a minSize parameter to
showDialog() — this avoids adding a resize handler. Use null for the height
parameter so the dialog auto-sizes to its content:
this.showDialog(dlg.container, 360, null, true, true);
Only pass minSize (a mxRectangle) when the dialog content is scrollable or
has a variable-height area that benefits from user resizing.
Button Spacing (Manual Buttons)
When using CustomDialog, button spacing is handled automatically (34px
margin-top, 10px padding-bottom on the content wrapper). When building buttons
manually (e.g., dialogs with custom button arrangements like Reset + Open),
replicate the same values:
// Content wrapper needs padding-bottom to prevent margin collapse
div.style.paddingBottom = '10px';
// Button row
var btns = document.createElement('div');
btns.style.marginTop = '34px';
btns.style.textAlign = 'right';
This produces equal visual spacing above (34px) and below (34px = 10px + 24px
dialog padding) the button row, matching CustomDialog exactly. Never use
other margin values (16px, 20px, 30px) for button rows.
Dark Mode
All CSS uses light-dark() for color values. Never hardcode colors in JS — use
the CSS classes which handle both modes automatically.
Colors come from the theme palette defined in the :root block of
styles/grapheditor.css (--strong-text-color, --field-color,
--field-border-color, --focus-color, … and their --dark-*
counterparts). Always reference these variables instead of literal hex
values — user color schemes override the variables via the css
configuration property, and literals silently opt a component out of
theming. Alpha tints of an accent derive from it via
color-mix(in srgb, var(--focus-color) 25%, transparent). The exception
is CSS injected by viewer-shared code (e.g. geNoteBox in Graph.js):
the viewer runs on third-party pages where the variables don't exist and
generic names could collide with host CSS, so literals stay there.
Keyboard Focus
Modal dialogs keep Tab inside the dialog (Dialog.installFocusTrap): Tab on
the last control focuses the first, Shift+Tab on the first focuses the last,
and Tab while the focus is behind the dialog (diagram, search box) moves it
into the dialog. The trap uses the visible, enabled controls in document
order (Dialog.getTabStops), so don't use positive tabindex values. A
control that handles Tab itself (eg. an autocomplete) must consume the event
(mxEvent.consume) so the trap leaves it alone. Focus the first input in the
dialog's init — callers that focus something else afterwards must check
document.activeElement first (see focusGraph in
Sidebar.addSearchPalette).
Shift+arrow keys move the focus to the nearest control in that direction
(EditorUi.focusTabStopInDirection). Shift+Arrow Left and Right stay in the
row and continue with the previous or next control in the order of Tab at
its ends, eg. from the preview of the More Shapes dialog to its buttons.
Arrow keys without Shift scroll areas that scroll, so a part of a dialog that
scrolls and has no controls, eg. a preview, needs tabindex="0" for the
keyboard.
Buttons (geBtn, also gePrimaryBtn) and collapsible titles
(geCollapsibleTitle) show the keyboard focus as a 2px outline in the focus
color (:focus-visible). Dark mode removes all shadows (body.geDarkMode *
sets box-shadow: none !important), so a focus ring must be an outline,
never a box-shadow. The outline is inside of the element
(outline-offset: -2px): the content of dialogs scrolls
(.geDialog > :first-child), which would clip a ring outside of controls at
its edges.
Every dialog has role="dialog" (and aria-modal if modal), and screen
readers name it after the first <h3> or .geDialogTitle in its content
(aria-labelledby), so give dialogs a title of that kind. A dialog without
such a title sets aria-label on its content element (the one passed to
showDialog), which the dialog moves to itself (eg. Edit Data). When a dialog
closes, the focus goes back to the control that opened it with the keyboard
(Dialog.getReturnFocus: a button, checkbox or select outside the diagram
that matches :focus-visible, eg. in the format panel or in another
dialog). Otherwise it goes to the diagram or to the label being edited.
Names, Images and Targets
Screen readers and the axe checks of the accessibility reports
(security-privacy-legal, scripts/vpat_axe_test.js) need:
- A name for every field: text before a field is no
<label>, so setaria-labelon inputs, selects and text areas (eg. the Filename field of the library dialog). alton every image:alt=""for icons inside a named control or with a name next to them (droppers, resize grips), else a text (the preview of the More Shapes dialog).- Targets of 24px (WCAG 2.5.8): icon buttons get padding up to 24px and a negative margin of the same size, so the row does not change (Swap, Copy and Opacity of the color window). Smaller targets need 24px from center to center (the dots of the color schemes).
- Contrast of 4.5:1 for text: gray text uses
#5f5f63in light mode and#a0a0a0in dark mode (geMenuShortcut), notgrayor an opacity. Text on a color picks black or white by the relative luminance (ColorDialog.hasDarkText).
Testing Dialogs
Use ?dev=1&ui=classic to keep the menubar visible regardless of window size.
Test with both single-page and multi-page diagrams, as extra controls appear
when multiple pages exist.