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

# HoverEffectComponent

A component that applies a visual effect to a hierarchy of entities when a person looks at or selects an entity.

```
struct HoverEffectComponent
```

## Overview

Add a HoverEffectComponent to an entity to convey the entity can receive gestures or to separate parts that can be interacted with independently.

> Note: On visionOS, you hover over an entity by looking at or directly touching it. On other platforms, you hover over an entity by moving your mouse cursor over it.

> Important: Entities also need to have an ``doc://com.apple.RealityKit/documentation/RealityKit/InputTargetComponent`` and ``doc://com.apple.RealityKit/documentation/RealityKit/CollisionComponent`` to receive hover effects.

```swift
let boxSize = SIMD3<Float>(0.5, 0.1, 0.05)

let modelComponent = ModelComponent(
    mesh: MeshResource.generateBox(size: boxSize),
    materials: [SimpleMaterial(color: .black, roughness: 0.5, isMetallic: false)]
)
let collisionComponent = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: boxSize)]
)
let inputTargetComponent = InputTargetComponent()
let hoverEffectComponent = HoverEffectComponent()

let entityA = Entity()
entityA.components.set([modelComponent, collisionComponent, inputTargetComponent, hoverEffectComponent])
```

The example code above produces the following scene.

![A video of a living room scene with 1 3D black rectangle in the center of it. The rectangle starts glowing with a feathered effect that moves around slowly.](videos/com.apple.RealityKit/hovereffectcomponent-scene-default-effect-1.mp4)

### Hierarchical behavior

The `HoverEffectComponent` applies its effect to an entity’s entire hierarchy, which means that all the entity’s descendent entities inherit the effect when a person looks at (or selects) an entity.

```swift
let boxSize = SIMD3<Float>(0.5, 0.1, 0.05)

// Create a black box model, a matching collision component, and an input target component.
let modelComponent = ModelComponent(
    mesh: MeshResource.generateBox(size: boxSize),
    materials: [SimpleMaterial(color: .black, roughness: 0.5, isMetallic: false)]
)
let collisionComponent = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: boxSize)]
)
let inputTargetComponent = InputTargetComponent()

// Create a default hover effect component.
let hoverEffectComponent = HoverEffectComponent()

let entityA = Entity()
entityA.components.set([modelComponent, collisionComponent, inputTargetComponent])

let entityB = entityA.clone(recursive: true)
let entityC = entityB.clone(recursive: true)

// B is a child of A.
entityA.addChild(entityB)
// C is a child of B.
entityB.addChild(entityC)

// Place B above its parent, A.
entityB.position.y = 0.1
// Place C above its parent, B.
entityC.position.y = 0.1

entityA.components.set(hoverEffectComponent)
```

In this example only the highest entity in the hierarchy has a `HoverEffectComponent`. Activating this hover effect causes all of its children to display the same effect.

![A video of a living room scene with three black rectangles arranged in a column. All three of the rectangles start glowing with a feathered effect that moves around slowly.](videos/com.apple.RealityKit/hovereffectcomponent-scene-default-effect-3.mp4)

### Grouping multiple hover effects

The optional [`groupID`](/documentation/RealityKit/HoverEffectComponent/HoverEffect-swift.struct/groupID) connects entities so that they activate their hover effects together, which is independent from the entities’ hierarchy.
When someone hovers over any entity in the group, all entities with the same [`HoverEffectComponent.GroupID`](/documentation/RealityKit/HoverEffectComponent/GroupID) instance start their hover effects together.

```swift
let boxSize = SIMD3<Float>(0.5, 0.1, 0.05)
let modelComponent = ModelComponent(
    mesh: MeshResource.generateBox(size: boxSize, cornerRadius: 0.2),
    materials: [SimpleMaterial(color: .black, roughness: 0.5, isMetallic: false)]
)
let collisionComponent = CollisionComponent(
    shapes: [ShapeResource.generateBox(size: boxSize)]
)
let inputTargetComponent = InputTargetComponent()

let hoverEntityA = Entity(components:
    modelComponent, collisionComponent, inputTargetComponent
)
let hoverEntityB = hoverEntityA.clone(recursive: true)
hoverEntityB.position.y = -0.1
let hoverEntityC = hoverEntityA.clone(recursive: true)
hoverEntityC.position.y = -0.2

content.add(hoverEntityA)
content.add(hoverEntityB)
content.add(hoverEntityC)

// Create hover effect components for the two topmost entities in the scene.
var hoverA = HoverEffectComponent(
    .highlight(HoverEffectComponent.HighlightHoverEffectStyle(
            color: .green, strength: 2.0
        )))

var hoverB = HoverEffectComponent(
    .highlight(HoverEffectComponent.HighlightHoverEffectStyle(
            color: .yellow, strength: 2.0
        )))

// Create a `HoverEffectComponent.GroupID` instance and assign it to the hover effect components for both `entityA` and `entityB`.
let topGroupID = HoverEffectComponent.GroupID()
hoverA.hoverEffect.groupID = topGroupID
hoverB.hoverEffect.groupID = topGroupID
hoverEntityA.components.set(hoverA)
hoverEntityB.components.set(hoverB)

// Create hover effect component for the bottommost entity in the scnee.
var hoverC = HoverEffectComponent(
    .highlight(HoverEffectComponent.HighlightHoverEffectStyle(
            color: .blue, strength: 2.0
        )))

// Create a `HoverEffectComponent.GroupID` instance and assign it to the hover effect component for `entityC`
let bottomGroupID = HoverEffectComponent.GroupID()
hoverC.hoverEffect.groupID = bottomGroupID
hoverEntityC.components.set(hoverC)
```

In this example, the top and middle entities, `entityA` and `entityB`, have a [`HoverEffectComponent`](/documentation/RealityKit/HoverEffectComponent) with the same group identifier.
However, the bottom entity, `entityC`, has a different group ID.
The top amd middle entity both glow when a person activates either one.
The bottom entity glows separately and only when someone activates it directly.

![A video of a living room scene with three black rectangles arranged in a column. The top two rectangles start glowing as the gaze pointer hovers over the top rectangle and as it continues over the middle rectange. The bottom rectangle begins glowing only when the gaze pointer hovers over it.](videos/com.apple.RealityKit/hovereffectcomponent-groupid.mp4)

### Styles

You can customize the visual effect of the `HoverEffectComponent` through the use of styles.

The [`HoverEffectComponent.SpotlightHoverEffectStyle`](/documentation/RealityKit/HoverEffectComponent/SpotlightHoverEffectStyle) represents a feathered effect that follows the hover location on the entity. This is the default effect RealityKit uses if you create a `HoverEffectComponent` with the default initializer, [`init()`](/documentation/RealityKit/HoverEffectComponent/init()). You can customize the color and strength of this effect by passing values into the [`HoverEffectComponent.SpotlightHoverEffectStyle`](/documentation/RealityKit/HoverEffectComponent/SpotlightHoverEffectStyle) constructor.

```swift
let hoverComponent = HoverEffectComponent(.spotlight(
    HoverEffectComponent.SpotlightHoverEffectStyle(
        color: .green, strength: 2.0
    )
))
```

![A screen recording of a living room with a black rectangle in the center of it. The rectangle begins to glow with a faint green feathered effect that moves around slowly.](videos/com.apple.RealityKit/hovereffectcomponent-spotlight~dark.mp4)

The [`HoverEffectComponent.HighlightHoverEffectStyle`](/documentation/RealityKit/HoverEffectComponent/HighlightHoverEffectStyle) applies a uniform glow to the entity
in addition to the feathered effect from the [`HoverEffectComponent.SpotlightHoverEffectStyle`](/documentation/RealityKit/HoverEffectComponent/SpotlightHoverEffectStyle).
You can customize the color and strength of this effect by passing values into the
[`HoverEffectComponent.HighlightHoverEffectStyle`](/documentation/RealityKit/HoverEffectComponent/HighlightHoverEffectStyle) constructor.

```swift
let hoverComponent = HoverEffectComponent(.highlight(
    HoverEffectComponent.HighlightHoverEffectStyle(
        color: .green, strength: 2.0
    )
))
```

![A screen recording of a living room with a black rectangle in the center of it. The rectangle begins to glow with a bright green feathered effect.](videos/com.apple.RealityKit/hovereffectcomponent-highlight~dark.mp4)

### Opacity functions

Customize how a `HoverEffectComponent` presents on a partially or fully transparent material with the following opacity functions:

- [`HoverEffectComponent.OpacityFunction.full`](/documentation/RealityKit/HoverEffectComponent/OpacityFunction/full): An opacity function that causes the effect to draw at full opacity regardless of opacity of the base material. This is the default opacity function.
- [`HoverEffectComponent.OpacityFunction.mask`](/documentation/RealityKit/HoverEffectComponent/OpacityFunction/mask): An opacity function that draws the hover effect at full opacity when the entity’s base material opacity is greater than `0.05`, and fades out the hover effect with the entity’s base material when its opacity is equal to or less than `0.05`.
- [`HoverEffectComponent.OpacityFunction.blend`](/documentation/RealityKit/HoverEffectComponent/OpacityFunction/blend): An opacity function that draws the hover effect with an opacity that’s equal to the product of the entity’s base material and the shader’s output.

`.full`

![A screen recording of a living room with a partially transparent green rectangle in the center of it. The green rectangle fades in to full opacity and becomes darker before fading out again and becoming partially transparent.](videos/com.apple.RealityKit/hovereffectcomponent-opacityfunction-full~dark.mp4)

`.mask`

![A screen recording of an empty living room. After a short delay a partially transparent green rectangle appears in the middle of the living room. The rectangle slowly fades in to become fully opaque before it fades out to be partially transparent and then disappears entirely.](videos/com.apple.RealityKit/hovereffectcomponent-opacityfunction-mask~dark.mp4)

`.blend`

![A screen recording of an empty living room. After a short delay a green rectangle slowly fades in and then fades back out.](videos/com.apple.RealityKit/hovereffectcomponent-opacityfunction-blend.mp4)

> Note: Opacity functions can’t be applied to `HoverEffectComponents` that use ``doc://com.apple.RealityKit/documentation/RealityKit/HoverEffectComponent/ShaderHoverEffectInputs``.

### Shader inputs

Pass [`HoverEffectComponent.ShaderHoverEffectInputs`](/documentation/RealityKit/HoverEffectComponent/ShaderHoverEffectInputs) to the `HoverEffectComponent`
constructor with [`shader(_:)`](/documentation/RealityKit/HoverEffectComponent/HoverEffect-swift.struct/shader(_:))
to activate the `Hover State` Shader Graph node in a [`ShaderGraphMaterial`](/documentation/RealityKit/ShaderGraphMaterial).
Apply the [`ShaderGraphMaterial`](/documentation/RealityKit/ShaderGraphMaterial) to the entity’s [`ModelComponent`](/documentation/RealityKit/ModelComponent) when using this effect.

```swift
let boxSize = SIMD3<Float>(0.5, 0.1, 0.05)

let customMaterial = try! await ShaderGraphMaterial(
   named: "/Root/HoverEffectComponentDemo",
   from: Bundle.main.url(forResource: "DemoScene", withExtension: "usda")!
)

let entity = ModelEntity(
    mesh: MeshResource.generateBox(size: boxSize),
    materials: [customMaterial]
)

// ...

let hoverComponent = HoverEffectComponent(.shader(
    HoverEffectComponent.ShaderHoverEffectInputs(
        fadeInDuration: 1.0, fadeOutDuration: 1.0
    )
))
entity.components.set(hoverComponent)
```

This shader graph represents a red and blue effect that interpolates between each color using a sine wave.

![A screenshot of an app window with a shader graph visible. The shader graph represents a red and blue effect that interpolates between each color using a sine wave. On the bottom right is a purple cube representing the effect halfway between red and blue.](images/com.apple.RealityKit/hovereffectcomponent-shader-graph.jpg)

Hovering over the entity displays the following effect.

![A screen recording of a living room with a single black rectangle in the middle of the room. The rectangle fades to a red color and back to black several times, and then stops at black.](videos/com.apple.RealityKit/hovereffectcomponent-shader~dark.mp4)

---

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)