Reference version

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 54).

SwiftUI view modifiers for customizing component appearance and behavior.

iOS
tvOS

SwiftUI view modifiers that allow you to customize the appearance and behavior of UI components.

Installation

Terminal
npx expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Modifiers are applied to components using the modifiers prop with an array syntax. You can combine multiple modifiers to create complex styling and behavior.

import { Text, Host, VStack } from '@expo/ui/swift-ui'; import { background, cornerRadius, padding, shadow, foregroundColor, onTapGesture, } from '@expo/ui/swift-ui/modifiers'; function ModifiersExample() { const [isEnabled, setIsEnabled] = useState(false); return ( <Host style={{ flex: 1 }}> <VStack spacing={20}> {/* Basic styling modifiers */} <Text modifiers={[ background('#FF6B6B'), cornerRadius(12), padding({ all: 16 }), foregroundColor('#FFFFFF'), ]}> Basic styled text </Text> {/* Complex combination with shadow and interaction */} <Text modifiers={[ background('#4ECDC4'), cornerRadius(16), padding({ horizontal: 20, vertical: 12 }), shadow({ radius: 4, x: 0, y: 2, color: '#4ECDC440' }), onTapGesture(() => console.log('Tapped!')), ]}> Styled with shadow and tap gesture </Text> {/* Conditional modifiers using spread operator */} <Text modifiers={[ background('#9B59B6'), cornerRadius(8), padding({ all: 14 }), ...(isEnabled ? [shadow({ radius: 6, y: 3 }), scaleEffect(1.02)] : [grayscale(0.5), opacity(0.7)]), ]}> Conditional styling </Text> </VStack> </Host> ); }

API

Constants

Animation

iOS
tvOS

Type: { default: ChainableAnimationType, easeIn: (params: TimingAnimationParams) => ChainableAnimationType, easeInOut: (params: TimingAnimationParams) => ChainableAnimationType, easeOut: (params: TimingAnimationParams) => ChainableAnimationType, interpolatingSpring: (params: InterpolatingSpringAnimationParams) => ChainableAnimationType, linear: (params: TimingAnimationParams) => ChainableAnimationType, spring: (params: SpringAnimationParams) => ChainableAnimationType }

RoundedRectangularShape

iOS
tvOS

Type: { rect: (cornerRadius: number) => { cornerRadius: undefined | number } }

Methods

accessibilityHint(hint)

iOS
tvOS
ParameterTypeDescription
hintstring

The accessibility hint


accessibilityLabel(label)

iOS
tvOS
ParameterTypeDescription
labelstring

The accessibility label


accessibilityValue(value)

iOS
tvOS
ParameterTypeDescription
valuestring

The accessibility value


allowsTightening(value)

iOS
tvOS
ParameterType
valueboolean

Sets whether text in this view can compress the space between characters when necessary to fit text in a line

animation(animationObject, animatedValue)

iOS
tvOS
ParameterType
animationObjectChainableAnimationType
animatedValuenumber | boolean

aspectRatio(params)

iOS
tvOS
ParameterTypeDescription
params{ contentMode: 'fill' | 'fit', ratio: number }

Width/height aspect ratio and content mode


background(color)

iOS
tvOS
ParameterTypeDescription
colorColor

The background color (hex string, e.g., '#FF0000')


backgroundOverlay(params)

iOS
tvOS
ParameterTypeDescription
params{ alignment: 'center' | 'top' | 'bottom' | 'leading' | 'trailing', color: Color }

Background color and alignment


Adds a background behind the view.

badge(value)

iOS
tvOS
ParameterTypeDescription
value(optional)string

Text view to display as a badge. Set the value to nil to hide the badge.


Generates a badge for the view from a localized string key.

badgeProminence(badgeType)

iOS
tvOS
ParameterTypeDescription
badgeType'standard' | 'increased' | 'decreased'

Select the type of badge


The prominence to apply to badges associated with this environment.

blur(radius)

iOS
tvOS
ParameterTypeDescription
radiusnumber

The blur radius


border(params)

iOS
tvOS
ParameterTypeDescription
params{ color: Color, width: number }

The border parameters. Color and width.


brightness(amount)

iOS
tvOS
ParameterTypeDescription
amountnumber

Brightness adjustment (-1 to 1)


buttonStyle(style)

iOS
tvOS
ParameterTypeDescription
style'bordered' | 'borderless' | 'automatic' | 'borderedProminent' | 'glass' | 'glassProminent' | 'plain'

The button style


Sets the button style for button views.

clipped(clipped)

iOS
tvOS
ParameterTypeDescription
clipped(optional)boolean

Whether to clip content

Default:true

clipShape(shape, cornerRadius)

iOS
tvOS
ParameterTypeDescription
shape'circle' | 'rectangle' | 'roundedRectangle'

The clipping shape

cornerRadius(optional)number

Corner radius for rounded rectangle (default: 8)


colorInvert(inverted)

iOS
tvOS
ParameterTypeDescription
inverted(optional)boolean

Whether to invert colors

Default:true

containerShape(shape)

iOS
tvOS
ParameterTypeDescription
shape{ cornerRadius: undefined | number }

A shape configuration from RoundedRectangularShape.rect()


Sets the container shape for the view.

contrast(amount)

iOS
tvOS
ParameterTypeDescription
amountnumber

Contrast multiplier (0 to infinity, 1 = normal)


cornerRadius(radius)

iOS
tvOS
ParameterTypeDescription
radiusnumber

The corner radius value


disabled(disabled)

iOS
tvOS
ParameterTypeDescription
disabled(optional)boolean

Whether the view should be disabled

Default:true

fixedSize(params)

iOS
tvOS
ParameterTypeDescription
params(optional){ horizontal: boolean, vertical: boolean }

Whether the view should use its ideal width or height


foregroundColor(color)

iOS
tvOS
ParameterTypeDescription
colorColor

The foreground color (hex string)


Sets the foreground color/tint of a view.

foregroundStyle(style)

iOS
tvOS
ParameterTypeDescription
stylestring | { color: string, type: 'color' } | { style: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary', type: 'hierarchical' } | { colors: string[], endPoint: { x: number, y: number }, startPoint: { x: number, y: number }, type: 'linearGradient' } | { center: { x: number, y: number }, colors: string[], endRadius: number, startRadius: number, type: 'radialGradient' } | { center: { x: number, y: number }, colors: string[], type: 'angularGradient' }

The foreground style configuration. Can be:

Simple Color (string):

  • Hex colors: '#FF0000', '#RGB', '#RRGGBB', '#AARRGGBB'
  • Named colors: 'red', 'blue', 'green', etc.

Explicit Color Object:

{ type: 'color', color: '#FF0000' }

Hierarchical Styles (Semantic): Auto-adapting semantic styles that respond to light/dark mode and accessibility settings:

{ type: 'hierarchical', style: 'primary' } // Most prominent (main content, headlines) { type: 'hierarchical', style: 'secondary' } // Supporting text, subheadlines { type: 'hierarchical', style: 'tertiary' } // Less important text, captions { type: 'hierarchical', style: 'quaternary' } // Subtle text, disabled states { type: 'hierarchical', style: 'quinary' } // Most subtle (iOS 16+, fallback to quaternary)

Linear Gradient:

{ type: 'linearGradient', colors: ['#FF0000', '#0000FF', '#00FF00'], startPoint: { x: 0, y: 0 }, // Top-left endPoint: { x: 1, y: 1 } // Bottom-right }

Radial Gradient:

{ type: 'radialGradient', colors: ['#FF0000', '#0000FF'], center: { x: 0.5, y: 0.5 }, // Center of view startRadius: 0, // Inner radius endRadius: 100 // Outer radius }

Angular Gradient (Conic):

{ type: 'angularGradient', colors: ['#FF0000', '#00FF00', '#0000FF'], center: { x: 0.5, y: 0.5 } // Rotation center }

Sets the foreground style of a view with comprehensive styling options.

Replaces the deprecated foregroundColor modifier with enhanced capabilities including colors, gradients, and semantic hierarchical styles that adapt to system appearance.

A view modifier that applies the specified foreground style

Example

// Simple usage <Text modifiers={[foregroundStyle('#FF0000')]}>Red Text</Text> // Adaptive hierarchical styling <Text modifiers={[foregroundStyle({ type: 'hierarchical', style: 'secondary' })]}> Supporting Text </Text> // Linear gradient <Text modifiers={[foregroundStyle({ type: 'linearGradient', colors: ['#FF6B35', '#F7931E', '#FFD23F'], startPoint: { x: 0, y: 0 }, endPoint: { x: 1, y: 0 } })]}> Gradient Text </Text>

frame(params)

iOS
tvOS
ParameterTypeDescription
params{ alignment: 'center' | 'top' | 'bottom' | 'leading' | 'trailing' | 'topLeading' | 'topTrailing' | 'bottomLeading' | 'bottomTrailing', height: number, idealHeight: number, idealWidth: number, maxHeight: number, maxWidth: number, minHeight: number, minWidth: number, width: number }

The frame parameters. Width, height, minWidth, maxWidth, minHeight, maxHeight, idealWidth, idealHeight and alignment.


glassEffect(params)

iOS
tvOS
ParameterTypeDescription
params(optional){ glass: { interactive: boolean, tint: Color, variant: 'clear' | 'regular' | 'identity' }, shape: 'circle' | 'rectangle' | 'capsule' | 'ellipse' }

The glass effect parameters. Variant, interactive, tint and shape.


glassEffectId(id, namespaceId)

iOS
tvOS
ParameterTypeDescription
idstring

The id of the glass effect

namespaceIdstring

The namespace id of the glass effect. Use Namespace component to create a namespace.


Associates an identity value to Liquid Glass effects defined within a GlassEffectContainer.

grayscale(amount)

iOS
tvOS
ParameterTypeDescription
amountnumber

Grayscale amount (0 to 1)


headerProminence(prominence)

iOS
tvOS
ParameterTypeDescription
prominence'standard' | 'increased'

The prominence to apply.


Sets the header prominence for this view.

hidden(hidden)

iOS
tvOS
ParameterTypeDescription
hidden(optional)boolean

Whether the view should be hidden

Default:true

hueRotation(angle)

iOS
tvOS
ParameterTypeDescription
anglenumber

Hue rotation angle in degrees


ignoreSafeArea(params)

iOS
tvOS
ParameterTypeDescription
params(optional){ edges: 'top' | 'bottom' | 'leading' | 'trailing' | 'all' | 'horizontal' | 'vertical', regions: 'all' | 'container' | 'keyboard' }

The safe area regions to ignore and the edges to expand into


kerning(value)

iOS
tvOS
ParameterType
value(optional)number

Sets the spacing, or kerning, between characters for the text in this view.

layoutPriority(priority)

iOS
tvOS
ParameterTypeDescription
prioritynumber

Layout priority value


lineSpacing(value)

iOS
tvOS
ParameterTypeDescription
valuenumber

The amount of space between the bottom of one line and the top of the next line in points. This value is always nonnegative. Otherwise, the default value will be used.


The distance in points between the bottom of one line fragment and the top of the next.

listRowBackground(color)

iOS
tvOS
ParameterTypeDescription
colorColor

The row color (hex string, e.g., '#FF0000')


listRowInsets(params)

iOS
tvOS
ParameterTypeDescription
params{ bottom: number, leading: number, top: number, trailing: number }

The inset to apply to the rows in a list.


listSectionMargins(params)

iOS
tvOS
ParameterTypeDescription
params(optional){ edges: 'top' | 'bottom' | 'leading' | 'trailing' | 'all' | 'horizontal' | 'vertical', length: number }

The margins to apply to the section in a list.


Allows a view to ignore safe area constraints.

listSectionSpacing(spacing)

iOS
tvOS
ParameterTypeDescription
spacingnumber | 'default' | 'compact'

The spacing to apply


Sets the spacing between adjacent sections.

mask(shape, cornerRadius)

iOS
tvOS
ParameterTypeDescription
shape'circle' | 'rectangle' | 'roundedRectangle'

The masking shape

cornerRadius(optional)number

Corner radius for rounded rectangle (default: 8)


matchedGeometryEffect(id, namespaceId)

iOS
tvOS
ParameterTypeDescription
idstring

The id of the view

namespaceIdstring

The namespace id of the view. Use Namespace component to create a namespace.


multilineTextAlignment(alignment)

iOS
tvOS
ParameterTypeDescription
alignment'center' | 'leading' | 'trailing'

A value that you use to align multiple lines of text within a view.


An alignment position for text along the horizontal axis.

offset(params)

iOS
tvOS
ParameterTypeDescription
params{ x: number, y: number }

The offset parameters. x and y.


Applies an offset (translation) to a view.

onAppear(handler)

iOS
tvOS
ParameterTypeDescription
handler() => void

Function to call when the view appears


onDisappear(handler)

iOS
tvOS
ParameterTypeDescription
handler() => void

Function to call when the view disappears


Adds an onDisappear modifier that calls a function when the view disappears.

onLongPressGesture(handler, minimumDuration)

iOS
tvOS
ParameterTypeDescription
handler() => void

Function to call when long pressed

minimumDuration(optional)number

Minimum duration for long press (default: 0.5s)


Adds a long press gesture recognizer.

onTapGesture(handler)

iOS
tvOS
ParameterTypeDescription
handler() => void

Function to call when tapped


opacity(value)

iOS
tvOS
ParameterTypeDescription
valuenumber

Opacity value between 0 and 1


overlay(params)

iOS
tvOS
ParameterTypeDescription
params{ alignment: 'center' | 'top' | 'bottom' | 'leading' | 'trailing', color: Color }

Overlay color and alignment


padding(params)

iOS
tvOS
ParameterTypeDescription
params{ all: number, bottom: number, horizontal: number, leading: number, top: number, trailing: number, vertical: number }

The padding parameters. Top, bottom, leading, trailing, horizontal, vertical and all.


Sets padding on a view. Supports individual edges or shorthand properties.

rotationEffect(angle)

iOS
tvOS
ParameterTypeDescription
anglenumber

Rotation angle in degrees


saturation(amount)

iOS
tvOS
ParameterTypeDescription
amountnumber

Saturation multiplier (0 to infinity, 1 = normal)


scaleEffect(scale)

iOS
tvOS
ParameterTypeDescription
scalenumber

Scale factor (1.0 = normal size)


scrollContentBackground(visible)

iOS
tvOS
ParameterTypeDescription
visible'visible' | 'hidden' | 'automatic'

The visibility of the background


Specifies the visibility of the background for scrollable views within this view.

scrollDismissesKeyboard(mode)

iOS
tvOS
ParameterTypeDescription
mode'automatic' | 'never' | 'interactively' | 'immediately'

The keyboard dismiss mode


Controls how the keyboard is dismissed when scrolling.

shadow(params)

iOS
tvOS
ParameterTypeDescription
params{ color: Color, radius: number, x: number, y: number }

The shadow parameters. Radius, offset and color.


strikethrough(params)

iOS
tvOS
ParameterTypeDescription
params{ color: Color, isActive: boolean, pattern: LinePattern }

Controls whether the strikethrough is visible (true to show, false to hide).


textCase(value)

iOS
tvOS
ParameterType
value'lowercase' | 'uppercase'

Sets a transform for the case of the text contained in this view when displayed.

textSelection(value)

iOS
tvOS
ParameterTypeDescription
valueboolean

Enable selection


Controls whether people can select text within this view.

tint(color)

iOS
tvOS
ParameterTypeDescription
colorColor

The tint color (hex string)


truncationMode(mode)

iOS
tvOS
ParameterTypeDescription
mode'head' | 'middle' | 'tail'

The truncation mode that specifies where to truncate the text within the text view, if needed. You can truncate at the beginning, middle, or end of the text view.


Sets the truncation mode for lines of text that are too long to fit in the available space.

underline(params)

iOS
tvOS
ParameterTypeDescription
params{ color: Color, isActive: boolean, pattern: LinePattern }

Controls whether the underline is visible (true to show, false to hide).


zIndex(index)

iOS
tvOS
ParameterTypeDescription
indexnumber

The z-index value


Sets the z-index (display order) of a view.