UI Reference

UI Reference

Use sigma.ui to show feedback and build lightweight extension interfaces.

Clipboard

Plain text

sigma.ui.copyText(text)

• Requires the clipboard permission.
• Copies plain text to the system clipboard.

Rich clipboard

sigma.ui.clipboardWrite(items)

• Requires the clipboard permission.
• items is an array of maps from MIME type string to Uint8Array payload. Supported types include text/plain, text/html (optionally with text/plain as fallback), and image/png. The implementation writes the first supported representation it finds in order (image/png, then text/html, then text/plain).

Notifications

Signature

sigma.ui.showNotification(options)

Options

Field	Description
title	Required notification title
subtitle	Optional secondary text
description	Optional body text
type	info, success, warning, or error
duration	Optional duration in milliseconds

Notes

• Requires the notifications permission.
• Best used for short success, warning, and error feedback.

Dialogs

Signature

sigma.ui.showDialog(options)

Options

Field	Description
title	Dialog title
message	Main message
type	info, confirm, or prompt
confirmText	Confirm button label
cancelText	Cancel button label
defaultValue	Default prompt value

Return

Returns Promise<{ confirmed: boolean, value?: string }>

Notes

• Requires the dialogs permission.
• Use prompt when you need a single string input.

Progress

Signature

sigma.ui.withProgress(options, task)

Options

Field	Description
subtitle	Progress title text
location	notification or statusBar
cancellable	Whether the user can cancel the task

Task Utilities

The task receives:

Value	Description
progress.report(...)	Updates visible progress
token.isCancellationRequested	Indicates cancellation
token.onCancellationRequested(...)	Registers a cancellation listener

progress.report(...) supports:

Field	Description
subtitle	Current step label
description	Additional details
increment	Incremental progress value
value	Absolute progress value

Custom Modals

Quick Modal

const result = await sigma.ui.showModal(options)

Returns Promise<Record<string, unknown> | null>. Resolves with form values on submit, or null when the user closes the modal. Use this when you only need to collect values and don't need live event hooks.

Full Modal

const modal = sigma.ui.createModal(options)

Options

Field	Description
title	Modal title
width	Optional modal width
content	Array of UIElement values
buttons	Optional custom action buttons

Each button supports:

Field	Description
id	Unique button identifier
label	Button label
variant	Optional primary, secondary, or danger
shortcut	Optional keyboard shortcut: { key, modifiers? } where modifiers can include ctrl, shift, alt, meta

Modal Handle

Method	Description
onSubmit(callback)	Called when a modal action button submits. The callback receives (values, buttonId) and may return false to keep the modal open
onClose(callback)	Called when the modal closes
onValueChange(callback)	Called when a field value changes
close()	Closes the modal programmatically
updateElement(id, updates)	Updates a single element definition
setContent(content)	Replaces the modal content
setButtons(buttons)	Replaces the modal action buttons
getValues()	Returns the current form values

Important Behavior

• onValueChange() is useful for dependent fields and live validation.
• setContent() preserves matching existing field values where possible.

UI Elements

Form Elements

Helper	Purpose
sigma.ui.input(...)	Single-line text input
sigma.ui.select(...)	Dropdown select
sigma.ui.checkbox(...)	Boolean toggle
sigma.ui.textarea(...)	Multi-line text input

Layout And Display Elements

Helper	Purpose
sigma.ui.separator()	Visual divider
sigma.ui.text(...)	Plain text block
sigma.ui.image(...)	Image element
sigma.ui.button(...)	Button element
sigma.ui.alert(...)	Inline status and warning block
sigma.ui.previewCard(...)	Media-style preview card
sigma.ui.previewCardSkeleton()	Loading placeholder for preview cards
sigma.ui.skeleton(...)	Generic loading placeholder
sigma.ui.renderToolbar(container, elements, onButtonClick?)	Renders a toolbar inside an extension embed page

Common Element Fields

Field	Description
id	Stable element identifier
label	User-facing label
placeholder	Placeholder text
value	Initial value
checked	Initial value for checkboxes
disabled	Disabled state

Select elements also support options, textareas support rows, and buttons support variant.

When To Use Which UI API

Need	Recommended API
Short feedback	showNotification()
Confirm or prompt	showDialog()
Long-running task	withProgress()
Collect form values	showModal()
Rich multi-field UI with live updates	createModal()

Continue

← Previous: API Reference

Next: Best Practices →