These are the docs of plugin API 1.7, as Textus 1.4.3 had them. API 1.8 is the newest.

A plugin's interface

How a plugin shows things so it looks and behaves like the rest of Textus: which layer to use, the five kinds of surface, every control a page may use, and the rules for sizes and colours. The design standard behind it is design-language.md §5.6 and §15; how pages work (webviews, messages, menus, dragging) is pages.md.

Four layers, most preferred first

Layer The plugin Textus Use it for
1. Declared writes settings, commands, menus, key bindings and status items in its manifest draws them all anything that is a setting, an action or a word in the status bar
2. Drawn by Textus calls an API with the data: views.registerList, ui.pick, ui.input, ui.form, ui.pickDate, ui.pickColor, ui.notice, ui.withProgress, ui.confirm draws it as its own lists in the sidebar, choices, questions, dates, colours, progress, notes
3. A page of shared controls writes a page using only the controls below gives the controls' look, size, colours, keys and motion a board, a table, a calendar, a viewer's toolbar
4. Free drawing draws content itself: a chart, a canvas, a picture, a PDF page gives the colour tokens and the scale the content only - never its bars, buttons or lists

A plugin MUST use the first layer that can do the job. In layers 3 and 4, everything around the content - bars, buttons, lists, empty states - is made of the shared controls.

Five surfaces

Each kind of surface has one shape. A plugin's surface is one of these.

Surface Opened with Shape
Sidebar panel views.registerList (preferred) or a sidebar webview a title row (its name, at most two circle icon buttons) → an optional search field → a tx-list → a tx-empty
Editor or tab view views.registerFileEditor, layout.openView a tx-bar var(--bar-height) high (start: navigation and view switching; end: actions, the primary button last) → the content
Block in the document views.registerCodeBlock a figure (chart, diagram): the content alone, one line for an error. A record (a database, tasks): one tx-bar, then the content, at most 70% of the window high, scrolling inside. Its bar leaves var(--block-source-room) at its end for the block's source button. It draws no fold arrow and no title of its own: Textus folds blocks
Floating view contributes.floatingViews the content alone, its manifest's size, scaled with the interface; folded, a dot
Settings declared settings (preferred) or a settings page tx-group-title, tx-group, tx-row: Settings' own look

Controls

Class names are public API: write them as below, and don't restyle them. Every control takes its sizes from tokens, so it grows with the interface, and its colours from the theme, so it follows light, dark and every theme.

Buttons and fields

Control Markup Notes
Button <button class="tx-button">Cancel</button> small in bars and cards
Primary button <button class="tx-button primary">Save</button> at most one per group, last
Icon button <button class="tx-icon-button" aria-label="Filter"><span class="tx-icon" data-icon="filter"></span></button> a circle; aria-label required
Icon <span class="tx-icon" data-icon="calendar"></span> names in design-language.md §15.4
Field <input class="tx-input"> a capsule; <textarea class="tx-input"> a box
Field in place <input class="tx-inline-input"> no frame: the cell or card it sits in is the field
Square corners add tx-square to a button, field or select capsules by default; square where a grid or table wants it
Checkbox <input type="checkbox" class="ui-check"> ticking things off
Switch <input type="checkbox" role="switch" class="tx-switch"> turning a setting on and off
Select <button class="tx-select">Week<span class="tx-icon" data-icon="chevron"></span></button> opens Textus's menu: api.menu(items, button)
Slider <input type="range" class="tx-slider"> var(--slider-width) wide
Segmented <div class="tx-segmented" role="tablist"><button class="tx-segment" role="tab" aria-selected="true">Table</button>…</div> 2–5 views or modes
Chip <button class="tx-chip">Status is Done</button> a rule in force; opens it
Tag <span class="tx-tag" data-tone="green">Done</span> status adds a dot; tones in their order
Badge <span class="tx-badge" data-tone="accent">New</span> beside a name; tones accent, warning, danger, strong

Bars and navigation

Control Markup Notes
Bar <div class="tx-bar">…<span class="tx-spacer"></span>…</div> navigation first, actions last
Zoom <div class="tx-zoom"><button class="tx-icon-button" aria-label="Zoom out">…minus…</button><button class="tx-value">100%</button><button class="tx-icon-button" aria-label="Zoom in">…plus…</button></div> the value resets the zoom when clicked
Pager <div class="tx-pager"><button class="tx-icon-button" aria-label="Previous">…left…</button><span class="tx-value">3 / 12</span><button class="tx-icon-button" aria-label="Next">…right…</button></div> pages, slides, months
Find <div class="tx-find"><input class="tx-input" type="search"><span class="tx-value">2 / 9</span>…arrows…</div> matches in the page take tx-hit, the current one tx-hit is-current

Lists, groups and folding

Control Markup Notes
List <div class="tx-list" role="listbox"><button class="tx-list-row" role="option" aria-selected="true"><span class="tx-list-label">Draft</span><span class="tx-list-meta">2 min</span></button></div> one tab stop, arrows move (design-language.md §9)
List heading <div class="tx-list-heading">Today</div> between rows: a day, a group
Folding <details class="tx-disclosure"><summary>Advanced</summary>…</details>, or a button with aria-expanded holding <span class="tx-disclosure-caret"></span> the app's own caret
Settings group <div class="tx-group-title">General</div><div class="tx-group"><div class="tx-row"><span>Label</span>…</div></div> Settings' look
Card <div class="tx-card">…</div> a hairline, no shadow
Table <div class="tx-table-frame"><table class="tx-table">…</table></div> the document's table look
Empty state <div class="tx-empty">No tasks yet.<button class="tx-button">New task</button></div> one sentence, at most one button

Records and progress

Control Markup Notes
Calendar <div class="tx-calendar"><span class="tx-calendar-weekday">M</span>…<button class="tx-calendar-day is-today is-marked" aria-selected="false">8</button>…</div> is-other for days outside the month
Board <div class="tx-board"><div class="tx-lane"><div class="tx-lane-head">…</div>…cards…</div></div> lanes var(--board-lane-width) wide
Rating <span class="tx-rating">★★★☆☆</span>, or ★ <span class="tx-value">7.5</span> past five one look down a whole column
Progress <div class="tx-progress" role="progressbar" style="--value: 0.4"></div>; is-indeterminate; ring for a circle var(--progress-ring-size) across, its line --progress-ring-line; a ring is-indeterminate is a spinner
Bubble <div class="tx-bubble" data-bubble-tail="bottom">…</div>; the tail top, bottom, left or right, placed along it by style="--tail-at: 30%" a floating view's line, beside it
Edge fade <div class="tx-scroll-fade">…</div> on a scroller its edges fade where there is more

Dragging

Two kinds, as in the rest of Textus. A row of tabs or columns put in a new order is the page's own textus.drag.reorder (API 1.7): the item itself follows the pointer along its row, the others slide aside, nothing floats, and let go it is in its new place at once. Things moved between lists (cards between a board's lists) use drag.sortable from lib/drag.js (pages.md › Dragging): a lifted copy follows the pointer. Either way it stays under the point it was taken by, in a zoomed document too.

Sizes and colours

The plugins repository's check reports fixed pixels, literal colours and hand-drawn copies of these controls.

This page is ui.md in the Textus repository.