A subspace is a partition of 3D space within your app where you can place 3D models, build 3D layouts, and add depth to otherwise 2D content. A subspace is rendered only when spatialization is enabled. In Home Space or on non-XR devices, any code within that subspace is ignored.

You can use subspace composables such as[`Volume`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#Volume(androidx.xr.compose.subspace.layout.SubspaceModifier,kotlin.Function1))and[`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,androidx.xr.compose.subspace.DragPolicy,androidx.xr.compose.subspace.ResizePolicy,kotlin.Function0))for placing 3D models. Some XR components such as[`Orbiter`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Orbiter(androidx.xr.compose.spatial.ContentEdge.Horizontal,androidx.compose.ui.unit.Dp,androidx.xr.compose.spatial.OrbiterOffsetType,androidx.compose.ui.Alignment.Horizontal,androidx.xr.compose.subspace.layout.SpatialShape,androidx.compose.ui.unit.Dp,kotlin.Boolean,kotlin.Function0))or[`SpatialDialog`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#SpatialDialog(kotlin.Function0,androidx.xr.compose.spatial.SpatialDialogProperties,kotlin.Function0))are standard 2D composables that can be used anywhere in your 2D UI hierarchy, but[`SubspaceComposable`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/SubspaceComposable)s must be invoked in your app's subspace. To do this, use either the`ApplicationSubspace`composable or the[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1))composable.

As the name suggests, the[`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1))composable should contain all of your app's spatialized content. The[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1))composable is ideal for nesting a partition of 3D space deeper in your app's existing UI hierarchy.

As with any other composable, you can call[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1))directly in your 2D UI hierarchy. However, it's important to be aware of the implications of where in the hierarchy you invoke[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)).

## About subspace hierarchies

The top-level subspace is the outermost subspace invoked by your app. Use the[`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1))composable for your top-level subspace, but, if you only use the Subspace composable in your app, the outermost`Subspace`composable will be your top-level subspace. By default, this top-level subspace is bounded by the recommended space for viewing an app, and it's typically where you place your app's spatial layout and[`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,androidx.xr.compose.subspace.DragPolicy,androidx.xr.compose.subspace.ResizePolicy,kotlin.Function0)). If you need to change the bounds of the top-level subspace, pass different[`VolumeConstraints`](https://developer.android.com/reference/kotlin/androidx/xr/compose/unit/VolumeConstraints)to your[`ApplicationSubspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#ApplicationSubspace(androidx.xr.compose.unit.VolumeConstraints,androidx.xr.compose.spatial.ConstraintsBehavior,kotlin.Function1)).

However, if you nest another subspace inside of a 2D UI hierarchy in a panel that's contained in the top-level subspace, that nested subspace behaves differently.

Nested subspaces have two key differences from top-level[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1)):

- They participate in the 2D layout in which they are invoked. This means that the height and width of the subspace will be constrained by the height and width of its 2D parent layout.
- They behave as children of the entity they're invoked in. This means that, if you call a[`Subspace`](https://developer.android.com/reference/kotlin/androidx/xr/compose/spatial/package-summary#Subspace(kotlin.Function1))composable nested inside of a[`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,androidx.xr.compose.subspace.DragPolicy,androidx.xr.compose.subspace.ResizePolicy,kotlin.Function0)), that subspace is a child of the[`SpatialPanel`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/package-summary#SpatialPanel(androidx.xr.compose.subspace.layout.SubspaceModifier,androidx.xr.compose.subspace.layout.SpatialShape,androidx.xr.compose.subspace.DragPolicy,androidx.xr.compose.subspace.ResizePolicy,kotlin.Function0))it's called in.

These behaviors of nested subspace enable capabilities such as:

- Moving the child with the parent entity
- Offsetting the location of the child using the offset[`SubspaceModifier`](https://developer.android.com/reference/kotlin/androidx/xr/compose/subspace/layout/SubspaceModifier)
- Presenting a 3D object that hovers above your 2D UI and matches the height and width of the appropriate space in the 2D layout

## Add a subspace to your app

The following code example shows how to add top-level and nested subspaces to your app:

<br />

```kotlin
setContent {
    // This is a top-level subspace
    ApplicationSubspace {
        SpatialPanel {
            MyComposable()
        }
    }
}https://github.com/android/snippets/blob/95aeebd507b29719a9e7d5a839f101bbbe42ea72/xr/src/main/java/com/example/xr/compose/Subspace.kt#L34-L41
```

<br />

<br />

```kotlin
@Composable
private fun MyComposable() {
    Row {
        PrimaryPane()
        SecondaryPane()
    }
}

@Composable
private fun PrimaryPane() {
    // This is a nested subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in a top-level Subspace
    Subspace {
        ObjectInAVolume(true)
    }
}https://github.com/android/snippets/blob/95aeebd507b29719a9e7d5a839f101bbbe42ea72/xr/src/main/java/com/example/xr/compose/Subspace.kt#L47-L62
```

<br />