API Reference

This document provides a comprehensive reference for all native template elements and their properties, methods, and types.

Layout
View
ScrollView
ImageView
VideoView
Label
TextField
TextView
BlurView
SpinnerView
ShapeView
AnimatedImage
Slot
Common Types

Note: Layout and positioning attributes are powered by Yoga (commit 0be0e9fc). See Style Attributes Reference for Yoga version details and flexbox behavior.

Layout

JSX Element: <layout>

Represents a node in the layout tree. Use a <layout> instead of <view> whenever possible, since these nodes will not be backed by a platform view when rendering, making them more performant.

Properties

Layout Attributes

Lifecycle Callbacks

onLayout: (frame: ElementFrame) => void

Called whenever the calculated frame for the element has changed.

onVisibilityChanged: (isVisible: boolean, eventTime: EventTime) => void

Called whenever the visibility for the element has changed.

onViewportChanged: (viewport: ElementFrame, frame: ElementFrame, eventTime: EventTime) => void

Called whenever the calculated viewport for the element has changed.
The viewport represents the rectangle area within the element's frame that is visible.

onLayoutComplete: () => void

Called after a layout pass has completed, if this node or any of its children were updated.

onMeasure: OnMeasureFunc

If set, the node will be set as a lazyLayout, and the given measure callback will be called whenever the node needs to be measured.
The callback should return a MeasuredSize tuple representing how big the node should be.
Type: (width: number, widthMode: MeasureMode, height: number, heightMode: MeasureMode) => MeasuredSize

Performance Optimization

lazyLayout: boolean

Whether the layout starting from this element should be lazy.
A lazy layout is disconnected from its parent layout; its children cannot impact the layout of the parent.
Setting this to true will defer layout calculation for all the children until this layout is determined to be visible.
This can help with performance when the layout is within a ScrollView.
Default: false

limitToViewport: boolean

Whether the backing native View instance should only be created if the element is visible within the viewport.
Setting this to true can help with performance when the view is within a ScrollView.
Default: true

lazy: boolean

Shorthand for lazyComponent, lazyLayout and limitToViewport.
Default: false

estimatedWidth: number

If set, the node will use this value as the base width that the node should measure at before the children are inserted.
This is typically used on nodes that represent an empty placeholder that are later rendered with children.

estimatedHeight: number

If set, the node will use this value as the base height that the node should measure at before the children are inserted.

Identity & References

id: string

Used to uniquely identify an element in the global valdi context.

key: string

A key to uniquely identify the element.
If it is not provided, the framework will generate one based on the index in which the element is being rendered.

ref: IRenderedElementHolder<this>

Sets an element reference holder, which will keep track of the rendered elements.

Visual Properties

animationsEnabled: boolean

Can be used to disable animations for this element and its children.
Default: true

zIndex: number

Loosely, zIndex specifies the order in which siblings are layered on top of each other.
Higher zIndex will mean that an element will be rendered "on top" of its siblings.
Specifying a zIndex will make the framework sort this element and its siblings before rendering the view tree.

class: string

Sets a CSS class to use from the associated CSS document.
You typically would use the style property directly instead.

ignoreParentViewport: boolean

Whether the calculated viewport for this element should not be intersected with the viewport of the parent.
This allows a child to have a viewport bigger than its parent.

Size Properties

width: CSSValue (string | number)

Specifies the width of an element's content area.
auto (default): width for the element based on its content.
points: Defines the width in absolute points.
percentage: Defines the width in percentage of its parent's width.

height: CSSValue

Specifies the height of an element's content area.
auto (default): height for the element based on its content.
points: Defines the height in absolute points.
percentage: Defines the height in percentage of its parent's height.

minWidth: CSSValue

Specifies the minimum width of an element's content area.

minHeight: CSSValue

Specifies the minimum height of an element's content area.

maxWidth: CSSValue

Specifies the maximum width of an element's content area.

maxHeight: CSSValue

Specifies the maximum height of an element's content area.

aspectRatio: number

Specifies the aspect ratio of an element's content area.
Defined as the ratio between the width and the height of a node.
e.g. if a node has an aspect ratio of 2 then its width is twice the size of its height.

Position Properties

position: 'relative' | 'absolute'

The position type of an element defines how it is positioned within its parent.
relative (default): positioned according to the normal flow of the layout, then offset relative to that position based on the values of top, right, bottom, and left.
absolute: doesn't take part in the normal layout flow. Position is determined based on the top, right, bottom, and left values.

top: CSSValue

Used with position to offset the element from its normal position or parent.

right: CSSValue

Used with position to offset the element from its normal position or parent.

bottom: CSSValue

Used with position to offset the element from its normal position or parent.

left: CSSValue

Used with position to offset the element from its normal position or parent.

Spacing Properties

margin: string | number

Margin affects the spacing around the outside of a node.
A node with margin will offset itself from the bounds of its parent but also offset the location of any siblings.

marginTop: CSSValue

marginRight: CSSValue

marginBottom: CSSValue

marginLeft: CSSValue

padding: string | number

Padding affects the size of the node it is applied to.
Padding will not add to the total size of an element if it has an explicit size set.

paddingTop: CSSValue

paddingRight: CSSValue

paddingBottom: CSSValue

paddingLeft: CSSValue

Flexbox Properties

display: 'flex' | 'none'

Choose the display mode.
flex: use flexbox layout system
none: do not display this element
Default: 'flex'

overflow: 'visible' | 'scroll'

Specifies how the parent will react to its children overflowing its boundaries.
visible: overflowing children elements will stretch the parent container
scroll: the parent container's size will not be affected by the children element's bounds
Default for layout elements: 'visible'
Default for scroll elements: 'scroll'

direction: 'inherit' | 'ltr' | 'rtl'

Layout direction specifies the direction in which children and text in a hierarchy should be laid out.
inherit (default): Use the parent's direction value
ltr: Text and children laid out from left to right
rtl: Text and children laid out from right to left
Default: 'inherit'

flexDirection: 'column' | 'column-reverse' | 'row' | 'row-reverse'

Controls the direction in which children of a node are laid out.
column (default): Align children from top to bottom
column-reverse: Align children from bottom to top
row: Align children from left to right
row-reverse: Align children from right to left
Default: 'column'

flexWrap: 'no-wrap' | 'wrap' | 'wrap-reverse'

Set on containers and controls what happens when children overflow the size of the container along the main axis.
Default: children are forced into a single line
wrap: items are wrapped into multiple lines along the main axis if needed
wrap-reverse: same as wrap but the order of the lines is reversed

Describes how to align children within the main axis of their container.
flex-start (default): Align children to the start of the container's main axis
flex-end: Align children to the end
center: Align children in the center
space-between: Evenly space children, distributing remaining space between them
space-around: Evenly space children, distributing remaining space around them
space-evenly: Evenly distributed with equal spacing
Default: 'flex-start'

Defines the distribution of lines along the cross-axis.
Only has effect when items are wrapped to multiple lines using flexWrap.
Default: 'flex-start'

alignItems: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline'

Describes how to align children along the cross axis of their container.
stretch (default): Stretch children to match the height of the container's cross axis
flex-start: Align children to the start of the container's cross axis
flex-end: Align children to the end
center: Align children in the center
baseline: Align children along a common baseline
Default: 'stretch'

Overrides the parent's alignItems for this specific child.

flexGrow: number

Describes how any space within a container should be distributed among its children along the main axis.
Accepts any floating point value >= 0
Default: 0

flexShrink: number

Describes how to shrink children along the main axis when the total size of the children overflow the size of the container.
Accepts any floating point value >= 0
Default: 0

flexBasis: CSSValue

Provides the default size of an item along the main axis.
Similar to setting width (for row) or height (for column).

extendViewportWithChildren: boolean

Whether the calculated viewport for the element should be potentially extended by taking into account the space of all the children.
By default, a child element outside the bounds of the parent element is considered invisible.
When this flag is true, the bounds of the parent will be extended such that the children are always visible.
This flag should be used rarely and in very specific circumstances.
Default: false

Accessibility Properties

Specify meta information that can then be used by accessibility technologies.
Default: 'auto'

Specify the way the element should behave during navigation by accessibility technologies.
auto: automatically chosen depending on the element
passthrough: element is not focusable, but its children may be accessed
leaf: element is fully focusable and interactive but none of its children are navigatable
cover: element is first fully focusable and interactive and afterward its children can also be accessed
group: element may be announced but not focused and its children may also be accessed
ignored: element and all its children will be ignored, unnavigatable and unfocusable
Default: 'auto'

accessibilityPriority: number | AccessibilityPriority

Specify the local priority of the element (compared to its direct sibling) for accessibility navigation sequential ordering.
All sibling elements are sorted by descending priority during accessibility navigation.
Default: 0

accessibilityLabel: string

Defines the information being displayed.
When an element is accessed by accessibility technologies, VoiceOver/TalkBack will read this string.

accessibilityHint: string

Defines the purpose of this element.
Additional hint that helps users understand what will happen when they perform an action on the accessibility element.

accessibilityValue: string

For elements that intrinsically contain information (such as textinputs or sliders).
Especially when it may be dynamic, we need to provide its current value.

accessibilityStateDisabled: boolean

For dynamic and interactive elements, indicate that the element is temporarily disabled.
Default: false

accessibilityStateSelected: boolean

For dynamic and interactive elements, set the current selection status.
Default: false

accessibilityStateLiveRegion: boolean

For dynamic and interactive elements, indicate that the element frequently updates its label, value or children.
Default: false

Styling

style: IStyle<Layout>

Styling object allows setting multiple attributes at once.
See Layout Style Attributes for a complete list of attributes that can be used in Style<Layout>.

View

JSX Element: <view>

iOS Native: SCValdiView
Android Native: com.snap.valdi.views.ValdiView

Represents a node in the layout tree backed by a native platform view. Use a <layout> instead of <view> whenever possible for better performance.

Properties

All properties from Layout, plus:

Lifecycle Callbacks

onViewCreate: () => void

Called whenever the backing native view is created.

onViewDestroy: () => void

Called whenever the backing native view is destroyed.

onViewChange: (nativeView: NativeView | undefined) => void

Called whenever the backing native view is created or destroyed.
@deprecated use IRenderedElement.getNativeNode

allowReuse: boolean

Whether the backing native View instance can be re-used.
By default, View instances are re-used across screens.
By setting this to false, the view instance will be guaranteed to be new and not re-used from the view pool.
Default: true

Appearance

background: string

Sets the background of the view.
Use "color1" to set a color.
Use "linear-gradient(color1, color2, color3...)" to set a gradient with evenly-spaced stops.
Use "linear-gradient(color1 stop1, color2 stop2, color3 stop3...)" to set a gradient with custom stops.

backgroundColor: Color (string)

Sets the background color of the view.
undefined sets a clear color.

opacity: number

Sets the opacity of the view.
Accepts values: [0.0 - 1.0]
Note: Making a view non-opaque will require layer blending.

slowClipping: boolean

Enables clipping of the view's contents based on the view's borders.
Warning: degrades performance, avoid using if possible.
Default: false

Border Properties

border: string

Short-hand for all the borderXXX attributes.

borderWidth: CSSValue

Sets the width of an element's border.
Note: make sure to set the borderColor
Default: 0

borderColor: Color

Sets the color of an element's four borders.
Note: make sure to set the borderWidth for the border to be visible
Default: black

borderRadius: CSSValue

Defines the radius of the element's corners.
Can specify radius on a per-corner basis: "5 10 0 20" (top/left/right/bottom)
Or set all corners at once: "10"
Default: 0

boxShadow: string

Add a shadow to the view.
Syntax: '{xOffset} {yOffset} {shadowOverflow} {color}'
All number values are interpreted as points.
Example: "0 2 10 rgba(0, 0, 0, 0.1)"

Gesture Properties

touchEnabled: boolean

Set this to false to disable any user interactions on this view and its children.
Default: true

hitTest: (event: TouchEvent) => boolean

Determines if a given view can capture any touches.

onTouch: (event: TouchEvent) => void

Event handler called on every touch event captured by this view (started, changed, ended).

onTouchStart: (event: TouchEvent) => void

Event handler called on the 'started' touch events captured by this view.

onTouchEnd: (event: TouchEvent) => void

Event handler called on the 'ended' touch events captured by this view.

onTouchDelayDuration: number

Specifies the minimum duration, in seconds, for an onTouch event to trigger.
When not set, will be zero.

Tap Gestures

onTapDisabled: boolean

Set to true to disable tap completely.
Default: false

onTap: (event: TouchEvent) => void

The handler that will be called when the user performs a tap gesture on this view.

onTapPredicate: (event: TouchEvent) => boolean

The predicate used to decide whether the tap gesture should be recognized.
Prefer using onTapDisabled if the decision can be made without TouchEvent data.

Double Tap Gestures

onDoubleTapDisabled: boolean

Set to true to disable double tap completely.
Default: false

onDoubleTap: (event: TouchEvent) => void

Handler called when the user performs a double tap gesture.

onDoubleTapPredicate: (event: TouchEvent) => boolean

Predicate to decide whether the double tap gesture should be recognized.

Long Press Gestures

longPressDuration: number

Specifies the minimum duration, in seconds, for a long press to trigger.
When not set, will use a platform provided default.

onLongPressDisabled: boolean

Set to true to disable long press completely.
Default: false

onLongPress: (event: TouchEvent) => void

Handler called when the user performs a long press gesture.

onLongPressPredicate: (event: TouchEvent) => boolean

Predicate to decide whether the long press gesture should be recognized.

Drag Gestures

onDragDisabled: boolean

Set to true to disable drag completely.
Default: false

onDrag: (event: DragEvent) => void

Handler called when the user performs a dragging gesture that started on this view.

onDragPredicate: (event: DragEvent) => boolean

Predicate to decide whether the drag gesture should be recognized.

Pinch Gestures

onPinchDisabled: boolean

Set to true to disable pinch completely.
Default: false

onPinch: (event: PinchEvent) => void

Handler called when the user performs a pinch gesture on this view.

onPinchPredicate: (event: PinchEvent) => boolean

Predicate to decide whether the pinch gesture should be recognized.

Rotate Gestures

onRotateDisabled: boolean

Set to true to disable rotate completely.
Default: false

onRotate: (event: RotateEvent) => void

Handler called when the user performs a rotate gesture on this view.

onRotatePredicate: (event: RotateEvent) => boolean

Predicate to decide whether the rotate gesture should be recognized.

Touch Area Extension

touchAreaExtension: number

Can be used to increase the view's touch target area.

touchAreaExtensionTop: number

touchAreaExtensionRight: number

touchAreaExtensionBottom: number

touchAreaExtensionLeft: number

Transform Properties

scaleX: number

Specifies the horizontal scale component of the affine transformation to be applied to the view.

scaleY: number

Specifies the vertical scale component of the affine transformation to be applied to the view.

rotation: number

Specifies the rotation component in angle radians of the affine transformation to be applied to the view.

translationX: number

Specifies the horizontal translation component of the affine transformation to be applied to the view.
Note: When the device is in RTL mode, the applied translationX value will be flipped.

translationY: number

Specifies the vertical translation component of the affine transformation to be applied to the view.

Mask Properties

maskOpacity: number

Set an opacity to use on mask.
The opacity defines how much the mask should "erase" pixels that match the maskPath.
Opacity of 1 will make all the pixels matching the path transparent.
Default: 1

maskPath: GeometricPath

Set a geometric path to use as a mask on the given view.
Pixels that are within the given path will be turned transparent relative to the maskOpacity.

Platform-Specific

accessibilityId: string

Sets the view's accessibility identifier.
Commonly used to identify UI elements in UI tests.

canAlwaysScrollHorizontal: boolean

Forces the platform surface method canScroll to always return true for horizontal touch events.
This property can be used to ensure that any platform-specific gesture handlers can be ignored when a valdi module would capture the event.

canAlwaysScrollVertical: boolean

Forces the platform surface method canScroll to always return true for vertical touch events.

filterTouchesWhenObscured: boolean

Optionally set filterTouchesWhenObscured for payment sensitive button on Android.
Not used for iOS.

Styling

style: IStyle<View | Layout>

Styling object allows setting multiple attributes at once.
See View Style Attributes for a complete list of attributes that can be used in Style<View>.

ScrollView

JSX Element: <scroll>

iOS Native: SCValdiScrollView
Android Native: com.snap.valdi.views.ValdiScrollView

A view that provides scrolling functionality for its children.

Properties

All properties from View, except flexDirection (which is replaced by horizontal), plus:

Scroll Event Callbacks

onScroll: (event: ScrollEvent) => void

Called when the content offset of the scrollview changed.

onScrollEnd: (event: ScrollEndEvent) => void

Called when the content offset of the scrollview has settled.

onDragStart: (event: ScrollEvent) => void

Called when the user starts dragging the scroll content.

onDragEnding: (event: ScrollDragEndingEvent) => ScrollOffset | undefined

Called synchronously when the ScrollView will end dragging.
The called function can return a scroll offset that should be used to replace the content offset where the scroll view should settle.

onDragEnd: (event: ScrollDragEndEvent) => void

Called when the ScrollView ended dragging.
This will be called right after onDragEnding() is called, and will be called asynchronously.
The scroll view might still be animating its scroll at this point.

onContentSizeChange: (event: ContentSizeChangeEvent) => void

Called whenever the content size of the scroll view has changed.

Scroll Behavior

horizontal: boolean

When enabled, the scroll view will allow horizontal scrolling instead of vertical.
Note: this attribute replaces flexDirection.
When enabled, children will be laid out as if flexDirection="row" was set.
When disabled, children will be laid out as if flexDirection="column" was set.
Default: false

flexDirection: never

FlexDirection is not available on scroll views.
It can be set through the "horizontal" attribute.

scrollEnabled: boolean

When enabled, the scroll view can be scrolled by the user.
Default: true

pagingEnabled: boolean

When enabled, the scroll content offset will always settle on a multiple of the scrollview's size.
Default: false

Bounce/Overscroll

bounces: boolean

Configure whether or not there should be a visual effect when the user tries to scroll past the scroll boundaries.
On iOS: this visually looks like letting the user "bounce" on the edge of the scroll view.
On Android: this looks like a glow or squish effect that follows the finger or a bounce if using skia.
Default: true

bouncesFromDragAtStart: boolean

Allow bouncing by dragging even when the content offset is already at the minimum.
Default: true

bouncesFromDragAtEnd: boolean

Allow bouncing by dragging even when the content offset is already at the maximum.
Default: true

bouncesVerticalWithSmallContent: boolean

Allow bouncing even when the vertical content size is smaller than the scroll itself.
Default: false

bouncesHorizontalWithSmallContent: boolean

Allow bouncing even when the horizontal content size is smaller than the scroll itself.
Default: false

Touch/Gesture Behavior

cancelsTouchesOnScroll: boolean

Cancels all active touch gestures (from onTouch) of the scroll view's children when dragging the scroll view content.
Default: true

dismissKeyboardOnDrag: boolean

If the keyboard is open, close it when we start scrolling.
Default: false

dismissKeyboardOnDragMode: 'immediate' | 'touch-exit-below'

When dismissKeyboardOnDrag is true, this changes the behavior of when the keyboard is dismissed.
immediate: keyboard is dismissed as soon as scrolling begins
touch-exit-below: keyboard is dismissed when the scroll drag gesture touches leave the lower boundary of the scroll bounds
Default: 'immediate'

Visual Indicators

showsVerticalScrollIndicator: boolean

Shows the scroll indicator when scrolling vertically.
Default: true

showsHorizontalScrollIndicator: boolean

Shows the scroll indicator when scrolling horizontally.
Default: true

fadingEdgeLength: number

Create a fade effect on the content of the scroll view when scrolling is possible.
This attribute can control the size of the effect.
Default: 0

Viewport Extensions

viewportExtensionTop: number

Can be used to extend the visible viewport of the scroll element.
When scrolling, this will cause child elements to be rendered potentially earlier (if positive) or later (if negative).
Default: 0

viewportExtensionRight: number

Extends the visible viewport on the right side.
Default: 0

viewportExtensionBottom: number

Extends the visible viewport on the bottom side.
Default: 0

viewportExtensionLeft: number

Extends the visible viewport on the left side.
Default: 0

Advanced Features

circularRatio: number

Enables circular scroll by specifying the ratio between the calculated content size of the scroll element to the size of a single scrollable page.
For circular scroll to work properly, the children elements must be re-rendered at least twice, in which case circularRatio should be set to 2.
Default: 0 (scroll is not circular)

decelerationRate: 'normal' | 'fast'

[iOS-Only] Defines the rate at which the scroll view decelerates after a fling gesture.
Default: 'normal'

scrollPerfLoggerBridge: IScrollPerfLoggerBridge

Set this to enable scroll performance logging with given attribution parameters.
To get a value of this type, see AttributedCallsite.forScrollPerfLogging

Interactive Properties (Programmatic Only)

These properties should not be used in TSX tags, only for programmatic attribute manipulation:

contentOffsetX: number

Can be programmatically set to change the current horizontal scroll offset.

contentOffsetY: number

Can be programmatically set to change the current vertical scroll offset.

contentOffsetAnimated: boolean

When set to true, any programmatic change to the contentOffset will be animated.

staticContentWidth: number

When set, the scrollable content width will be based on this value for operations like snapping and scrolling.
This will bypass the automatic measurement.

staticContentHeight: number

When set, the scrollable content height will be based on this value for operations like snapping and scrolling.
This will bypass the automatic measurement.

Styling

style: IStyle<ScrollView | View | Layout>

See ScrollView Style Attributes for a complete list of attributes that can be used in Style<ScrollView>.

ImageView

JSX Element: <image>

iOS Native: SCValdiImageView
Android Native: com.snap.valdi.views.ValdiImageView

A view for displaying images from local assets or remote URLs.

Properties

All properties from Layout Attributes, plus:

Image Source

src: string | Asset

Specify the image asset or url to be rendered within the image's bounds.
Can be a URL string or an Asset object.
Default: undefined

Image Display

objectFit: 'fill' | 'contain' | 'cover' | 'none'

Define how the image should be resized within the image view's bounds.
Useful when the aspect ratio of the image bounds may be different than the image asset content's aspect ratio.
fill: stretch the image to fill the image view's bounds
contain: conserve aspect ratio and scale to fit within bounds (can leave blank space)
cover: conserve aspect ratio and scale to fill bounds (can crop parts of the image)
none: conserve aspect ratio and don't scale to fit (just rendered in center)
Default: 'fill'

tint: Color

Apply a color tint on every pixel of the image.
Default: undefined

flipOnRtl: boolean

When the current layout is in RTL, horizontally-mirror-flip the image's content.
Default: false

Content Transform

contentScaleX: number

Scale horizontally the content of the image within the image's bounds.
Default: 1

contentScaleY: number

Scale vertically the content of the image within the image's bounds.
Default: 1

contentRotation: number

Rotate the content of the image in radians.
Default: 0

Filters

filter: ImageFilter

A post processing filter to apply on the image.

Callbacks

onAssetLoad: (success: boolean, errorMessage?: string) => void

Called when the loaded image asset has either successfully loaded or failed to load.

onImageDecoded: (width: number, height: number) => void

Called when the image has been loaded and we have the dimensions.
Note: dimensions returned are of the raw image which may be different than the view.

View Properties

All view properties from View including:

Lifecycle callbacks (onViewCreate, onViewDestroy)
Appearance properties (backgroundColor, opacity, border, etc.)
Gesture handlers (tap, drag, etc.)
Transform properties

Styling

style: IStyle<ImageView | View | Layout>

See ImageView Style Attributes for a complete list of attributes that can be used in Style<ImageView>.

VideoView

JSX Element: <video>

iOS Native: SCValdiVideoView
Android Native: com.snap.valdi.views.ValdiVideoView

A view for displaying and controlling video playback.

Properties

All properties from Layout Attributes, plus:

Video Source

src: string | Asset

Specify the video asset or url to be rendered within the view's bounds.
Default: undefined

Playback Control

volume: number

Float between 0 and 1.

playbackRate: number

0 is paused
1 is playing
Default: paused

seekToTime: number

In milliseconds.

Callbacks

onVideoLoaded: (duration: number) => void

A callback to be called when the video is loaded.
Hands back the length of the video in milliseconds.

onBeginPlaying: () => void

Callback for when the video begins playing.

onError: (error: string) => void

Callback to be called when there's an error.

onCompleted: () => void

Callback to be called when the video completes.

onProgressUpdated: (time: number, duration: number) => void

Callback called when the video progress updates.
time is in milliseconds
duration is in milliseconds
Frequency may differ from platform to platform.

View Properties

All view properties from View.

Styling

style: IStyle<VideoView | View | Layout>

See VideoView Style Attributes for a complete list of attributes that can be used in Style<VideoView>.

Label

JSX Element: <label>

iOS Native: SCValdiLabel
Android Native: android.widget.TextView

A view for displaying text.

Properties

All properties from Layout Attributes, plus:

Text Content

value: string | AttributedText

The text value of the label.
Use the AttributedTextBuilder class to set a value composed of multiple strings with different text attributes.

Text Styling

font: string

Set the font used to render the text characters.
This attribute must be a string with 4 parts separated by space:
1. required: the name of the font (including the font's weight)
2. required: the size of the font
3. optional: the scaling type (or 'unscaled' for no scaling)
4. optional: the maximum size of the font after scaling
Example: 'AvenirNext-Bold 16 unscaled 16'
Default: 'system 12'

color: Color

Set the rendering color for the text characters.
Default: black

textGradient: string

Set the Gradient color for the text string. Overrides color setting.
Use "linear-gradient(color1, color2, color3...)" for evenly-spaced stops.
Use "linear-gradient(color1 stop1, color2 stop2, color3 stop3...)" for custom stops.

textShadow: string

Add a shadow to the text.
Syntax: '{color} {radius} {opacity} {offsetX} {offsetY}'
All number values are interpreted as points.
Note: TextShadow and BoxShadow are mutually exclusive.
Example: 'rgba(0, 0, 0, 0.1) 1 1 1 1'

Text Layout

numberOfLines: number

This property controls the maximum number of lines to use to fit the label's text into its bounding rectangle.
To remove any maximum limit, and use as many lines as needed, set the value to 0.
Default: 1

textAlign: 'left' | 'right' | 'center' | 'justified'

Set the horizontal alignment behavior for the label's text.
Note: it will automatically invert in RTL locales:
- In RTL locales, "left" will align text to the right of the label's bounds
- In RTL locales, "right" will align text to the left of the label's bounds
Default: 'left'

textDecoration: 'none' | 'strikethrough' | 'underline'

Optionally adds a visual decoration effect to the label's text.
Default: undefined

lineHeight: number

Rendering size of each line of the label, this value is a ratio of the font height.
If the lineHeight ratio is above 1, spacing is added on top of each line of the text.
Example: A value of 2 will double the height of each line.
Default: 1

letterSpacing: number

Extra spacing added at the end of each character, in points.
Note: negative values will shrink the space between characters.
Default: 0

textOverflow: 'ellipsis' | 'clip'

Controls how hidden text overflow content is signaled to users.
Default: 'ellipsis'

Auto-sizing

adjustsFontSizeToFitWidth: boolean

If this property is true, and the text exceeds the label's bounding rectangle, the label reduces the font size until the text fits or it has scaled down to the minimum font size.
If you set this to true, be sure to also set an appropriate minimum font scale with minimumScaleFactor.
Notes:
- This autoshrinking behavior is mostly intended for use with a single-line label when numberOfLines == 1.
- This will also work when for multiline using numberOfLines > 0 but the behavior will be much less predictable.
- Specifying the label's width/height/minHeight will make the auto-shrink behavior much more predictable.
Default: false

minimumScaleFactor: number

If adjustsFontSizeToFitWidth is true, use this property to specify the smallest multiplier for the current font size that yields an acceptable font size for the label's text.
Default: 0

View Properties

All view properties from View.

Styling

style: IStyle<Label | View | Layout>

See Label Style Attributes for a complete list of attributes that can be used in Style<Label>.

TextField

JSX Element: <textfield>

iOS Native: SCValdiTextField
Android Native: com.snap.valdi.views.ValditText

A single-line text input field.

Properties

All properties from Layout Attributes, plus:

Text Content & Styling

All text properties from Label including value, font, color, textGradient, textShadow.

Text Input Configuration

placeholder: string

The string that is displayed when there is no other text in the text field.

placeholderColor: Color

Sets the foreground color of the placeholder text.

tintColor: Color

[iOS-Only] Setting the tintColor will change the color of the editing caret and drag handles of the text field.

textAlign: 'left' | 'center' | 'right'

Set the text alignment within the typing box of the text input.
Default: 'left'

enabled: boolean

Set whether the text input is editable or not.
Default: true

Keyboard Configuration

The content type identifies what keyboard keys and capabilities are available on the input and which ones appear by default.
Default: 'default'

Setting this property changes the visible title of the Return key.
Note: This might not actually be text, e.g. on Android 10 setting this to 'search' will make the return key display a search glass icon.
Default: 'done'

autocapitalization: 'sentences' | 'words' | 'characters' | 'none'

Determines at what times the Shift key is automatically pressed, thereby making the typed character a capital letter.
Default: 'sentences'

autocorrection: 'default' | 'none'

Determines whether autocorrection is enabled or disabled during typing.
Default: 'default'

keyboardAppearance: 'default' | 'dark' | 'light'

[iOS-Only] Force keyboard appearance to dark/light (ignoring the current system appearance).

enableInlinePredictions: boolean

Whether to enable inline predictions for the text input.
Note: This is only relevant on iOS. No-op if used on Android.
Default: false

Text Editing Behavior

characterLimit: number

Determines the maximum number of characters allowed to be entered into the text field.
Note: an undefined or negative value means there is no limit.
Default: undefined

selectTextOnFocus: boolean

Whether to select the contents of the textfield when it becomes focused.
Default: false

closesWhenReturnKeyPressed: boolean

Dismiss keyboard when the return key is pressed.
Is enabled by default.
Default for textfield elements: true
Default for textview elements: false

Selection

selection: [number, number]

Selection for the text field.
First index for start of selection
Second index for end of selection
Set both to the same to select at a single position

Callbacks

onChange: (event: EditTextEvent) => void

Callback that will get called whenever the user changes the text value of the text field.
The event parameter contains the current text value of the text field.

onWillChange: (event: EditTextEvent) => EditTextEvent | undefined

Callback called when the text value is about to change.
The event parameter contains the current text value before any change.
Must return the new text value expected to replace the last text value.

onEditBegin: (event: EditTextBeginEvent) => void

Callback called when the user starts editing the textfield (i.e. when the text field becomes focused).
The event parameter contains the current text value of the text field.

onEditEnd: (event: EditTextEndEvent) => void

Callback called when the user stops editing the textfield (i.e. when the text field stops being focused).
The event parameter contains the current text value and the reason for ending.

onReturn: (event: EditTextEvent) => void

Callback called when the user taps the return key.
The event parameter contains the current text value of the text field.

onWillDelete: (event: EditTextEvent) => void

Callback called when the user presses the delete key on the keyboard.
The event parameter contains the current text value before characters are deleted.
Note: on android some soft-keyboard may only send this when pressing delete on an empty textfield.

onSelectionChange: (event: EditTextEvent) => void

Callback called when the selection is changed.
The event parameter contains the current text value and the selected indexes.

Interactive Properties (Programmatic Only)

focused: boolean

Can be programmatically set to change the current focus state of the textfield.
Changing this to true will make this textfield become the currently edited one.
Example:
- On iOS this will make the view request/resign the first responder
- On Android this will make the view become focused/unfocused and open/close the keyboard

View Properties

All view properties from View.

Styling

style: IStyle<TextField | View | Layout>

See TextField Style Attributes for a complete list of attributes that can be used in Style<TextField>.

TextView

JSX Element: <textview>

iOS Native: SCValdiTextView
Android Native: com.snap.valdi.views.ValditTextMultiline

A multi-line text input field.

Properties

All properties from TextField, except returnKeyText is replaced with returnType, plus:

Return Key Configuration

Setting this property changes the visible title of the Return key.
Setting this property will also impact the behavior of the return key.
linereturn will let users add line returns, but any other value will be constrained to single line text.
Consider using this attribute in combination with closesWhenReturnKeyPressed.
Default: 'linereturn'

Text Gravity

textGravity: 'top' | 'center' | 'bottom'

Set the text gravity/alignment vertically within the text view.
Default: 'center'

Background Effect

backgroundEffectColor: Color

Set the color for the background effect of the text view.
This background is drawn behind each line fragment of the text, wrapping each line together making a cohesive background that follows the text shape.
Default: clear

backgroundEffectBorderRadius: number

Set the background effect border radius.
Default: 0

backgroundEffectPadding: number

Set the background effect padding.
This padding is applied only around the exterior edge of the text as a whole (it does not apply to the space between lines of text).
Default: 0

Interactive Properties (Programmatic Only)

focused: boolean

Can be programmatically set to change the current focus state of the textview.

Styling

style: IStyle<TextView | View | Layout>

See TextView Style Attributes for a complete list of attributes that can be used in Style<TextView>.

BlurView

JSX Element: <blur>

iOS Native: SCValdiBlurView
Android Native: com.snap.valdi.views.ValdiView

A view that applies a blur effect to content behind it.

Properties

All properties from Layout Attributes and View Attributes (appearance and gestures), plus:

Blur Configuration

blurStyle: BlurStyle

The style of blur effect to apply.
Possible values:
- 'light'
- 'dark'
- 'extraLight'
- 'regular'
- 'prominent'
- 'systemUltraThinMaterial'
- 'systemThinMaterial'
- 'systemMaterial'
- 'systemThickMaterial'
- 'systemChromeMaterial'
- 'systemUltraThinMaterialLight'
- 'systemThinMaterialLight'
- 'systemMaterialLight'
- 'systemThickMaterialLight'
- 'systemChromeMaterialLight'
- 'systemUltraThinMaterialDark'
- 'systemThinMaterialDark'
- 'systemMaterialDark'
- 'systemThickMaterialDark'
- 'systemChromeMaterialDark'

Container Properties

BlurView extends ContainerTemplateElement, so it can have children.

Styling

style: IStyle<BlurView | View | Layout>

See BlurView Style Attributes for a complete list of attributes that can be used in Style<BlurView>.

SpinnerView

JSX Element: <spinner>

iOS Native: SCValdiSpinnerView
Android Native: com.snap.valdi.views.ValdiSpinnerView

A view that displays a loading spinner.

Properties

All properties from Layout Attributes and View, plus:

Spinner Configuration

color: Color

Color of the spinning shape.

Styling

style: IStyle<SpinnerView | View | Layout>

See SpinnerView Style Attributes for a complete list of attributes that can be used in Style<SpinnerView>.

ShapeView

JSX Element: <shape>

iOS Native: SCValdiShapeView
Android Native: com.snap.valdi.views.ShapeView

A view for drawing custom shapes using geometric paths.

Properties

All properties from Layout Attributes and View, plus:

Shape Configuration

path: GeometricPath

The GeometricPath object representing the path to draw.

Stroke Properties

strokeWidth: number

Defines the thickness of the shape's stroked path.

strokeColor: Color

The color that the stroked path is drawn with.

strokeCap: 'butt' | 'round' | 'square'

The stroke cap specifies the shape of the endpoints of an open path when stroked.

strokeJoin: 'bevel' | 'miter' | 'round'

The stroke join specifies the shape of the joints between connected segments of a stroked path.

strokeStart: number

The relative location at which to begin stroking the path.
Default value is 0. Animatable.

strokeEnd: number

The relative location at which to stop stroking the path.
Default value is 1. Animatable.

Fill Properties

fillColor: Color

The color that the shape's enclosed area is filled with.

Styling

style: IStyle<ShapeView | View | Layout>

See ShapeView Style Attributes for a complete list of attributes that can be used in Style<ShapeView>.

AnimatedImage

JSX Element: <animatedimage>

iOS Native: SCValdiAnimatedContentView
Android Native: com.snap.valdi.views.AnimatedImageView

A view for displaying animated images including Lottie animations, animated WebP, and other formats.

Properties

All properties from Layout Attributes and View, plus:

Image Source

src: string | Asset

Specify the image asset or url to be rendered within the view's bounds.
Default: undefined (nothing rendered by default)

Animation Control

loop: boolean

Specify whether the image animation should loop back to the beginning when reaching the end.

advanceRate: number

Sets the speed ratio at which the image animation should run.
0 is paused
1 means the animation runs at normal speed
0.5 at half speed
-1 the animation will run in reverse
Default: 0

currentTime: number

Set the current time in seconds for the image animation as an offset from animationStartTime.

animationStartTime: number

Set the start time in seconds for the image animation.
Animation will be clamped between start and end time.
Default: 0

animationEndTime: number

Set the end time in seconds for the image animation.
Animation will be clamped between start and end time.
Default: animation duration

Display Configuration

objectFit: 'fill' | 'contain' | 'cover' | 'none'

Define how the animatedimage should be resized within the view's bounds.
Note that the default is different from the image element.
fill: stretch the image to fill the view's bounds
contain: conserve aspect ratio and scale to fit within bounds (can leave blank space)
cover: conserve aspect ratio and scale to fill bounds (can crop parts)
none: conserve aspect ratio and don't scale to fit (just rendered in center)
Default: 'contain'

Font Provider

fontProvider: IFontProvider

Set a font provider that the lottie element will use to resolve fonts within its scenes.

Callbacks

onAssetLoad: (success: boolean, errorMessage?: string) => void

Called when the loaded animatedimage asset has either successfully loaded or failed to load.

onImageDecoded: (width: number, height: number) => void

Called when the animatedimage has been loaded and we have the dimensions.
Note: dimensions returned are of the raw image which may be different than the view.

onProgress: (event: AnimatedImageOnProgressEvent) => void

Called when the animation progresses.
Event contains:
- time: number (current time in seconds)
- duration: number (duration of the animation in seconds)

Styling

style: IStyle<AnimatedImage | View | Layout>

See AnimatedImage Style Attributes for a complete list of attributes that can be used in Style<AnimatedImage>.

Slot

JSX Element: <slot>

Slots are used for content projection, allowing a component to define placeholders that can be filled with content.

Properties

key: string

A key to uniquely identify the element.
If not provided, the framework will generate one based on the index.

name: string

The unique name of the Slot.
If not provided, it would be considered to be named 'default'.

ref: IRenderedElementHolder<unknown>

Sets an element reference holder, which will keep track of the elements rendered at the root of this slot.

Common Types

EditTextEvent

Interface for text editing events.

interface EditTextEvent {
  text: string;
  selectionStart: number;
  selectionEnd: number;
}

EditTextBeginEvent

Extends EditTextEvent with no additional properties.

EditTextEndEvent

interface EditTextEndEvent extends EditTextEvent {
  reason: EditTextUnfocusReason;
}

EditTextUnfocusReason

enum EditTextUnfocusReason {
  Unknown = 0,
  ReturnKeyPress = 1,
  DismissKeyPress = 2,
}

MeasureMode

enum MeasureMode {
  Unspecified = 0,
  Exactly = 1,
  AtMost = 2,
}

MeasuredSize

type MeasuredSize = [number, number];

OnMeasureFunc

type OnMeasureFunc = (
  width: number,
  widthMode: MeasureMode,
  height: number,
  heightMode: MeasureMode,
) => MeasuredSize;

CSSValue

type CSSValue = string | number;

Color

type Color = string;

LabelValue

type LabelValue = string | AttributedText;

Gesture Types

GestureHandler

type GestureHandler<Event> = (event: Event) => void;

GesturePredicate

type GesturePredicate<Event> = (event: Event) => boolean;

Callback Types

ImageOnAssetLoadCallback

type ImageOnAssetLoadCallback = (success: boolean, errorMessage?: string) => void;

ImageOnImageDecodedCallback

type ImageOnImageDecodedCallback = (width: number, height: number) => void;

AnimatedImageOnProgressCallback

type AnimatedImageOnProgressCallback = (event: AnimatedImageOnProgressEvent) => void;

Layout Enums

LayoutAccessibilityCategory

type LayoutAccessibilityCategory =
  | 'auto'
  | 'view'
  | 'text'
  | 'button'
  | 'image'
  | 'image-button'
  | 'input'
  | 'header'
  | 'link'
  | 'checkbox'
  | 'radio'
  | 'keyboard-key';

LayoutAccessibilityNavigation

type LayoutAccessibilityNavigation = 
  | 'auto' 
  | 'passthrough' 
  | 'leaf' 
  | 'cover' 
  | 'group' 
  | 'ignored';

Label Enums

type LabelTextDecoration = 'none' | 'strikethrough' | 'underline';
type LabelTextAlign = 'left' | 'right' | 'center' | 'justified';
type LabelFontWeight = 'light' | 'normal' | 'medium' | 'demi-bold' | 'bold' | 'black';
type LabelFontStyle = 'normal' | 'italic';

Image Enums

type ImageObjectFit = 'fill' | 'contain' | 'cover' | 'none';

TextField Enums

type TextFieldAutocapitalization = 'sentences' | 'words' | 'characters' | 'none';
type TextFieldAutocorrection = 'default' | 'none';
type TextFieldTextAlign = 'left' | 'center' | 'right';
type TextFieldReturnKeyText = 'done' | 'go' | 'join' | 'next' | 'search' | 'send' | 'continue';
type TextFieldKeyboardAppearance = 'default' | 'dark' | 'light';
type TextFieldContentType =
  | 'default'
  | 'phoneNumber'
  | 'email'
  | 'password'
  | 'url'
  | 'number'
  | 'numberDecimal'
  | 'numberDecimalSigned'
  | 'passwordNumber'
  | 'passwordVisible'
  | 'noSuggestions';

TextView Enums

type TextViewReturnType = 'linereturn' | TextFieldReturnKeyText;
type TextViewTextGravity = 'top' | 'center' | 'bottom';

Shape Enums

type ShapeStrokeCap = 'butt' | 'round' | 'square';
type ShapeStrokeJoin = 'bevel' | 'miter' | 'round';

BlurStyle

type BlurStyle =
  | 'light'
  | 'dark'
  | 'extraLight'
  | 'regular'
  | 'prominent'
  | 'systemUltraThinMaterial'
  | 'systemThinMaterial'
  | 'systemMaterial'
  | 'systemThickMaterial'
  | 'systemChromeMaterial'
  | 'systemUltraThinMaterialLight'
  | 'systemThinMaterialLight'
  | 'systemMaterialLight'
  | 'systemThickMaterialLight'
  | 'systemChromeMaterialLight'
  | 'systemUltraThinMaterialDark'
  | 'systemThinMaterialDark'
  | 'systemMaterialDark'
  | 'systemThickMaterialDark'
  | 'systemChromeMaterialDark';

Usage Examples

Basic Layout

<layout width="100%" height={200} padding={10} flexDirection="row">
  <view backgroundColor="red" flex={1} margin={5} />
  <view backgroundColor="blue" flex={1} margin={5} />
</layout>

ScrollView with Images

<scroll height={300} width="100%" horizontal={false}>
  <layout padding={10}>
    <image src={res.myImage} width={200} height={200} margin={10} />
    <label value="My Image" textAlign="center" />
  </layout>
</scroll>

TextField with Callbacks

<textfield
  value={this.state.text}
  placeholder="Enter your name"
  placeholderColor="#888"
  contentType="default"
  returnKeyText="done"
  onChange={(event) => {
    this.setState({ text: event.text });
  }}
  onEditEnd={(event) => {
    console.log('Editing ended:', event.text);
  }}
/>

Shape Drawing

<shape
  path={myGeometricPath}
  strokeWidth={2}
  strokeColor="blue"
  fillColor="lightblue"
  strokeCap="round"
  strokeJoin="round"
  width={100}
  height={100}
/>

AnimatedImage (Lottie)

<animatedimage
  src={res.myLottieAnimation}
  loop={true}
  advanceRate={1}
  width={200}
  height={200}
  objectFit="contain"
  onProgress={(event) => {
    console.log(`Progress: ${event.time}/${event.duration}`);
  }}
/>

FilesExpand file tree

api-reference-elements.md

Latest commit

History

api-reference-elements.md

File metadata and controls

API Reference

Table of Contents

Layout

Properties

Layout Attributes

Lifecycle Callbacks

Performance Optimization

Identity & References

Visual Properties

Size Properties

Position Properties

Spacing Properties

Flexbox Properties

Accessibility Properties

Styling

View

Properties

Lifecycle Callbacks

Appearance

Border Properties

Gesture Properties

Tap Gestures

Double Tap Gestures

Long Press Gestures

Drag Gestures

Pinch Gestures

Rotate Gestures

Touch Area Extension

Transform Properties

Mask Properties

Platform-Specific

Styling

ScrollView

Properties

Scroll Event Callbacks

Scroll Behavior

Bounce/Overscroll

Touch/Gesture Behavior

Visual Indicators

Viewport Extensions

Advanced Features

Interactive Properties (Programmatic Only)

Styling

ImageView

Properties

Image Source

Image Display

Content Transform

Filters

Callbacks

View Properties

Styling

VideoView

Properties

Video Source

Playback Control

Callbacks

View Properties

Styling

Label

Properties

Text Content

Text Styling

Text Layout

Auto-sizing

View Properties

Styling

TextField

Properties

Text Content & Styling

Text Input Configuration

Keyboard Configuration

Text Editing Behavior

Selection