Views, Settings, and UI
Build portable host-rendered plugin views, settings, sidebar items, status items, and menus.
Views, sidebar items, status bar items, context menu items, and settings are declared data. Cortex renders them with host components; plugins never ship React or DOM code. None of them need a permission.
Declare a View#
type CounterState = { count: number }contributes: { views: [ { id: "counter", label: "Counter", icon: "plus", location: "sidebar-left", initialState: { count: 0 }, render: (state: CounterState) => ({ type: "stack", gap: "md", children: [ { type: "heading", value: "Counter" }, { type: "text", value: `Count: ${state.count}` }, { type: "button", label: "Increment", action: "increment", variant: "primary" }, { type: "button", label: "Insert", action: "insert" }, ], }), reduce: (state: CounterState, action) => action === "increment" ? { count: state.count + 1 } : state, onAction(ctx, action, _payload, state) { if (action === "insert") ctx.editor.insertAtCursor(String(state.count)) }, }, ],},render(state, ctx)returns portable descriptors. Annotatestatewith a type alias for typed views.reduce(state, action, payload)is pure and updates host-owned state.onAction(ctx, action, payload, state)runs side effects afterreduce(editor writes, opening tabs, persisting data). Permissions still apply.- Omit
renderto resolveviews[id]fromload(); Cortex shows a spinner until it loads. - Each view renders inside an error boundary, so a throwing view cannot crash the app.
View Locations#
Views can render in:
tabsidebar-leftsidebar-rightmodal
Open views with ctx.workspace.openView(id) (requires workspace:tabs) or modal views with
ctx.ui.openModal(id). View ids are type-checked.
Sidebar, Status Bar, and Context Menus#
contributes: { sidebarItems: [{ id: "counter", label: "Counter", icon: "plus", view: "counter" }], statusBarItems: [ { id: "counter-status", position: "right", icon: "plus", text: "Counter", tooltip: "Open counter", command: "open-counter", when: "showStatus", }, ], contextMenuItems: [ { id: "count-file", label: "Count words", location: "file", command: "count-words" }, ],},Status bar and context menu items execute one of the plugin's command ids. Context menu commands
receive a ContextMenuActionContext payload (file, editor, or tab target). when shows a
status bar item only while a boolean setting is true.
Settings#
Declare a settings schema once; Cortex renders a settings page titled with the plugin name,
persists values to <vault>/.cortex/plugins/<plugin-id>/settings.json, and applies defaults.
settings: { showStatus: { type: "boolean", label: "Show status item", default: true }, maxItems: { type: "slider", label: "Maximum items", default: 5, min: 1, max: 20, step: 1 }, mode: { type: "select", label: "Mode", default: "compact", options: [ { value: "compact", label: "Compact" }, { value: "full", label: "Full" }, ], },},activate(ctx) { const mode = ctx.settings.get("mode") ctx.settings.onChange("maxItems", (value, oldValue) => console.log(value, oldValue))},ctx.settings.get(key) returns the stored value or the schema default, typed from the schema
("compact" | "full" above). set, getAll, and onChange are typed the same way. Supported
field types are text, number, boolean, select, slider, color, and folder-path.
Portable UI Nodes#
Use the descriptor nodes exposed by @cortex.md/api: stack, row, text, heading, button,
icon-button, input, textarea, toggle, checkbox, select, slider, icon, separator, list, list-item,
scroll-area, badge, progress, empty, markdown, setting-row, item, alert, tabs, and table.
Do not expose React components, DOM nodes, inline styles, arbitrary event handlers, or free
className values.