<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/ReferenceComponent",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation18ReferenceComponentV"
  },
  "title" : "ReferenceComponent"
}
-->

# ReferenceComponent

A component that can load another entity from a file.

```
struct ReferenceComponent
```

## Overview

You can use a `ReferenceComponent` to load other entities from files in your app’s main bundle.
This allows you to load complex scenes incrementally, resulting in more responsive apps.
It also enables collaborative workflows so you can split a complex scene into separate pieces that
different teams own.

Use a `ReferenceComponent` by adding it to an entity when building up a scene programmatically.
Then call [`write(to:)`](/documentation/RealityKit/Entity/write(to:)) to save the scene to a `.reality` file.

```swift
// Create the root entity.
let root = Entity()

// Create an entity that references another entity file.
let earth = Entity()
earth.setParent(root)

// Add a reference to another entity that loads immediately
// when the root entity loads.
earth.components.set(ReferenceComponent(
    named: "Earth",
    loadingPolicy: .immediate))

// Add a reference to another entity that loads on demand.
let mars = Entity()
mars.name = "mars"
mars.components.set(ReferenceComponent(
    named: "Mars",
    loadingPolicy: .onDemand))

// Write the root entity to a `.reality` file.
try await root.write(to: fileURL)
```

When your app loads the `.reality` file, it can dynamically load referenced entities from files.
For references that have a [`ReferenceComponent.LoadingPolicy`](/documentation/RealityKit/ReferenceComponent/LoadingPolicy-swift.enum) of
[`ReferenceComponent.LoadingPolicy.onDemand`](/documentation/RealityKit/ReferenceComponent/LoadingPolicy-swift.enum/onDemand), you can use
[`loadReference(at:)`](/documentation/RealityKit/ReferenceComponent/loadReference(at:)-1en8b) to load content on demand.

```swift
if let entity = root.findEntity(named: "mars") {
    try ReferenceComponent.loadReference(at: entity)
}
```

Conversely, use [`releaseReference(at:)`](/documentation/RealityKit/ReferenceComponent/releaseReference(at:)) to unload content
and free up memory.

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)