Controls - Metabind

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;

label

string | Component

required

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

action

() => void

required

Callback invoked when the button is tapped.

When using the object form:

props.action

() => void

required

Callback invoked when the button is tapped.

props.label

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;

label

string

A text label displayed alongside the toggle switch.

isOn

boolean

required

The current state of the toggle.

setIsOn

(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;

value

number

required

The current value of the slider.

setValue

(value: number) => void

required

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

range

[number, number]

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

lowerBound

number

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

upperBound

number

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

step

number

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

label

string

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

minimumValueLabel

Component

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

maximumValueLabel

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;

label

string

required

The label text for the picker.

selection

Binding<V>

required

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

children

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;

props.label

Component

required

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

children

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;

title

string | Component

required

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

icon

Component

A custom icon component displayed alongside the title.

systemImage

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;

value

number

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

total

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)

​Button

​Toggle

​Slider

​Picker

​Menu

​Label

​ProgressView

​See also

Button

Toggle

Slider

Picker

Menu

Label

ProgressView

See also