Gauge

Expo UI Gauge matches the official SwiftUI Gauge API and supports styling via the gaugeStyle modifier.

Usage

Basic gauge

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

export default function BasicGaugeExample() {
  // A linear gauge stretches to the width it is given, so give the host a size.
  return (
    <Host style={{ flex: 1 }}>
      <Gauge value={0.5} />
    </Host>
  );
}

With label

You can pass custom components as children to provide a label for the gauge.

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

export default function LabelExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Gauge value={0.7}>
        <Text>Progress</Text>
      </Gauge>
    </Host>
  );
}

A gauge with a Progress label rendered on iOS

With value labels

Use the currentValueLabel, minimumValueLabel, and maximumValueLabel props to display value information.

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

export default function ValueLabelsExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Gauge
        value={50}
        min={0}
        max={100}
        currentValueLabel={<Text>50%</Text>}
        minimumValueLabel={<Text>0</Text>}
        maximumValueLabel={<Text>100</Text>}>
        <Text>Usage</Text>
      </Gauge>
    </Host>
  );
}

A gauge with current, minimum, and maximum value labels rendered on iOS

Gauge styles

Use the gaugeStyle modifier to change the gauge's appearance. Available styles are: automatic, circular, circularCapacity, linear, and linearCapacity.

import { Host, Gauge, Text, VStack } from '@expo/ui/swift-ui';
import { gaugeStyle } from '@expo/ui/swift-ui/modifiers';

export default function GaugeStylesExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={16}>
        <Text>Circular</Text>
        <Gauge value={0.5} modifiers={[gaugeStyle('circular')]}>
          <Text>Circular</Text>
        </Gauge>
        <Text>Circular Capacity</Text>
        <Gauge
          value={0.5}
          modifiers={[gaugeStyle('circularCapacity')]}>
          <Text>Circular Capacity</Text>
        </Gauge>
        <Text>Linear</Text>
        <Gauge value={0.5} modifiers={[gaugeStyle('linear')]}>
          <Text>Linear</Text>
        </Gauge>
        <Gauge
          value={0.5}
          modifiers={[gaugeStyle('linearCapacity')]}>
          <Text>Linear Capacity</Text>
        </Gauge>
      </VStack>
    </Host>
  );
}

Circular, circular capacity, linear, and linear capacity gauge styles rendered on iOS

Tinted gauge

Use the tint modifier to change the gauge's color.

import { Host, Gauge, VStack } from '@expo/ui/swift-ui';
import { gaugeStyle, tint } from '@expo/ui/swift-ui/modifiers';

export default function TintedGaugeExample() {
  return (
    <Host style={{ flex: 1 }}>
      <VStack spacing={16}>
        <Gauge
          value={0.7}
          modifiers={[gaugeStyle('circular'), tint('green')]}
        />
        <Gauge
          value={0.3}
          modifiers={[gaugeStyle('linear'), tint('red')]}
        />
      </VStack>
    </Host>
  );
}

A green circular gauge and a red linear gauge rendered on iOS

API

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

Component

`Gauge`

Type: React.Element<GaugeProps>

Renders a SwiftUI Gauge component.

GaugeProps

`children`

Optional • Type: ReactNode

A label describing the gauge's purpose.

`currentValueLabel`

Optional • Type: ReactNode

A label showing the current value. Use Text or Label to display the value.

`max`

Optional • Type: number • Default: 1

The maximum value of the gauge range.

`maximumValueLabel`

Optional • Type: ReactNode

A label showing the maximum value. Use Text or Label to display the value.

`min`

Optional • Type: number • Default: 0

The minimum value of the gauge range.

`minimumValueLabel`

Optional • Type: ReactNode

A label showing the minimum value. Use Text or Label to display the value.

`value`

Type: number

The current value of the gauge.

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 Gauge, but not all of them do something here.

67 change what you see on Gauge.
9 have no visible effect on Gauge.
13 work only in one place, such as a widget or a Grid.

Best modifiers for Gauge

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

Also works on Gauge

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

No visible effect on Gauge

Gauge 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 Gauge takes no child views.
`containerShape`	It sets the shape that the child views use for `containerRelativeShape`, and Gauge takes no child views.
`contentShape`	It changes the area that gets touches, and Gauge gets no touches of its own.
`geometryGroup` iOS 17+	It works on the child views that you give the component, and Gauge takes none.
`imageScale`	It changes only SF Symbols, and Gauge shows none.
`layoutPriority`	It has an effect only when the view shares an axis with other views in a stack.
`onLongPressGesture`	In SDK 57, Gauge does not send modifier events to JavaScript, so the handler does not run.
`onTapGesture`	In SDK 57, Gauge does not send modifier events to JavaScript, so the handler does not run.
`zIndex`	It changes the order of views that cover each other in the same parent, and Gauge 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:

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

On this page