Skip to content

Controls

Controls are the views people interact with. Each one either runs an action (a button) or edits a value through a binding (a text field, toggle or picker).

enum Size { small, medium, large }
app Order(width: 300, height: 200) {
state name = ""
state giftWrap = true
state size = Size.medium
state placed = false
VStack(spacing: 12, alignment: .leading) {
TextField("Your name", text: name)
Toggle("Gift wrap", isOn: giftWrap)
Picker(selection: size) {
Text("Small").tag(.small)
Text("Medium").tag(.medium)
Text("Large").tag(.large)
}
Button("Place order") { placed = true }
.disabled(name == "")
}
.padding(16)
}

A text field containing "Sam" with a blue focus ring, a "Gift wrap" switch turned on, a segmented control with Medium selected, and a "Place order" button

Button shows a label and runs its block when clicked:

Button("Save") { save() }

The block is the button’s action: parameter, written as a trailing block. Writing it with its label, Button("Save", action: { save() }), means the same thing. When the action is just a call to a function with no parameters, you can also pass the function itself: Button("Save", action: save).

The label is a String. Buttons have a light gray, rounded look with a blue label; .color(…) changes the label color and .background(…) replaces the gray. For something that doesn’t look like a button at all, use .onTap (below).

A disabled button (.disabled(true)) is faded and ignores clicks.

TextField is a one-line text input. Its first argument is the placeholder, shown in gray while the field is empty, and text: is bound to the String it edits:

TextField("Search", text: query)

Every key press changes the bound string right away, so anything that uses it updates as the user types.

To run something when the user edits the text, give the field an onChange block (the block after the call). It runs after each edit that changes the text: a key typed, a paste, a deletion, an undo. It doesn’t run when your program sets the text itself:

TextField("Title", text: title) { unsaved = true }

onChange works the same on secure fields, fields of several lines and search fields.

A text field is as wide as it’s allowed to be: in a stack it stretches across the available width. Give it a .frame(width:) to make it a fixed size.

Click a field to start editing it; a blue ring shows which field is being edited. Clicking somewhere else, or pressing Escape, stops editing.

lines: makes a field for longer text, a few lines high. The text wraps at the field’s width, Enter starts a new line, and the field scrolls when the text is longer than it:

app Notes(width: 360, height: 260) {
state notes = ""
VStack(spacing: 8) {
TextField("Notes", text: notes, lines: 5)
Text("{notes.count} characters")
}
.padding(16)
}

In a field of several lines, Cmd+Enter (Ctrl+Enter on Windows) runs its .onSubmit, since Enter is taken. On Android the keyboard’s Enter key starts a new line too.

.onSubmit { … } runs a block when the user presses Enter in the field. Pressing Enter also stops editing the field.

app Chat(width: 360, height: 240) {
state draft = ""
state messages: [String] = []
TextField("Message", text: draft)
.autofocus()
.onSubmit { send() }
for m in messages {
Text(m)
}
fn send() {
if draft != "" {
messages.append(draft)
draft = ""
}
}
}

.autofocus() starts editing a text field as soon as it appears, so the user can type right away without clicking it first. It also works on a CodeEditor. It applies when the field appears: at startup, or when an if starts showing it. That makes it a good fit for a field that pops up when needed, like a “New file name” prompt.

SearchField is a text field for what to look for: a magnifying glass before the text, and a button after it that clears it. Escape clears it too:

app Contacts(width: 320, height: 300) {
state query = ""
let names = ["Ada Lovelace", "Alan Turing", "Grace Hopper"]
let shown = names.filter { n in query == "" || n.lowercase().contains(query.lowercase()) }
VStack(alignment: .leading) {
SearchField("Search contacts", text: query)
for name in shown {
Text(name)
}
}
.padding(12)
}

The placeholder is “Search” unless you give one. Like a TextField, it changes text: as the user types, and runs .onSubmit on Enter, for a search that’s too slow to run on every key. Its onChange block runs after each edit, and when the text is cleared.

Link is text that opens a web page when it’s clicked, in the accent color, with the pointing hand over it:

Link("Read the guide", url: "https://tessel-lang.syncster.dev")
Link("Email us", url: "mailto:hello@example.com")
Link("Show details", action: { details = true })

url: is opened as openURL opens it: a web page, a file or folder, or an email. action: runs a block instead (or as well).

Toggle is an on/off switch bound to a Bool:

Toggle("Dark background", isOn: darkBackground)
Toggle(isOn: todo.done)

The label is optional. Clicking the switch or its label flips the value.

An onChange block (the block after the call) runs after the user flips it, but not when your program sets the value:

Toggle("Show grid", isOn: showGrid) { saveSettings() }

Picker lets the user choose one of a few options. It’s drawn as a row of segments, with the selected one highlighted. selection: is bound to the chosen value, and each option is a view marked with .tag(value):

enum Filter { all, active, done }
app Todos(width: 360, height: 200) {
state filter = Filter.all
Picker(selection: filter) {
Text("All").tag(.all)
Text("Active").tag(.active)
Text("Done").tag(.done)
}
Text("Showing: {filter}")
}

Clicking an option sets selection to that option’s tag. The selection can be any type: an enum is the usual choice, but a String or an Int works too, as long as every .tag has the same type as the selection. Options are usually Text, but can be other views such as icons.

.tag only means something on the options of a Picker and the pages of a TabView; anywhere else it’s a compile error.

onChange: runs a block after the user chooses another option (by a click or the arrow keys, in every style below). The block after the call holds the options, so onChange: goes inside the parentheses:

Picker(selection: filter, onChange: { page = 0 }) {
Text("All").tag(.all)
Text("Active").tag(.active)
Text("Done").tag(.done)
}

It doesn’t run when the user clicks the option that’s already chosen, or when your program sets selection.

style: .radio shows the options one above the other, each with a round button, the chosen one filled:

enum Units { metric, imperial }
app Settings(width: 300, height: 160) {
state units = Units.metric
VStack(alignment: .leading) {
Text("Units").font(weight: .semibold)
Picker(selection: units, style: .radio) {
Text("Metric (m, kg)").tag(.metric)
Text("Imperial (ft, lb)").tag(.imperial)
}
}
}

Clicking an option or its button chooses it; with the keyboard on the picker, the arrows move the choice. In a form the options line up beside their label.

style: .menu shows only the chosen option, in a box with an arrow; a click opens the list of all of them, with a check by the chosen one. It suits long lists, and forms where room is short:

app Shipping(width: 320, height: 200) {
state country = "Philippines"
HStack {
Text("Country")
Picker(selection: country, style: .menu) {
for c in ["Japan", "Philippines", "Singapore", "Vietnam"] {
Text(c).tag(c)
}
}
}
}

With the keyboard on it, Enter or Space opens the list, the arrows choose, and Escape closes it.

These three edit a number or a color:

app Symbol(width: 340, height: 220) {
state opacity = 0.8
state width = 1.5
state classes = 5
state fill: Color = .rgb(52, 120, 246)
state edits = 0
VStack(spacing: 12, alignment: .leading) {
HStack {
Text("Opacity")
Slider(value: opacity, from: 0, to: 1, step: 0.05) { edits += 1 }
}
HStack {
Text("Line width")
Stepper(value: width, step: 0.5, from: 0, to: 10)
}
HStack {
Text("Classes")
Stepper(value: classes, from: 2, to: 12)
}
HStack {
Text("Fill")
ColorPicker(color: fill) { edits += 1 }
}
Text("{edits} edits").color(.secondary)
}
.padding(16)
}

A slider for the opacity, two steppers showing 1.5 and 5, and a blue color swatch

  • Slider sets a Float between from and to (0 and 1 if you leave them out), in steps of step if it isn’t 0.
  • Stepper makes an Int or a Float a step larger or smaller, between from and to, and shows it.
  • ColorPicker shows a Color. Clicking it opens a palette over the window, with a field for a hex code like #3478f6; picking a color closes it.

Each takes an optional onChange block (the block after the call), which runs after the user changes the value: the place to redraw a map or recompute something. Toggle, Picker, TextField and SearchField take one too, and so do the date pickers. It runs only for the user’s changes, never when your program sets the value.

The color picker's palette open: rows of colors from light to dark, and a hex field

A DatePicker shows a date and opens a calendar to pick another; a Calendar is that calendar by itself. Both change a time kept as a Float, as now() and date(…) give it:

state due = now()
HStack {
Text("Due")
DatePicker(date: due)
}
Text("{daysBetween(now(), due)} days left")

See DatePicker and Calendar.

Every control can be used without a mouse. Tab and Shift+Tab go from one to the next: text fields, buttons, toggles, pickers, tab views, sliders, steppers, color pickers and disclosure groups. A blue ring shows which one the keyboard is on. Then:

KeysWhat they do
Space, EnterPress a button, or turn a toggle on or off.
Left, Right, Up, DownChoose the option before or after in a picker, or the tab before or after in a tab view.
Left, Right, Up, DownMove a slider or a stepper.
Right, LeftOpen or close a disclosure group.
Enter, SpaceOpen a color picker’s palette (ready to type a hex code), or open or close a disclosure group.
EscapeTake the keyboard away from the control, or close the palette.

Clicking a slider, a stepper, a color picker or a disclosure group also puts the keyboard on it; clicking a button doesn’t. A view made pressable with .onTap isn’t a stop for Tab: use a Button for what should be reachable from the keyboard.

Shortcuts still work meanwhile. Keys a control doesn’t use go to .onKeyEvent or .onKey.

.onTap { … } runs a block when a view is clicked. It works on any view, including stacks, so you can build your own clickable rows and buttons:

HStack {
Icon(.folder)
Text("Documents")
Spacer()
}
.padding(6)
.hoverBackground(.lightGray, radius: 4)
.onTap { open(folder: "Documents") }

Add .hoverBackground so people can see it’s clickable. If a clickable view contains a button or another clickable view, a click goes to the innermost one.

A control takes its own clicks, so .onTap on a Toggle, a Picker, a Slider or a text field doesn’t run. To know when the user changes one, use its onChange block.

.onDrag { dx, dy in … } runs while the mouse is dragged from a view, with how far it moved each time. That’s what a bar between two panes needs, to resize them:

app Split(width: 400, height: 200) {
state left = 150.0
HStack(spacing: 0) {
Text("Left").frame(width: left, maxHeight: .infinity).background(.sidebar)
Spacer()
.frame(width: 6, maxHeight: .infinity)
.background(.separator)
.onDrag { dx, dy in left = (left + dx).clamped(min: 60, max: 300) }
Text("Right").frame(maxWidth: .infinity, maxHeight: .infinity)
}
}

The bar is a Spacer given a size and a color. Dragging it changes left, the UI is rebuilt with the new width, and the bar follows the mouse. The pointer turns into a resize arrow over it. See onDrag in the reference.

Text fields and code editors support the usual editing keys. On Windows, use Ctrl where this table says Cmd, and Alt where it says Option.

KeysWhat they do
Left, RightMove one character. With a selection, jump to its start or end.
Option+Left, Option+RightMove one word.
Cmd+Left, Cmd+Right, Home, EndMove to the start or end of the line.
Up, DownMove to the line above or below (in a code editor).
Shift + any of the aboveSelect text while moving.
Backspace, DeleteDelete the character before or after the cursor, or the selection.
Option+Backspace, Option+DeleteDelete a word.
Cmd+Backspace, Cmd+DeleteDelete to the start or end of the line.
Cmd+ASelect all.
Cmd+C, Cmd+X, Cmd+VCopy, cut and paste, with the system clipboard.
Cmd+Z, Cmd+Shift+ZUndo and redo.
EnterIn a text field: stop editing and run .onSubmit.
EscapeStop editing.

With the mouse, click to place the cursor, drag to select, Shift-click to extend the selection, double-click to select a word, and triple-click to select everything. A field scrolls sideways to keep the cursor in view when its text is longer than the field.

Undo remembers each change separately, except that a run of typed letters and digits is undone in one step. Each field keeps its own undo history. If the program itself changes a text field’s text, its history is cleared. In a code editor, a change the program makes is kept as a step of the history instead, so it can be undone like typing.

While nothing is being edited, Cmd+Z and Cmd+Shift+Z undo and redo in the field or editor whose text changed last, which is then edited, with the cursor where the change was. undoTextEdit() and redoTextEdit() do the same, for Undo and Redo buttons of your own.

Pasting into a text field turns line breaks into spaces, since it holds a single line. The code editor adds keys of its own: for comments, moving and copying lines, indentation, several cursors and folding.

Tab starts editing the next text field (or code editor), and Shift+Tab the one before, in the order they’re written. After the last one comes the first again. A field you arrive at with Tab has its text selected, so typing replaces it. Hidden and disabled fields are skipped. In a code editor, Tab indents instead.

Text typed with an input method works in text fields and code editors: Chinese, Japanese and Korean input, and accents typed with dead keys (such as Option+E, then E, for é on a Mac). While you compose, the text so far is shown underlined at the cursor. It becomes part of the field’s text, and of your state, when you confirm it.