<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "StateReporting",
  "identifier" : "/documentation/StateReporting/StateReporter/reportTransition(to:stableMetadata:volatileMetadata:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "StateReporting"
    ],
    "preciseIdentifier" : "s:14StateReporting0A8ReporterC16reportTransition2to14stableMetadata08volatileH0ySSSg_xSgq_SgtF"
  },
  "title" : "reportTransition(to:stableMetadata:volatileMetadata:)"
}
-->

# reportTransition(to:stableMetadata:volatileMetadata:)

Reports a transition to a new state.

```
final func reportTransition(to stateLabel: String?, stableMetadata: StableMetadata? = nil, volatileMetadata: VolatileMetadata? = nil)
```

## Parameters

`stateLabel`

A descriptive label for the new state, which must not be empty, or `nil` to clear the active state.

`stableMetadata`

An optional value that identifies the state together with `stateLabel`.

`volatileMetadata`

An optional value providing context likely to change within this state.

## Discussion

A transition occurs only when `stateLabel` or `stableMetadata` changes from the current
state. If both are equal to the current values, this call is a no-op. Pass `nil` for
`stateLabel` to indicate that no state is currently active, clearing any previously
reported state. Passing an empty string for `stateLabel` is a fatal error. Any volatile
metadata from the previous state is discarded when a new transition begins. Calling this
method more frequently than user interaction timescales can trigger rate limiting,
causing state updates to go unlogged.

---

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)