<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 11.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "SwiftUI",
  "identifier" : "/documentation/SwiftUI/SpatialEventGesture",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "SwiftUI"
    ],
    "preciseIdentifier" : "s:7SwiftUI19SpatialEventGestureV"
  },
  "title" : "SpatialEventGesture"
}
-->

# SpatialEventGesture

A gesture that provides information about ongoing spatial events like
clicks and touches.

```
nonisolated struct SpatialEventGesture
```

## Overview

Use a gesture of this type to track multiple simultaneous spatial events
and gain access to detailed information about each. For example, you can
place a particle emitter at every location in a [`Canvas`](/documentation/SwiftUI/Canvas) that has an
ongoing spatial event:

```
struct ParticlePlayground: View {
    @State var model = ParticlesModel()

    var body: some View {
        Canvas { context, size in
            for particle in model.particles {
                context.fill(Path(ellipseIn: particle.frame),
                             with: .color(particle.color))
            }
        }
        .gesture(
            SpatialEventGesture()
                .onChanged { events in
                    for event in events {
                        if event.phase == .active {
                            // Update particle emitters.
                            model.emitters[event.id] = ParticlesModel.Emitter(
                                location: event.location
                            )
                        } else {
                            // Remove emitters when no longer active.
                            model.emitters[event.id] = nil
                        }
                    }
                }
                .onEnded { events in
                    for event in events {
                        // Remove emitters when no longer active.
                        model.emitters[event.id] = nil
                    }
                }
        )
    }
}
```

The gesture provides a [`SpatialEventCollection`](/documentation/SwiftUI/SpatialEventCollection) structure when it detects
changes. The collection contains [`SpatialEventCollection.Event`](/documentation/SwiftUI/SpatialEventCollection/Event) values
that represent ongoing spatial events. Each event contains a stable, unique
identifier so that you can track how the event changes over time. The event
also indicates its current location, a timestamp, the pose of the
input device that creates it, and other useful information.

The phase of events in the collection can change
to [`SpatialEventCollection.Event.Phase.ended`](/documentation/SwiftUI/SpatialEventCollection/Event/Phase-swift.enum/ended) or
[`SpatialEventCollection.Event.Phase.cancelled`](/documentation/SwiftUI/SpatialEventCollection/Event/Phase-swift.enum/cancelled) while the gesture itself
remains active. Individually track state for each event inside
[`onChanged(_:)`](/documentation/SwiftUI/Gesture/onChanged(_:)) or [`updating(_:body:)`](/documentation/SwiftUI/Gesture/updating(_:body:)) and clean up all
state in [`onEnded(_:)`](/documentation/SwiftUI/Gesture/onEnded(_:)).

> Tip: Only use a spatial event gesture if you need to access low-level
> event information, like when you create a complex multi-touch experience.
> For most use cases, it’s better to rely on gestures that recognize
> targeted interactions, like a ``doc://com.apple.SwiftUI/documentation/SwiftUI/SpatialTapGesture``, ``doc://com.apple.SwiftUI/documentation/SwiftUI/MagnifyGesture``,
> or ``doc://com.apple.SwiftUI/documentation/SwiftUI/DragGesture``.

## Topics

### Creating a spatial event gesture

[`init(coordinateSpace:)`](/documentation/SwiftUI/SpatialEventGesture/init(coordinateSpace:))

Creates the gesture with a desired coordinate space.

[`init(coordinateSpace3D:)`](/documentation/SwiftUI/SpatialEventGesture/init(coordinateSpace3D:))

Creates the gesture with a desired coordinate space 3D.

### Getting gesture properties

[`coordinateSpace`](/documentation/SwiftUI/SpatialEventGesture/coordinateSpace)

The coordinate space of the gesture.

## Relationships

### Conforms To

[`Gesture`](/documentation/SwiftUI/Gesture)

---

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)