Skip to content

UI Primitives

The View is the window: the root of every view, which is there without being written. It has the box properties and the container properties, so a view can be given a background, a padding or a direction by writing it as the outermost element:

fn view(state: State): Node =>
#view(fill: white, padding: 16px, direction: "column") {
#text("Hello")
}

A #view has to be the outermost element, and there is only one. Without one, the view still has its View, with nothing to paint.

Fragments allow for grouping of UI Primitives but cannot effect the layout and do not have any properties>.

Boxes are the absolute most basic UI primitive

Properties

NameTypeDescription
widthPx | Pct | Fr | auto

Width of the box (>= 0).

heightPx | Pct | Fr | auto

Height of the box (>= 0).

min-widthPx | Pct

Minimum width constraint (>= 0).

min-heightPx | Pct

Minimum height constraint (>= 0).

max-widthPx | Pct

Inner spacing between the box edge and its content (>= 0).

max-heightPx | Pct

Inner spacing between the box edge and its content (>= 0).

max-heightPx | Pct

Maximum height constraint (>= 0).

paddingPx | Pct

Inner spacing between the box edge and its content (>= 0).

marginPx | Pct

Outer spacing around the box.

growNumber

Flex grow factor when extra space is available (>= 0).

shrinkNumber

Flex shrink factor when space is constrained (>= 0).

basisPx | Pct | Fr | auto

Initial main-axis size before growing or shrinking (>= 0).

align-selfAlign

Overrides the parent’s align: "start", "center", "end", "stretch".

fillColor

Background fill color of the box.

border-colorColor

Color of the box border. A color with no border-width is a border 1px thick.

border-widthPx

Thickness of the border, in px (>= 0). It is inside the box’s edge, and takes none of its room from its children’s: that is padding’s. A width with no border-color is black.

radiusPx

Corner rounding radius, in px (>= 0). It is at most half of the box’s smaller side. A rounded box is made of rows of rectangles, so its edge is not smoothed.

tooltipString

A tooltip: text that is shown next to the pointer once it has been over the box for a moment (half a second, unless the host says otherwise), over everything else. What is inside the box has the box’s tooltip unless it has its own, and where the box is cut off, by a #scroll for instance, it has none. A click or the wheel hides it until the pointer is over something else. The text can be made when the view runs, like "{count} items", and wraps if it is long.

opacityNumber

Opacity from 0 (transparent) to 1 (opaque). It lightens the box’s own fill and border, or a text’s color. It is not passed on to what is inside the box.

on-clickMessage

Message dispatched when the box is clicked.

Containers are #boxes that contain children

Properties

NameTypeDescription
Inherits from:#box
gapPx | Pct

Spacing between adjacent children (>= 0).

directionDirection

Main layout axis: "row", "column", "row-reverse", or "column-reverse".

alignAlign

Cross-axis alignment of children: "start", "center", "end", or "stretch".

justifyJustify

Main-axis distribution: "start", "center", "end", "space-between", "space-around", "space-evenly".

wrapBool

Whether children wrap onto multiple lines when they overflow the main axis.


A general-purpose layout container for grouping and arranging child elements.

Properties

NameTypeDescription
Inherits from:#container

Example

#block(direction: "column",
gap: 12px,
padding: 16px,
fill: #1e1e1e,
radius: 8px) {
#text(value: "Settings", size: 20px, color: white)
#text(value: "Manage your preferences.", size: 14px, color: #a0a0a0)
}

A #box for displaying text

Properties

NameTypeDescription
Inherits from:#box
valueString

What to show.

sizePx

The font size, in px (>= 0).

font-familyString

The font: a name, or a comma-separated list in order of preference.

colorColor

The color of the text. Opaque black if it isn’t given.

text-alignString

Horizontal text alignment: "left", "center", or "right". Each line of the text is placed in the room the text has, which is its own width unless something makes it wider, like a column that stretches it. It is a word, not a value that changes.

Positional Arguments
valueString

The text to render

Example

#text(size: 24px,
font-family: "Inter, sans-serif",
color: white,
"Hello World")

A single-line #box for user input.

Properties

NameTypeDescription
Inherits from:#box
sizePx

The font size, in px (>= 0).

font-familyString

The font: a name, or a comma-separated list in order of preference.

colorColor

The color of the input text.

text-alignString

Horizontal text alignment: "left", "center", or "right".

on-inputMessage

Message dispatched when the user edits the text.

Positional Properties
valueString

The current text value inside the input.

Example

#input(size: 16px,
padding: 8px,
border-color: #444444,
border-width: 1px,
on-input: UpdateQuery,
"Search....")

A #box for rendering an image

Properties

NameTypeDescription
Inherits from:#box
fitString

How the image scales inside its box: "contain", "cover", "fill", or "none".

Positional Properties
sourceString

The source uri for the image

Example

#image(width: 120px,
height: 120px,
fit: "contain"
source)

A #box that response to clicks

Properties

NameTypeDescription
Inherits from:#container

Example

#button(padding: 10px,
fill: blue,
radius: 6px,
on-click: Submit) {
#text(value: "Save", size: 14px, color: white)
}

A #container for displaying more children than fit. What is in it is laid out at its own size, and the box shows the part of it that has been scrolled to, clipping the rest. Its padding, gap, direction, align and justify are for what is inside it, and its width, height, fill, border-* and radius for the box.

A #list is a #scroll that goes down: its direction is "column" unless it says otherwise. Every row of a list is laid out and drawn, whether it is in view or not.

The host scrolls it (Session::Scroll, or kura_rt_event_scroll): the wheel moves the topmost container under the pointer that has room to go that way, and when it is as far as it goes the one it is in gets the wheel. How far a container is scrolled is kept from one frame to the next, and is kept in range if its content shrinks.

Properties

NameTypeDescription
Inherits from:#container
on-scrollMessage

Message dispatched when the scroll offset changes. It doesn’t say where the offset is yet.

Example

#scroll(height: 300px,
direction: "column",
gap: 8px,
on-scroll: Scrolled) {
#text(value: "Item 1", size: 14px)
#text(value: "Item 2", size: 14px)
}

A #box visual indicator showing completion progress.

Properties

NameTypeDescription
Inherits from:#box
Positional Properties
valueNumber

Completion ratio between 0 (empty) and 1 (complete).

Example

#progress(width: 200px,
height: 8px,
fill: #333333,
radius: 4px
0.75)