foregroundStyle & background#

These two modifiers—foregroundStyle and background—allow you to customize the visual styling of view content and its background, supporting a wide range of styles including solid colors, gradients, materials, and dynamic appearances for light/dark mode.

foregroundStyle#

Definition#

1foregroundStyle?: ShapeStyle | DynamicShapeStyle | {
2  primary: ShapeStyle | DynamicShapeStyle
3  secondary: ShapeStyle | DynamicShapeStyle
4  tertiary?: ShapeStyle | DynamicShapeStyle
5}

Sets the style of a view’s foreground content, such as the color of text, shapes, or symbols. You can pass a single style or a layered style object (primary, secondary, tertiary) to support multi-layered rendering, such as in SF Symbols or decorated text.

Usage Examples#

Basic Foreground Color#

1<Text foregroundStyle="white">
2  Hello World!
3</Text>

Foreground with Dynamic Colors (Light/Dark Mode)#

1<Text
2  foregroundStyle={{
3    light: "black",
4    dark: "white"
5  }}
6>
7  Adaptive Text
8</Text>

Multi-layer Foreground Style#

1<Text
2  foregroundStyle={{
3    primary: "red",
4    secondary: "orange",
5    tertiary: "yellow"
6  }}
7>
8  Layered Style
9</Text>

Use layered styles primarily with views that support multistage rendering like system icons or stylized text.

background#

Definition#

1background?: 
2  | ShapeStyle 
3  | DynamicShapeStyle 
4  | { style: ShapeStyle | DynamicShapeStyle, shape: Shape }
5  | VirtualNode 
6  | { content: VirtualNode, alignment: Alignment }

Sets the background of a view. You can apply simple colors or gradients, or supply a custom shape or view as the background.

Background Variants#

1. ShapeStyle: Use a solid color, gradient, or material.
2. DynamicShapeStyle: Automatically switches styles between light and dark mode.
3. Shape with Fill Style: Use a shape (e.g., RoundedRectangle) with a style applied to it.
4. VirtualNode: Use another component as the background.
5. Custom Alignment: Align a background content explicitly behind the main view.

Usage Examples#

Solid Color Background#

1<Text background="systemBlue">
2  Hello
3</Text>

Gradient Background#

1<Text
2  background={{
3    gradient: [
4      { color: "purple", location: 0 },
5      { color: "blue", location: 1 }
6    ],
7    startPoint: { x: 0, y: 0 },
8    endPoint: { x: 1, y: 1 }
9  }}
10>
11  Gradient Background
12</Text>

Dynamic Background#

1<Text
2  background={{
3    light: "white",
4    dark: "black"
5  }}
6>
7  Mode-aware Background
8</Text>

Background with a Shape#

1<Text
2  background={
3    <RoundedRectangle fill="systemBlue" />
4  }
5>
6  Hello World!
7</Text>

Background with Custom Alignment#

1<Text
2  background={{
3    content: <Image filePath="path/to/background.jpg" />,
4    alignment: "center"
5  }}
6>
7  Overlayed Text
8</Text>

Related Types#

• ShapeStyle A visual style that defines how a foreground or background is rendered—this can be a color, gradient, or material. Supports "red", "systemBlue", "#FF0000", rgba(...), and gradient definitions.

• DynamicShapeStyle A light/dark mode–aware style with separate definitions for each appearance. The system automatically applies the appropriate style based on the current UI mode.

• VirtualNode A component used as a background, such as <Image />, <RoundedRectangle />, or any view that returns a JSX.Element.

• Shape A predefined shape such as RoundedRectangle, Circle, or Capsule, used for styled background shapes.

Summary#

These properties give you fine-grained control over visual styling and are essential for building rich, adaptive interfaces in the Scripting app.