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.
SwiftUI view modifiers that allow you to customize the appearance and behavior of UI components.
Installation
-
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
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
}
Type: {
rect: (cornerRadius: number) => {
cornerRadius: undefined | number
}
}
Methods
Parameter | Type | Description |
---|---|---|
hint | string | The accessibility hint |
Parameter | Type | Description |
---|---|---|
label | string | The accessibility label |
Parameter | Type | Description |
---|---|---|
value | string | The accessibility value |
Parameter | Type |
---|---|
value | boolean |
Sets whether text in this view can compress the space between characters when necessary to fit text in a line
ModifierConfig
Parameter | Type |
---|---|
animationObject | ChainableAnimationType |
animatedValue | number | boolean |
ModifierConfig
Parameter | Type | Description |
---|---|---|
params | {
contentMode: 'fill' | 'fit',
ratio: number
} | Width/height aspect ratio and content mode |
Parameter | Type | Description |
---|---|---|
color | Color | The background color (hex string, e.g., '#FF0000') |
Parameter | Type | Description |
---|---|---|
params | {
alignment: 'center' | 'top' | 'bottom' | 'leading' | 'trailing',
color: Color
} | Background color and alignment |
Adds a background behind the view.
ModifierConfig
Parameter | Type | Description |
---|---|---|
value(optional) | string | Text view to display as a badge. Set the value to nil to hide the badge. |
Parameter | Type | Description |
---|---|---|
badgeType | 'standard' | 'increased' | 'decreased' | Select the type of badge |
Parameter | Type | Description |
---|---|---|
params | {
color: Color,
width: number
} | The border parameters. Color and width. |
Parameter | Type | Description |
---|---|---|
amount | number | Brightness adjustment (-1 to 1) |
Parameter | Type | Description |
---|---|---|
style | 'bordered' | 'borderless' | 'automatic' | 'borderedProminent' | 'glass' | 'glassProminent' | 'plain' | The button style |
Parameter | Type | Description |
---|---|---|
clipped(optional) | boolean | Whether to clip content Default: true |
Parameter | Type | Description |
---|---|---|
shape | 'circle' | 'rectangle' | 'roundedRectangle' | The clipping shape |
cornerRadius(optional) | number | Corner radius for rounded rectangle (default: 8) |
Parameter | Type | Description |
---|---|---|
inverted(optional) | boolean | Whether to invert colors Default: true |
Parameter | Type | Description |
---|---|---|
shape | {
cornerRadius: undefined | number
} | A shape configuration from RoundedRectangularShape.rect() |
Sets the container shape for the view.
ModifierConfig
Parameter | Type | Description |
---|---|---|
amount | number | Contrast multiplier (0 to infinity, 1 = normal) |
Parameter | Type | Description |
---|---|---|
radius | number | The corner radius value |
Parameter | Type | Description |
---|---|---|
disabled(optional) | boolean | Whether the view should be disabled Default: true |
Parameter | Type | Description |
---|---|---|
params(optional) | {
horizontal: boolean,
vertical: boolean
} | Whether the view should use its ideal width or height |
Parameter | Type | Description |
---|---|---|
color | Color | The foreground color (hex string) |
Parameter | Type | Description |
---|---|---|
style | string | {
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):
Explicit Color Object:
Hierarchical Styles (Semantic): Auto-adapting semantic styles that respond to light/dark mode and accessibility settings:
Linear Gradient:
Radial Gradient:
Angular Gradient (Conic):
|
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.
ModifierConfig
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>
Parameter | Type | Description |
---|---|---|
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. |
Parameter | Type | Description |
---|---|---|
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. |
Parameter | Type | Description |
---|---|---|
id | string | The id of the glass effect |
namespaceId | string | 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
.
ModifierConfig
Parameter | Type | Description |
---|---|---|
amount | number | Grayscale amount (0 to 1) |
Parameter | Type | Description |
---|---|---|
prominence | 'standard' | 'increased' | The prominence to apply. |
Sets the header prominence for this view.
ModifierConfig
hidden(hidden)
Parameter | Type | Description |
---|---|---|
hidden(optional) | boolean | Whether the view should be hidden Default: true |
Parameter | Type | Description |
---|---|---|
angle | number | Hue rotation angle in degrees |
Parameter | Type | Description |
---|---|---|
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 |
Parameter | Type |
---|---|
value(optional) | number |
Parameter | Type | Description |
---|---|---|
priority | number | Layout priority value |
Parameter | Type | Description |
---|---|---|
value | number | 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.
ModifierConfig
Parameter | Type | Description |
---|---|---|
color | Color | The row color (hex string, e.g., '#FF0000') |
Parameter | Type | Description |
---|---|---|
params | {
bottom: number,
leading: number,
top: number,
trailing: number
} | The inset to apply to the rows in a list. |
Parameter | Type | Description |
---|---|---|
params(optional) | {
edges: 'top' | 'bottom' | 'leading' | 'trailing' | 'all' | 'horizontal' | 'vertical',
length: number
} | The margins to apply to the section in a list. |
Parameter | Type | Description |
---|---|---|
spacing | number | 'default' | 'compact' | The spacing to apply |
Sets the spacing between adjacent sections.
ModifierConfig
Parameter | Type | Description |
---|---|---|
shape | 'circle' | 'rectangle' | 'roundedRectangle' | The masking shape |
cornerRadius(optional) | number | Corner radius for rounded rectangle (default: 8) |
Parameter | Type | Description |
---|---|---|
id | string | The id of the view |
namespaceId | string | The namespace id of the view. Use Namespace component to create a namespace. |
Parameter | Type | Description |
---|---|---|
alignment | 'center' | 'leading' | 'trailing' | A value that you use to align multiple lines of text within a view. |
Parameter | Type | Description |
---|---|---|
params | {
x: number,
y: number
} | The offset parameters. x and y. |
Parameter | Type | Description |
---|---|---|
handler | () => void | Function to call when the view appears |
Parameter | Type | Description |
---|---|---|
handler | () => void | Function to call when the view disappears |
Parameter | Type | Description |
---|---|---|
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.
ModifierConfig
Parameter | Type | Description |
---|---|---|
handler | () => void | Function to call when tapped |
Parameter | Type | Description |
---|---|---|
value | number | Opacity value between 0 and 1 |
Parameter | Type | Description |
---|---|---|
params | {
alignment: 'center' | 'top' | 'bottom' | 'leading' | 'trailing',
color: Color
} | Overlay color and alignment |
Parameter | Type | Description |
---|---|---|
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. |
Parameter | Type | Description |
---|---|---|
angle | number | Rotation angle in degrees |
Parameter | Type | Description |
---|---|---|
amount | number | Saturation multiplier (0 to infinity, 1 = normal) |
Parameter | Type | Description |
---|---|---|
scale | number | Scale factor (1.0 = normal size) |
Parameter | Type | Description |
---|---|---|
visible | 'visible' | 'hidden' | 'automatic' | The visibility of the background |
Specifies the visibility of the background for scrollable views within this view.
ModifierConfig
Parameter | Type | Description |
---|---|---|
mode | 'automatic' | 'never' | 'interactively' | 'immediately' | The keyboard dismiss mode |
Parameter | Type | Description |
---|---|---|
params | {
color: Color,
radius: number,
x: number,
y: number
} | The shadow parameters. Radius, offset and color. |
Parameter | Type | Description |
---|---|---|
params | {
color: Color,
isActive: boolean,
pattern: LinePattern
} | Controls whether the strikethrough is visible ( |
Parameter | Type |
---|---|
value | 'lowercase' | 'uppercase' |
Sets a transform for the case of the text contained in this view when displayed.
ModifierConfig
Parameter | Type | Description |
---|---|---|
value | boolean | Enable selection |
Parameter | Type | Description |
---|---|---|
color | Color | The tint color (hex string) |
Parameter | Type | Description |
---|---|---|
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.
ModifierConfig
Parameter | Type | Description |
---|---|---|
params | {
color: Color,
isActive: boolean,
pattern: LinePattern
} | Controls whether the underline is visible ( |
Parameter | Type | Description |
---|---|---|
index | number | The z-index value |