Controls

The interactive control primitives. Button performs an action on tap. Toggle flips a boolean. Picker selects one value from a set, and Menu shows a dropdown list of actions. Label is a title-plus-icon combination commonly used as a button or row label, and ProgressView displays determinate or indeterminate progress.

Button

A tappable control that performs an action when pressed.

Button(props: { action: () => void; label: Component }): Component;
Button(label: string, action: () => void): Component;
Button(label: Component, action: () => void): Component;

string | Component

required

The button’s visible content. Can be a plain string or any component for custom layouts.

() => void

required

Callback invoked when the button is tapped.

When using the object form:

() => void

required

Callback invoked when the button is tapped.

Component

required

A component to use as the button label.

Simple text button

Button("Save", () => {
    console.log("Saved!")
})

Button with component label

Button(
    HStack({ spacing: 8 }, [
        Image({ systemName: "checkmark" }),
        Text("Save")
    ]),
    () => handleSave()
)

Object form

Button({
    action: () => handleSave(),
    label: HStack([
        Image({ systemName: "checkmark" }),
        Text("Save")
    ])
})

Styled button

Button("Primary Action", () => {})
    .foregroundStyle(Color("white"))
    .padding({ horizontal: 16, vertical: 10 })
    .background(Color("blue"))
    .cornerRadius(8)

Disabled button

Button("Submit", () => {})
    .disabled(true)

Toggle

A switch control for toggling a boolean value on or off.

Toggle(props: {
    label?: string;
    isOn: boolean;
    setIsOn: (value: boolean) => void;
}): Component;

string

A text label displayed alongside the toggle switch.

boolean

required

The current state of the toggle.

(value: boolean) => void

required

Callback invoked when the user taps the toggle. Use this to update your state.

Basic toggle

const body = () => {
    const [enabled, setEnabled] = useState(false)
    return Toggle({ label: "Notifications", isOn: enabled, setIsOn: setEnabled })
}

With tint color

const body = () => {
    const [darkMode, setDarkMode] = useState(false)
    return Toggle({ label: "Dark Mode", isOn: darkMode, setIsOn: setDarkMode })
        .tint(Color("green"))
}

Settings list

const body = () => {
    const [wifi, setWifi] = useState(true)
    const [bluetooth, setBluetooth] = useState(false)
    return VStack({ spacing: 0 }, [
        Toggle({ label: "Wi-Fi", isOn: wifi, setIsOn: setWifi })
            .padding(16),
        Divider(),
        Toggle({ label: "Bluetooth", isOn: bluetooth, setIsOn: setBluetooth })
            .padding(16),
    ])
}

Slider

A continuous control for selecting a numeric value within a range.

Slider(props: {
    value: number;
    setValue: (value: number) => void;
    range?: [number, number];
    lowerBound?: number;
    upperBound?: number;
    step?: number;
    label?: string;
    minimumValueLabel?: Component;
    maximumValueLabel?: Component;
}): Component;

number

required

The current value of the slider.

(value: number) => void

required

Callback invoked as the user drags the slider. Use this to update your state.

[number, number]

The slider’s range as [lowerBound, upperBound]. The convenient form for setting both bounds at once.

number

The minimum value. Use instead of range when setting only one bound.

number

The maximum value. Use instead of range when setting only one bound.

number

The increment between selectable values. When omitted, the slider is continuous.

string

A text label describing what the slider controls. Some hosts display the label alongside the slider.

Component

A component shown at the lower end of the slider, typically a small Text.

Component

A component shown at the upper end of the slider.

Basic slider

const body = () => {
    const [volume, setVolume] = useState(50)
    return Slider({
        value: volume,
        setValue: setVolume,
        range: [0, 100],
    })
}

Stepped slider with labels

const body = () => {
    const [volume, setVolume] = useState(50)
    return Slider({
        value: volume,
        setValue: setVolume,
        range: [0, 100],
        step: 5,
        label: "Volume",
        minimumValueLabel: Text("0").font("caption"),
        maximumValueLabel: Text("100").font("caption"),
    })
}

Bounded with lowerBound and upperBound

const body = () => {
    const [opacity, setOpacity] = useState(1)
    return Slider({
        value: opacity,
        setValue: setOpacity,
        lowerBound: 0,
        upperBound: 1,
        step: 0.1,
    })
}

Picker

A selection control for choosing from a set of mutually exclusive values.

Picker<V extends Hashable = string>(
    label: string,
    selection: Binding<V>,
    children: Component[]
): Component;

string

required

The label text for the picker.

Binding<V>

required

A binding to the selected value, provided as a [value, setValue] tuple. The value type must be string or number.

Component[]

required

An array of picker options. Each child should have a .tag() modifier to identify its value.

Basic picker

const body = () => {
    const [color, setColor] = useState("red")
    return Picker("Color", [color, setColor], [
        Text("Red").tag("red"),
        Text("Green").tag("green"),
        Text("Blue").tag("blue")
    ])
}

Segmented picker

const body = () => {
    const [size, setSize] = useState("m")
    return Picker("Size", [size, setSize], [
        Text("S").tag("s"),
        Text("M").tag("m"),
        Text("L").tag("l"),
        Text("XL").tag("xl")
    ])
        .pickerStyle("segmented")
}

Picker in a form

const body = () => {
    const [country, setCountry] = useState("us")
    const [language, setLanguage] = useState("en")
    return VStack({ spacing: 16 }, [
        Picker("Country", [country, setCountry], [
            Text("United States").tag("us"),
            Text("Canada").tag("ca"),
            Text("United Kingdom").tag("uk")
        ]),
        Picker("Language", [language, setLanguage], [
            Text("English").tag("en"),
            Text("French").tag("fr"),
            Text("Spanish").tag("es")
        ])
    ])
}

With ForEach

const body = () => {
    const options = ["Option 1", "Option 2", "Option 3"]
    const [selected, setSelected] = useState(options[0])
    return Picker("Choose", [selected, setSelected], [
        ForEach(options, (option) =>
            Text(option).tag(option)
        )
    ])
}

Each child must have a .tag() value matching the type of the selection binding. Style the picker with .pickerStyle() using values like "menu", "segmented", "wheel", or "inline". See PickerStyle.

A dropdown menu of actions that appears when the label is tapped.

Menu(props: { label: Component }, children: Component[]): Component;

Component

required

The component displayed as the menu trigger. Typically a Button, Text, or Label.

Component[]

required

An array of menu items. Typically Button components, with optional Divider separators and nested Menu components for submenus.

Simple menu

Menu({ label: Text("Options") }, [
    Button("Edit", () => handleEdit()),
    Button("Delete", () => handleDelete())
])

Menu with icon label

Menu({ label: Image({ systemName: "ellipsis.circle" }) }, [
    Button("Share", () => {}),
    Button("Copy Link", () => {}),
    Divider(),
    Button("Report", () => {})
])

Nested submenu

Menu({ label: Text("Format") }, [
    Button("Bold", () => toggleBold()),
    Button("Italic", () => toggleItalic()),
    Divider(),
    Menu({ label: Text("Text Size") }, [
        Button("Small", () => setSize("small")),
        Button("Medium", () => setSize("medium")),
        Button("Large", () => setSize("large"))
    ])
])

Menu with button items using icons

Menu({ label: Image({ systemName: "gear" }) }, [
    Button({
        label: Label({ title: "Profile", systemImage: "person" }),
        action: () => showProfile()
    }),
    Button({
        label: Label({ title: "Notifications", systemImage: "bell" }),
        action: () => showNotifications()
    }),
    Divider(),
    Button({
        label: Label({ title: "Sign Out", systemImage: "arrow.right.square" }),
        action: () => signOut()
    })
])

Label

A standard label combining a title with an optional icon.

Label(props: {
    title: string | Component;
    icon?: Component;
    systemImage?: string;
}): Component;

string | Component

required

The label text. Can be a plain string or a component for custom styling.

Component

A custom icon component displayed alongside the title.

string

A system symbol name (SF Symbols) to use as the icon. Mutually exclusive with icon.

Label with system image

Label({ title: "Favorites", systemImage: "star.fill" })

Label with custom icon

Label({
    title: "Profile",
    icon: Image({ url: "https://example.com/avatar.png" })
        .resizable()
        .frame({ width: 20, height: 20 })
})

Label with styled title

Label({
    title: Text("Important")
        .foregroundStyle(Color("red")),
    systemImage: "exclamationmark.triangle"
})

Labels in a list

List([
    NavigationLink(
        Label({ title: "Messages", systemImage: "message" }),
        () => MessagesView()
    ),
    NavigationLink(
        Label({ title: "Calendar", systemImage: "calendar" }),
        () => CalendarView()
    ),
    NavigationLink(
        Label({ title: "Photos", systemImage: "photo" }),
        () => PhotosView()
    ),
])

ProgressView

A view that shows progress toward completion of a task, either determinate or indeterminate.

ProgressView(props?: { value: number; total?: number }): Component;

number

The current progress value. When provided, displays a determinate progress bar.

number

default:"1"

The value that represents full completion. Defaults to 1, so value is treated as a fraction (0 to 1).

Indeterminate spinner When called with no arguments, displays an indeterminate spinning indicator.

ProgressView()

Determinate progress bar

ProgressView({ value: 0.7 })

Custom total

ProgressView({ value: 75, total: 100 })

With label

VStack({ spacing: 8 }, [
    HStack([
        Text("Downloading..."),
        Spacer(),
        Text("60%")
    ]),
    ProgressView({ value: 0.6 })
])
    .padding(16)

Introduction

Authoring

Components

Components — iOS Extensions

Components — Web Extensions

Modifiers

Modifiers — iOS Extensions

Hooks and Globals

Styles

Types

Button

Toggle

Slider

Picker

Menu

Label

ProgressView

See also

​Button

​Toggle

​Slider

​Picker

​Menu

​Label

​ProgressView

​See also

Button

Toggle

Slider

Picker

Menu

Label

ProgressView

See also