02 — Controls Reference
Every Add-UICanvas* control with its real parameters, an example, and notes. All controls also accept the universal parameters (-Name -X -Y -Width -Height -ZIndex -Tooltip -Visible -Enabled -Refresh -Properties) unless noted. Parameters shown are the control-specific ones.
Conventions:
-Label/-Valueaccept a string or a scriptblock (with-Refresh N, the scriptblock re-runs every N seconds for live values).-Bind 'key'ties the control to a reactive state key (see 03).-OnChange { }fires when the user changes an input's value.
Text & display
Add-UICanvasLabel
Add-UICanvasLabel [-Label] <string|scriptblock> [-Name <s>] [-Bind <s>]
[-FontSize <d>] [-FontWeight <s>] [-Foreground <hex>]Static or live text. -FontWeight = Normal|SemiBold|Bold. With -Bind, the label can be a key (-Bind 'count') or a template (-Bind 'Hello {name}') that re-renders on change.
Add-UICanvasLabel 'Status: ready' -FontSize 14 -Foreground '#94A3B8'
Add-UICanvasLabel -Name clock -Refresh 1 -Label { Get-Date -Format 'HH:mm:ss' }Elapsed clock (-Clock / -ClockStop). -Clock <controlName> names a control that holds a start time as UTC ticks; the label then shows elapsed mm:ss, updated twice a second by the engine itself — no runspace call, so it keeps ticking while a long action or step holds the gate (a -Refresh label would freeze). -ClockStop <controlName> names a control holding the end ticks; once it is set, the clock freezes at the final time. The workflow runner publishes <wf>_start / <wf>_end for exactly this; for your own timer, keep the ticks in hidden controls:
Add-UICanvasTextBox -Name jobStart -Visible $false
Add-UICanvasTextBox -Name jobEnd -Visible $false
Add-UICanvasLabel -Name elapsed '00:00' -Clock jobStart -ClockStop jobEnd -FontSize 20
Add-UICanvasButton 'Start' -Action { Set-UICanvasValue jobStart ([DateTime]::UtcNow.Ticks) }
Add-UICanvasButton 'Stop' -Action { Set-UICanvasValue jobEnd ([DateTime]::UtcNow.Ticks) }Add-UICanvasIcon
Add-UICanvasIcon [-Icon] <string> [-Name <s>] [-FontSize <d>] [-Foreground <hex>]An icon by glyph name, MDL2 char, or PNG path.
Add-UICanvasBadge
Add-UICanvasBadge [-Label] <string> [-Value <o>] [-Severity Neutral|Info|Success|Warning|Error] [-Icon <s>]A small status pill. -Icon may be a PNG path or glyph.
Add-UICanvasBanner
Add-UICanvasBanner [-Label] <string> [-Value <o>] [-Severity Informational|Success|Warning|Error]
[-Icon <s>] [-Image <s>]A prominent header strip. -Icon = leading status icon (PNG/glyph), -Image = a hero illustration on the right.
Add-UICanvasHyperlink
Add-UICanvasHyperlink [-Label] <string> [-NavigateUri <url>]Opens the URL in the default browser. Security: only http/https/mailto/file schemes open; anything else is blocked and logged.
Add-UICanvasMarkdown
Add-UICanvasMarkdown [-Text <string>] [-Path <file>]Renders Markdown to a native WPF FlowDocument (no browser needed). Supports headings (#/##/###), **bold**, *italic*, `code`, fenced ``` code blocks, > blockquotes, --- rules, unordered (-/*) and ordered (1.) lists, links [text](url) (scheme-gated), and images  (local paths render inline; alt text is the fallback).
Add-UICanvasSeparator
Add-UICanvasSeparator [-Name <s>] [-X <d>] [-Y <d>] [-Width <d>] [-ZIndex <int>]A horizontal rule.
Buttons
Add-UICanvasButton
Add-UICanvasButton [-Label] <string> [-Name <s>] [-Action { }] [-NavigateTo <page>]
[-Style Standard|Secondary|Accent|Primary|Subtle|Gradient] [-Icon <s>]-Action { }runs (on the bridge runspace) when clicked.-NavigateTogoes to a page with no action code: a page title, a numeric index, or a relative keywordNext,Prev/Previous/Back,First,Last. It is ignored when-Actionis also given — to navigate after doing work, callShow-UICanvasPageat the end of the action instead.-Style:Accent/Primary= filled brand;Secondary= outlined;Subtle= quiet/ghost;Gradient= brand gradient fill;Standard= default. CallSet-UIThemefirst — on the unthemed dark paletteAccentis unreadable.-Icon= a friendly name (play,back,next,refresh,shield,server, …), a hex code point (E768,0xE768), a glyph character, or a PNG path.-Properties @{ ContentAlign = 'Left' }left-aligns content.
Add-UICanvasButton 'Deploy' -Name go -Style Accent -Icon 'play' -Action {
Set-UICanvasProperty go 'Enabled' $false
Show-UICanvasToast -Message 'Deploying…' -Severity info
}Add-UICanvasDropDownButton
Add-UICanvasDropDownButton [-Label] <string> [-Choices <array>] [-Value <o>] [-OnChange { }]A button that opens a built-in menu of -Choices; the picked item becomes its value. (For an anchored popup menu driven by an action, see Show-UICanvasFlyout in 03.)
App chrome & structure
The pieces that turn a page into an application: a header, a footer, a menu bar, tabs, resizable panes and content that scales to fit. For a fully custom look (slim top bar, animated icon rail) see 10; these are the built-in versions.
Add-UICanvasToolbar
Add-UICanvasToolbar [-Name <s>] [-Brand <s>] [-BrandIcon <s>] [-Status <s>]
[-Links <string[]>] [-Active <pageTitle>] [-Actions <hashtable[]>]An application header: brand and a status pill on the left, navigation links in the centre, action icons on the right.
-Links— page titles; each link navigates to the page of the same title.-Activehighlights the current one.-Actions—@{ Icon = '<glyph>'; Tooltip = '...'; Action = { ... } }, orPage = '<title>'instead ofAction, orImage = '<png>'(e.g. an avatar) instead ofIcon. AddName = '...'to address it later.- Its height is fixed at about 54 px; for a slimmer bar build one in an island (file 10).
Add-UICanvasToolbar -Brand 'Contoso Ops' -BrandIcon 'server' -Status 'Connected' `
-Links 'Overview', 'Reports', 'Settings' -Active 'Overview' -Actions @(
@{ Icon = 'refresh'; Tooltip = 'Refresh'; Action = { Show-UICanvasToast 'Refreshed' -Severity info } }
@{ Icon = 'settings'; Tooltip = 'Settings'; Page = 'Settings' }
)Add-UICanvasFooter
Add-UICanvasFooter [-Name <s>] [-LeftText <s>] [-Links <object[]>]A status/footer bar: muted text on the left, links on the right. A link is a plain string (display only) or @{ Text = '...'; Action = { ... } } / @{ Text = '...'; Page = '<title>' }.
Add-UICanvasFooter -LeftText 'v1.2.0 | Signed in as CONTOSO\admin' -Links @(
@{ Text = 'Help'; Action = { Show-UICanvasDialog -Title 'Help' -Message 'Call 1234.' -OkLabel 'Close' } }
@{ Text = 'Settings'; Page = 'Settings' }
)On a Dock page, give it -Properties @{ Dock = 'Bottom' } and declare it before the fill child.
Add-UICanvasMenu
Add-UICanvasMenu -Items <hashtable[]> [-Name <s>] [-Background <hex>]A classic menu bar. Each item is @{ Text; Items } (a submenu) or a leaf @{ Text; Action } / @{ Text; Page }. Leaves also take Gesture (the shortcut text shown — register the key itself with Add-UICanvasShortcut), Icon, Disabled = $true and Checked = $true|$false. Text = '-' is a separator.
Add-UICanvasMenu -Items @(
@{ Text = 'File'; Items = @(
@{ Text = 'Export...'; Gesture = 'Ctrl+E'; Action = { Show-UICanvasToast 'Exported' -Severity success } }
@{ Text = '-' }
@{ Text = 'Exit'; Action = { Submit-UICanvas } } ) }
@{ Text = 'View'; Items = @(
@{ Text = 'Reports'; Page = 'Reports' }
@{ Text = 'Show hidden'; Checked = $false; Action = { } } ) }
)
Add-UICanvasShortcut 'Ctrl+E' -Action { Show-UICanvasToast 'Exported' -Severity success }Add-UICanvasTabs / Add-UICanvasTab
Add-UICanvasTabs [-Name <s>] [-SelectedIndex <int>] [-OnChange { }] -Children { Add-UICanvasTab ... }
Add-UICanvasTab [-Label] <header> [-Layout VStack|HStack|Grid|Wrap|Canvas] [-Columns <int>]
[-ColumnWidths <s>] [-Spacing <d>] [-Padding <o>] [-Disabled] -Children { ... }A tab container; its children must be Add-UICanvasTab blocks, each one tab page with its own layout. Read or switch the active tab with Get-UICanvasValue / Set-UICanvasValue (an index or the header text); -OnChange fires when the user switches tab.
Add-UICanvasTabs -Name details -Children {
Add-UICanvasTab 'Summary' -Spacing 8 -Children {
Add-UICanvasLabel 'Everything at a glance.'
}
Add-UICanvasTab 'Hardware' -Layout Grid -Columns 2 -Spacing 8 -Children {
Add-UICanvasMetricCard 'CPU' -Value '8 cores'
Add-UICanvasMetricCard 'RAM' -Value '32 GB'
}
Add-UICanvasTab 'Audit' -Disabled -Children { Add-UICanvasLabel 'Coming soon' }
}Tabs keep every page's controls alive, so a value typed on one tab is still readable from another.
The strip follows the theme: headers in the secondary text colour, the selected one in full text weight over an accent underline, a hairline under the strip, and each page on the surface the tabs sit on (so tabs inside a card take the card's background).
Engine 1.4.1 and earlier drew tabs in the stock light Windows style, unreadable in a dark app. If you must support that engine, use a row of buttons that show one panel and hide the others with
Set-UICanvasProperty <panel> Visible $true|$falseinstead.
Add-UICanvasGridSplitter
Add-UICanvasGridSplitter [-Name <s>] [-Orientation Vertical|Horizontal] [-Thickness <d>] [-Background <hex>]A drag handle that resizes the panes either side of it. Put it in its own column of a Grid panel, between the two panes, and give that column a fixed width. Vertical (default) resizes columns; Horizontal resizes rows.
Add-UICanvasPanel -Layout Grid -ColumnWidths '280,6,*' -Children {
Add-UICanvasListBox -Name servers -Choices 'web-01', 'web-02', 'db-01' -Properties @{ Column = 0 }
Add-UICanvasGridSplitter -Properties @{ Column = 1 }
Add-UICanvasLabel 'Details for the selected server' -Properties @{ Column = 2; Margin = '12,0,0,0' }
}Add-UICanvasViewbox
Add-UICanvasViewbox [-Stretch Uniform|Fill|UniformToFill|None] [-StretchDirection Both|UpOnly|DownOnly]
[-Layout VStack|HStack|Grid|Wrap|Canvas] [-Spacing <d>] -Children { ... }Scales its content to fit the space it is given — vector scaling, so text stays crisp. Use it for a kiosk number, a big status readout, or a fixed design that must fill any window. DownOnly shrinks to fit but never enlarges. Give it an explicit -Height (or a Dock fill slot) so it has a size to scale to.
Add-UICanvasViewbox -Height 160 -Children {
Add-UICanvasLabel -Name bigCount '248' -FontSize 72 -FontWeight Bold
}Text input
Add-UICanvasTextBox
Add-UICanvasTextBox [-Name <s>] [-Bind <s>] [-Value <o>] [-Placeholder <s>] [-OnChange { }]Single-line text. Value = the text.
Add-UICanvasMultiLine
Add-UICanvasMultiLine [-Name <s>] [-Bind <s>] [-Value <o>] [-Placeholder <s>] [-OnChange { }]Multi-line text area.
Add-UICanvasRichEdit
Add-UICanvasRichEdit [-Name <s>] [-Bind <s>] [-Value <o>] [-Placeholder <s>] [-OnChange { }]A richer multi-line editor.
Add-UICanvasPassword
Add-UICanvasPassword [-Name <s>] [-Placeholder <s>]Masked input with a reveal (eye) toggle. The value is DPAPI-protected (CurrentUser) and returned as a SecureString — never logged in plaintext. Read it via the result set, not Get-UICanvasValue.
Add-UICanvasAutoSuggest
Add-UICanvasAutoSuggest [-Name <s>] [-Bind <s>] [-Choices <array>] [-Value <o>] [-OnChange { }]Editable, type-to-filter combo with a dropdown chevron. Value = the current text.
Add-UICanvasNumber / Add-UICanvasNumberBox
Add-UICanvasNumber [-Name <s>] [-Bind <s>] [-Value <o>] [-Minimum <d>] [-Maximum <d>] [-OnChange { }]
Add-UICanvasNumberBox [-Name <s>] [-Bind <s>] [-Value <o>] [-Minimum <d>] [-Maximum <d>] [-Step <d>] [-OnChange { }]Numeric inputs; NumberBox adds spinner -Step.
Selection & boolean
Add-UICanvasDropdown
Add-UICanvasDropdown [-Name <s>] [-Bind <s>] [-Choices <array>] [-Value <o>] [-ItemIcons <string[]>] [-OnChange { }]
[-DependsOn <string[]>] [-OptionsScript { ... }]Combo box. -ItemIcons = a parallel array of PNG paths/glyphs aligned to -Choices.
Cascading options: -DependsOn + -OptionsScript make the items recompute automatically whenever any of the named fields changes — no -OnChange wiring. The script's output becomes the new item list. On a cascading dropdown, omit -Choices and -ItemIcons (items come from the script).
Add-UICanvasDropdown -Name region -Choices 'US','EU','APAC'
Add-UICanvasDropdown -Name dc -DependsOn region -OptionsScript {
switch (Get-UICanvasValue -Name region) {
'US' { 'us-east-1','us-west-2' } 'EU' { 'eu-central-1','eu-west-1' } 'APAC' { 'ap-southeast-1' }
}
}Add-UICanvasListBox
Add-UICanvasListBox [-Name <s>] [-Bind <s>] [-Choices <array>] [-Value <o>] [-ItemIcons <string[]>] [-OnChange { }]
[-DependsOn <string[]>] [-OptionsScript { ... }]Single-select list. Supports -ItemIcons and -Height. -DependsOn/-OptionsScript cascade exactly as on Add-UICanvasDropdown above.
Add-UICanvasRadioGroup
Add-UICanvasRadioGroup [-Name <s>] [-Bind <s>] [-Choices <array>] [-Value <o>] [-Orientation Vertical|Horizontal]Add-UICanvasCheckbox
Add-UICanvasCheckbox [-Label] <string> [-Name <s>] [-Bind <s>] [-Value <bool>] [-Icon <s>] [-OnChange { }]Value = $true/$false.
Add-UICanvasToggle
Add-UICanvasToggle [-Name <s>] [-Bind <s>] [-Value <bool>] [-OnChange { }]A switch.
Add-UICanvasSlider
Add-UICanvasSlider [-Name <s>] [-Bind <s>] [-Value <o>] [-Minimum <d>] [-Maximum <d>] [-Step <d>] [-OnChange { }]Add-UICanvasRating
Add-UICanvasRating [-Name <s>] [-Value <int>] [-Max <int>] [-FontSize <d>] [-OnChange { }]A 0..Max star rating.
Date / time / color
Add-UICanvasDatePicker
Add-UICanvasDatePicker [-Name <s>] [-Bind <s>] [-Value <o>] [-OnChange { }]Add-UICanvasTimePicker
Add-UICanvasTimePicker [-Name <s>] [-Value <s>] [-StepMinutes <int>] [-OnChange { }]Add-UICanvasColorPicker
Add-UICanvasColorPicker [-Name <s>] [-Value <s>] [-Choices <array>] [-OnChange { }]Progress & status
Add-UICanvasProgressBar
Add-UICanvasProgressBar [-Name <s>] [-Bind <s>] [-Value <o>] [-Minimum <d>] [-Maximum <d>]
[-Fill <hex>] [-Glow $true|<hex>] [-GlowPulse] [-GlowRadius <d>]-Fillsets the bar color.-Glow $true= neon glow in the fill color;-Glow '#34D399'= a specific glow color.-GlowPulseanimates the glow;-GlowRadiussets its size.
Add-UICanvasProgressBar -Name dep -Value 0 -Fill '#34D399' -Glow '#34D399' -GlowPulse -GlowRadius 16
# later, in an action: Set-UICanvasValue dep 65Add-UICanvasProgressRing
Add-UICanvasProgressRing [-Name <s>] [-Foreground <hex>] [-Thickness <d>]An indeterminate spinner. (Set-UICanvasProperty <name> Spin $true/$false toggles spin on any icon/image too.)
Add-UICanvasConsole
Add-UICanvasConsole [-Name <s>] [-Bind <s>] [-Value <o>]A themed monospace log/output area. Append live via Set-UICanvasValue/-Refresh or bind to state. To add one line and scroll to it: Set-UICanvasProperty <name> AppendLine '<text>' — the cheapest way to stream a log from an async block, since it doesn't resend the whole text. The console is one colour, so mark levels in the text ([ERROR] …).
Images & raw XAML
Add-UICanvasImage
Add-UICanvasImage [-Name <s>] -Source|-Value <path> [-Properties @{ Stretch = 'Uniform' }]Renders a PNG/JPG/etc. -Source is an alias of -Value.
Add-UICanvasXaml (escape hatch)
Add-UICanvasXaml [-Name <s>] [-Markup <xaml-string>] [-Path <xaml-file>]Splices raw WPF XAML for anything the cmdlets don't cover. Named elements inside (including the root) are registered and addressable via Set-UICanvasProperty/Get-UICanvasValue. Theme brushes resolve via {DynamicResource ...}. Use sparingly.
Data controls (Tier-1)
Add-UICanvasDataGrid
Add-UICanvasDataGrid [-Name <s>] [-Columns <string[]>] [-Items <object[]>] [-BindItems <stateKey>] [-Height <d>]A modern data grid. Pass rows as -Items (array of [pscustomobject]/hashtables) — they serialize correctly. Columns auto-generate, or pass -Columns for explicit ones. -BindItems 'key' makes the rows follow a state list reactively (see 03). Shows a centered "No data" placeholder when empty.
Add-UICanvasDataGrid -Name grid -Items @(
[pscustomobject]@{ Host='web-01'; Role='Web'; Status='Online' }
[pscustomobject]@{ Host='db-01'; Role='Database'; Status='Online' }
)Add-UICanvasTreeView
Add-UICanvasTreeView [-Name <s>] [-Nodes <object[]>] [-Height <d>]Nested tree. Each node = @{ Text='Sites'; Expanded=$true; Children=@(@{ Text='HQ' }, ...) }.
Dashboard cards
Add-UICanvasMetricCard
Add-UICanvasMetricCard [-Caption] <string> [-Value <o>] [-Trend Up|Down|Stable] [-Delta <s>]A KPI tile: big value + caption + an optional trend arrow and delta.
Add-UICanvasStatusCard
Add-UICanvasStatusCard [-Title] <string> [-Items <string[]>] [-Background <hex>]A list of "Label|State" items, each with a colored status dot (e.g. 'API|Online', 'Disk|Warning').
Add-UICanvasTableCard
Add-UICanvasTableCard [-Title] <string> [-Columns <string[]>] [-Rows <object[]>] [-Background <hex>]A simple titled table card (lighter than DataGrid).
Add-UICanvasChartCard
The full chart system — bar/line/area/donut/sparkline, multi-series, spline, reactive. See 04-charts.md.
Pickers (composite)
Add-UICanvasFolderPicker
Add-UICanvasFolderPicker [-Name <s>] [-Value <s>] [-Placeholder <s>] [-Description <s>] [-ButtonLabel <s>]A path textbox + Browse button (native folder dialog).
Add-UICanvasFilePicker
Add-UICanvasFilePicker [-Name <s>] [-Value <s>] [-Placeholder <s>] [-Title <s>]
[-Filter 'Label (*.ext)|*.ext'] [-ButtonLabel <s>]A path textbox + Browse button (native open-file dialog).
Iteration & shapes
Add-UICanvasRepeater
Add-UICanvasRepeater -Items <object[]> -Template { param($item) ... }Authoring-time loop: runs -Template once per item, emitting controls for each. Use inside a container's -Children to build N cards/rows from data.
Add-UICanvasPanel -Layout Grid -Columns 3 -Spacing 12 -Children {
Add-UICanvasRepeater -Items $stats -Template { param($s)
Add-UICanvasCard -Layout VStack -Children {
Add-UICanvasLabel $s.Value -FontSize 22 -FontWeight Bold
Add-UICanvasLabel $s.Title -Foreground '#94A3B8'
}
}
}(Repeater is static — it builds once. For a live, data-driven list use a DataGrid with -BindItems.)
Shapes
Add-UICanvasRectangle [-Fill <hex>] [-Stroke <hex>] [-StrokeThickness <d>] [-CornerRadius <d>]
Add-UICanvasEllipse [-Fill <hex>] [-Stroke <hex>] [-StrokeThickness <d>]
Add-UICanvasLine [-Stroke <hex>] [-StrokeThickness <d>]Primitive shapes (mostly for Canvas-layout decoration).
Generic escape: Add-UICanvasControl
Add-UICanvasControl -Type <string> [-Name <s>] [-Label <o>] [-Value <o>] [-Choices <o>]
[-Action { }] [-OnChange { }] [-Properties @{ ... }]The low-level cmdlet every typed cmdlet forwards to. Rarely needed directly; prefer the typed cmdlets.
