Understand subspace modifiers

Applicable XR devices

This guidance helps you build experiences for these types of XR devices.

Learn about XR device types →

Learn about XR device types →

A SubspaceModifier is similar to a Compose modifier for composables in a Subspace. A SubspaceModifier lets you manipulate composables in 3D space, helping you position, rotate, and add behaviors to 3D layout nodes.

Layout

By default, a Subspace is bounded by the recommended space for viewing an app. These bounds are used when measuring the layout of your subspace components, similar to bounds in 2D Compose layouts.

Fill bounds

The modifiers fillMaxSize, fillMaxWidth, fillMaxHeight, and fillMaxDepth make content (partially) fill the bounds of its parent. Using fill modifiers helps your app layout content that's independent of the XR device's display characteristics.

Set the size and required size

The modifiers size, width, height, and depth declare the preferred size of the content. To declare the exact size of the content, use requiredSize, requiredWidth, requiredHeight, and requiredDepth. These units must be specified in dp; to convert from meters to dp, use Meter.toDp().

Position composables

offset

The offset modifier moves the composable in 3D space along the x, y, and z axes. These units must be specified in dp; to convert from meters to dp, use Meter.toDp().

rotate

The rotate modifier rotates the given composable in space. You can specify the direction and the amount of rotation in different ways:

• Using pitch, yaw, and roll, which specify the rotation around the x, y, and z axes respectively,
• Using an axisAngle, which is a Vector3 representing the axis of rotation, and the amount of degrees it should be rotated around,
• Using a Quaternion that represents the rotation.

rotateToLookAtUser

The rotateToLookAtUser modifier continuously rotates content so that it faces the user at all times. You can also use this modifier to achieve a "billboard" effect where the content rotates to face the user on the Y-axis while still remaining upright and aligned with gravity. To do this, combine the rotateToLookAtUser modifier with the gravityAligned modifier.

Move and Resize with composables

Let users directly manipulate the position and size of objects in 3D space. You can add these modifiers to individual components (like SpatialPanel), subspaces, and spatial layout components (like SpatialRow or SpatialColumn).

Move elements

Movable modifiers let users grab and reposition subspace elements.

• transformingMovable: Use this modifier for standard movement. This modifier configures the element to be interactive and movable by the user. The system automatically calculates and applies the new pose and scale based on user input.

• movable: Use this modifier to define custom movement behavior. While the system supplies the move affordance, you must use the required onMove event and apply the result. This is useful for restricting movement or creating custom movement in your app.

Resize elements

Resizable modifiers let users grab and resize subspace elements.

• transformingResizable: Use this modifier for system-managed resizing. This modifier automatically handles the resize gesture and applies the new dimensions that the user specifies.

• resizable: Use this modifier for custom resizing logic. While the system provides the resize affordance, you must use the onResize event and apply the result. This modifier is useful for complex scenarios, such as maintaining a specific aspect ratio or readjusting the overall layout of other components after a resize ends.

Change the appearance of composables

alpha

The alpha modifier sets the opacity of the element and its children, where 0f represents fully transparent and 1.0f represents completely opaque.

scale

The scale modifier scales the contents of the composible along the horizontal, vertical, and depth axes.

Testing and accessibility

semantics

The semantics modifier adds semantics to the layout node, for use in testing and accessibility. See Semantics in Jetpack Compose and SemanticsModifier.

testTag

The testTag modifier is a shorthand for SemanticsPropertyReceiver.testTag, which allows test frameworks to find the element in tests.