Label

Expo UI Label matches the official SwiftUI Label API and displays a title alongside an icon.

Usage

Basic label with SF Symbol

import { Host, Label } from '@expo/ui/swift-ui';

export default function BasicLabelExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Label title="Favorites" systemImage="star.fill" />
    </Host>
  );
}

A star SF Symbol next to the title Favorites

With custom icon

Use the icon prop to provide a custom React node as the icon instead of an SF Symbol.

import { Host, Label, Image } from '@expo/ui/swift-ui';

export default function LabelCustomIconExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Label
        title="Custom Icon"
        icon={
          <Image systemName="sparkles" size={20} color="purple" />
        }
      />
    </Host>
  );
}

A purple sparkles SF Symbol next to the title Custom Icon

Icon only

Use the labelStyle modifier with iconOnly to display only the icon. Always provide a title for accessibility even though it won't be visible.

import { Host, Label } from '@expo/ui/swift-ui';
import { labelStyle } from '@expo/ui/swift-ui/modifiers';

export default function LabelIconOnlyExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Label
        title="Settings"
        systemImage="gear"
        modifiers={[labelStyle('iconOnly')]}
      />
    </Host>
  );
}

A gear SF Symbol shown alone, with no visible title text

API

import { Label } from '@expo/ui/swift-ui';

Component

`Label`

Type: React.Element<LabelProps>

Renders a native label view, which could be used in a list or section.

LabelProps

`children`

Optional • Type: ReactNode

Custom title view. Accepts any React node (for example, a VStack with title and subtitle). When provided, this takes precedence over title.

`color`

Deprecated: Use foregroundStyle modifier instead.

Optional • Type: ColorValue

The color of the label icon.

`icon`

Optional • Type: ReactNode

Custom icon view to be displayed in the label. When provided, this takes precedence over systemImage.

`systemImage`

Optional • Type: SFSymbols7_0

The name of the SFSymbol to be displayed in the label.

`title`

Optional • Type: string

The title text to be displayed in the label.

Inherited props

CommonViewModifierProps

Modifiers

Use these modifiers in the modifiers prop of the SwiftUI version.

Expo UI lets you put any of the 89 modifiers for any view on Label, but not all of them do something here.

70 change what you see on Label.
6 have no visible effect on Label.
13 work only in one place, such as a widget or a Grid.

Best modifiers for Label

These modifiers are made for Label, or they are the ones that you use most with it.

Also works on Label

Label takes these modifiers too, and each one works in the usual way.

No visible effect on Label

Label accepts these modifiers, but you see no change. They do not give an error.

Modifier	Why nothing happens
`accessibilityElement`	It joins the child views into one accessibility element, and Label takes no child views.
`containerShape`	It sets the shape that the child views use for `containerRelativeShape`, and Label takes no child views.
`disabled`	It turns off the controls in the view, and Label has none.
`geometryGroup` iOS 17+	It works on the child views that you give the component, and Label takes none.
`layoutPriority`	It has an effect only when the view shares an axis with other views in a stack.
`zIndex`	It changes the order of views that cover each other in the same parent, and Label does not stack its children.

Only in some places

These modifiers work only in a widget, in a Grid, in a Namespace or in a parent that asks for them.

Modifier	Where it works
`activityBackgroundTint`	Works only in a Live Activity. It has no effect in the app.
`alignmentGuide`	Has an effect only when the parent, such as a `VStack` or `ZStack`, aligns its children by the same guide.
`containerBackground`	Works only in a widget, or in a navigation container when you use a `navigation` placement.
`glassEffectId`	Works only on a view that also has `glassEffect`, in a `GlassEffectContainer` and a `Namespace`.
`gridCellAnchor` iOS 16+	Works only on a cell of a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellColumns`	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellUnsizedAxes`	Works only on a view in a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridColumnAlignment` iOS 16+	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`invalidatableContent` iOS 17+	Has an effect only when a parent view uses `redacted` with the `invalidated` reason.
`matchedGeometryEffect`	Works only in a `Namespace`. Give two views the same `id` and change between them with an animation.
`privacySensitive`	Has an effect only when a parent view uses `redacted` with the `privacy` reason.
`unredacted`	Has an effect only in a parent view that uses `redacted`.
`widgetURL`	Works only in a widget. It has no effect in the app.

Sources

The original Expo docs for this page:

Label (SwiftUI) (source-of-truth/versions/v57.0.0/sdk/ui/swift-ui/label.md)

On this page