<!--
{
  "availability" : [
    "iOS: 7.0.0 -",
    "iPadOS: 7.0.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIGravityBehavior",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UIGravityBehavior"
  },
  "title" : "UIGravityBehavior"
}
-->

# UIGravityBehavior

An object that applies a gravity-like force to all of its associated dynamic items.

```
@MainActor class UIGravityBehavior
```

## Overview

The magnitude and direction of the gravity force are configurable and are applied equally to all associated items. Use this behavior to modify the position of views and other dynamic items in your app’s interface.

You specify the magnitude and direction of the gravity force as a two-dimensional vector in the reference view’s coordinate system. A value of `1.0` imparts the standard UIKit gravity, which corresponds to an acceleration of 1000 points / second² in the direction of the given axis. The default vector in the [`gravityDirection`](/documentation/UIKit/UIGravityBehavior/gravityDirection) property is (`0.0`, `1.0`), which causes items to accelerate downward along the positive y axis. If you prefer to set the vector [`angle`](/documentation/UIKit/UIGravityBehavior/angle) and [`magnitude`](/documentation/UIKit/UIGravityBehavior/magnitude) separately, you can do so using the corresponding properties.

> Note:
> If you want a gravitational force that takes the mass of each object into account, use a ``doc://com.apple.uikit/documentation/UIKit/UIFieldBehavior`` object instead. Field behaviors support both linear and radial gravitation fields and take the mass of an object into account, resulting in different amounts of force applied to each object.

If you want to influence a gravity behavior at each step of a dynamic animation, assign an appropriate block to the inherited [`action`](/documentation/UIKit/UIDynamicBehavior/action) property. Use your block to make any needed changes to the dynamic items associated with the gravity behavior.

### Applying a Gravity Behavior to an Item

To apply a gravity behavior to one or more dynamic items, do the following:

1. Initialize the behavior using the [`init(items:)`](/documentation/UIKit/UIGravityBehavior/init(items:)) method, passing in the items you want associated with the behavior. Use the [`addItem(_:)`](/documentation/UIKit/UIGravityBehavior/addItem(_:)) method to add items after initialization. For more information about dynamic items, see [`UIDynamicItem`](/documentation/UIKit/UIDynamicItem).
2. Enable the gravity behavior by adding it to your [`UIDynamicAnimator`](/documentation/UIKit/UIDynamicAnimator) object using the [`addBehavior(_:)`](/documentation/UIKit/UIDynamicAnimator/addBehavior(_:)) method. (Do not add more than one gravity behavior to an animator.)

The gravity behavior derives its coordinate system from the reference view of its associated dynamic animator object. For more information about the dynamic animator and the reference coordinate system, see [`UIDynamicAnimator`](/documentation/UIKit/UIDynamicAnimator).

## Topics

### Initializing a gravity behavior

[`-  initWithItems:`](/documentation/UIKit/UIGravityBehavior/init(items:))

Initializes a gravity behavior with an array of dynamic items.

### Managing a gravity behavior’s items

[`items`](/documentation/UIKit/UIGravityBehavior/items)

The set of dynamic items associated with the gravity behavior.

[`-  addItem:`](/documentation/UIKit/UIGravityBehavior/addItem(_:))

Associates the specified dynamic item with the gravity behavior.

[`-  removeItem:`](/documentation/UIKit/UIGravityBehavior/removeItem(_:))

Removes the specified dynamic item from the gravity behavior.

### Configuring a gravity behavior

[`gravityDirection`](/documentation/UIKit/UIGravityBehavior/gravityDirection)

The direction and magnitude of the gravitational force, expressed as a vector.

[`angle`](/documentation/UIKit/UIGravityBehavior/angle)

The direction of the gravity vector, expressed in radians in the reference coordinate system.

[`magnitude`](/documentation/UIKit/UIGravityBehavior/magnitude)

The magnitude of the gravity vector.

[`-  setAngle:magnitude:`](/documentation/UIKit/UIGravityBehavior/setAngle(_:magnitude:))

Sets the angle and magnitude of the gravity vector for the behavior.

## Relationships

### Inherits From

[`UIDynamicBehavior`](/documentation/UIKit/UIDynamicBehavior)

### Conforms To

[`Sendable`](/documentation/Swift/Sendable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Equatable`](/documentation/Swift/Equatable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`CVarArg`](/documentation/Swift/CVarArg)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

---

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)