Skip to content

How to style and lay out the page

Reference: documents (stylesheets, computed style, environment). What HTML and CSS the host supports, in detail: HTML and CSS support in Core. Examples: 04-todo-list.ps1 (light and dark palette), 09-settings-dialog.ps1 (theme switch, replaceable stylesheet), 15-data-table.ps1 (app shell with a sticky table header), bulk-rename/ (separate index.html and style.css).

Screenshot: ps-sdk-04-todo-list

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Screenshot: ps-sdk-09-settings-dialog

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Screenshot: ps-sdk-15-data-table

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Screenshot: ps-sdk-bulk-rename

Real capture on KDE Plasma 6.6 Wayland with the released packages.

The page is rendered by the NativeHTMLKit Core host with its own native engine, not by a browser. It understands modern HTML and CSS (flexbox, grid, custom properties, media queries, transitions) but runs no JavaScript and loads nothing from the network. Everything interactive is a PowerShell callback.

Where the CSS lives

Approach Use it for
<style> inside the HTML here-string Small single-file apps, like most examples.
index.html + style.css loaded with Open-NativeHTMLKitFile Larger apps. Relative URLs (style.css, images, fonts) resolve against the HTML file's folder.
Add-NativeHTMLKitStylesheet / Set-NativeHTMLKitStylesheet CSS that changes at run time: user font size, themes, generated rules.
$doc = Open-NativeHTMLKitFile -Window $window -Path (Join-Path $PSScriptRoot 'index.html')

# A placeholder sheet that the app replaces later.
$userSheet = (Add-NativeHTMLKitStylesheet -Document $doc -Css '').sheet
$null = Set-NativeHTMLKitStylesheet -Document $doc -Sheet $userSheet -Css 'body { font-size: 18px; }'

Use single-quoted here-strings (@' ... '@) for HTML and CSS so PowerShell leaves $ and backticks alone. If you need to insert values, use .Replace('%TOKEN%', $value) or the -f operator on a here-string whose literal braces are doubled.

An application layout

Desktop windows are usually an app shell: fixed toolbars, one scrolling region, maybe a side panel. Flexbox on a full-height body does that:

body { margin:0; height:100vh; display:flex; font:13px sans-serif; }
.main { flex:1; display:flex; flex-direction:column; min-width:0; padding:14px 16px; }
.tools { display:flex; gap:10px; align-items:center; margin-bottom:10px; }
.scroll { flex:1; overflow:auto; }                 /* only this region scrolls */
th { position:sticky; top:0; background:#e9ecf2; } /* the header row stays visible */
aside { width:240px; border-left:1px solid #dde1e8; }

That is the layout of 15-data-table.ps1. Grid works too (grid-template-columns, named areas, gap), as do tables, position: sticky/fixed, multi-column text and container queries. Give windows a minimum size that fits the layout: New-NativeHTMLKitWindow ... -MinWidth 420 -MinHeight 360.

State as classes

Keep presentation in CSS and let PowerShell switch classes:

Set-NativeHTMLKitClass -Document $doc -Element body -Name running            # add
Set-NativeHTMLKitClass -Document $doc -Element body -Name running -Remove    # remove
.running #clock { color: #8ef0b6; }
tr.low td { color: #b03a2e; }
li.done .text { text-decoration: line-through; }

Class and attribute changes for many elements belong in one Invoke-NativeHTMLKitBatch (updating the page). Attribute selectors and ARIA attributes work well together: th[aria-sort=ascending]::after { content: " \25B2"; }.

Light and dark

prefers-color-scheme follows the desktop setting. Define colours once as custom properties and switch the palette in a media query:

:root { --bg:#f6f7fb; --card:#fff; --text:#1d2433; --accent:#3a6ff7; }
@media (prefers-color-scheme: dark) {
  :root { --bg:#141923; --card:#1d2433; --text:#e8ecf5; --accent:#7aa2ff; }
}
body { background:var(--bg); color:var(--text); }

To offer a Light / Dark / System choice in the app, override the media query per document:

$null = Set-NativeHTMLKitEnvironment -Document $doc -ColorScheme dark      # light, dark or system
$null = Set-NativeHTMLKitEnvironment -Document $doc -ReducedMotion reduce  # reduce, no-preference or system

system removes the override. prefers-reduced-motion works the same way; honour it in your transitions and animations.

Images, fonts and icons

Resources load only from the document's asset root (the HTML file's folder, or -AssetRoot), from data: URLs (up to 4 MiB) and from in-memory bundles. http: and https: URLs are refused.

# An inline page that references files next to the script:
$doc = Open-NativeHTMLKitHtml -Window $window -Html $page -AssetRoot $PSScriptRoot

# Generated or embedded bytes, without temporary files:
$png = [IO.File]::ReadAllBytes((Join-Path $PSScriptRoot 'logo.png'))
$null = Register-NativeHTMLKitResources -Document $doc -Name brand -Entries @{ 'logo.png' = @{ Bytes = $png; Mime = 'image/png' } }
# <img src="nativehtmlkit-res://brand/logo.png" alt="Logo">

PNG, JPEG, GIF (first frame), WebP, BMP and static SVG are supported. @font-face loads TTF, OTF and WOFF/WOFF2 from the same places; the generic families (sans-serif, monospace, system-ui) use the desktop's fonts. For pixels you compute (charts, previews) use a live bitmap.

What is not there

Markup with <script>, <iframe>, on... attributes or contenteditable is refused: loading it, or inserting it with Set-NativeHTMLKitDocumentHtml, throws NativeHTMLKit.RpcException -32602 (for example INVALID_ARGUMENT: Unsupported active element: script) and the document stays as it was. Date, time and colour inputs are refused too (no native picker); use text inputs with a pattern. <canvas>, <video> and <audio> show empty boxes. Links never navigate; the host sends a link_activated event and your script decides (for example Open-NativeHTMLKitExternal). The Core guide lists the CSS features and selectors that are off in Core 1.0.3.

When something looks wrong

# What did the engine compute?
(Get-NativeHTMLKitComputedStyle -Document $doc -Element title -Properties @('color', 'font-size')).properties.'font-size'.value

# Why does a declaration have no effect?
Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation explain -Parameters @{ element = 'title'; property = 'top' }
# -> status 'not_applicable', reason 'position is static: offsets only apply to positioned elements'

# What did the engine drop or refuse in this document?
(Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_diagnostics).diagnostics

# CSS you add at run time is checked on the spot:
(Add-NativeHTMLKitStylesheet -Document $doc -Css 'h1 { colr: red }').diagnostics
# -> category 'unknown-property', excerpt 'colr', line 1, column 6

These calls work in headless mode, so a -SelfTest can assert on computed styles. Fonts, colours and the final look still need one check on each real desktop.


Source: nativehtmlkit-powershell/docs/guides/styling-and-layout.md ยท edit the page there.