> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/ja/maps/llms.txt)

# Viewport

A viewport typically refers to the visible area of a map or scene that is currently being displayed. Our [`ViewportManager`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/) offers an extensive high-level API for controlling a map's camera. It provides built-in states for following the location puck and showing an overview of a GeoJSON geometry. Transitions between states can be animated with one of the built-in transitions or with custom transitions.

To configure the [`ViewportManager`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/), you can update its [`options`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/options/). For example, if you want to take the safe area inset into account when calculating a viewport camera, you can set `mapview.viewport.options.usesSafeAreaInsetsAsPadding` to `true`.

### Viewport status

At any given time, a [`ViewportStatus`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportstatus/) can be either of the followings:

-   Idle (camera is not updating)
-   Running in a state (an overview viewport or a viewport that is following a location's puck)
-   Transitioning to a new state

> **Note**
> 
> Note that if you want to use other APIs to control the map's camera i.e [`MapboxMap.setCamera(to:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/mapboxmap/setcamera(to:)/), it's a good practice to make sure that the map's viewport is in an idle state.

#### Listen to viewport status's changes

You can get the current [`ViewportStatus`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportstatus/) by accessing [`ViewportManager.status`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/status/). To get notified when the viewport status changed, you can provide your own implementation of [`ViewportStatusObserver`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportstatusobserver/) and register it to the viewport manager using [`ViewportManager.addStatusObserver(_:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/addstatusobserver(_:)/)

Map's viewport manager will keep a strong reference to its status observers, therefore, when you no longer need to listen to viewport status's changes, you should unsubscribe using [`ViewportManager.removeStatusObserver(_:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/removestatusobserver(_:)/) to release this strong reference.

> **Note**
> 
> Observers are notified of status changes asynchronously on the main queue. This means that by the time the notification is delivered, the status may have already changed again. This behavior is necessary to allow observers to trigger further transitions while avoiding out-of-order delivery of status changed notifications.

### Viewport state

#### Overview Viewport

An [`OverviewViewportState`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/overviewviewportstate/) shows a map camera that overviews a region defined by a geometry.

**SwiftUI**

```swift
Map(initialViewport: .overview(
  geometry: LineString(lineCoordinates),
  geometryPadding: UIEdgeInsets(top: 40, left: 40, bottom: 40, right: 40))
)
```

**UIKit**

```swift
let routeLine = LineString(lineCoordinates)
// Defines a viewport that fits a given geometry with 40px padding from all edges.
let viewportStateOptions = OverviewViewportStateOptions(
  geometry: routeLine,
  geometryPadding: UIEdgeInsets(top: 40, left: 40, bottom: 40, right: 40)
)
// Creates an OverviewViewportState
let overviewViewportState = mapView.viewport.makeOverviewViewportState(options: viewportStateOptions)
// Sets viewport state
mapView.viewport.transition(to: overviewViewportState)
```

![](https://docs.mapbox.com/ios/ja/assets/ideal-img/maps-guides-overview-viewport.a705c46.480.png)

#### Follow Puck Viewport

A [`FollowPuckViewportState`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/followpuckviewportstate/) shows a map camera that tracks user's location.

> **Note**
> 
> Users must grant permission before an app can access information about their location. For more information about asking for the user's location, see the [User location](https://docs.mapbox.com/ios/ja/maps/guides/user-location/) guide.

**SwiftUI**

```swift
Map(initialViewport: .followPuck(zoom: 16.35, bearing: .course, pitch: 45))
```

**UIKit**

```swift
let followPuckViewportStateOptions = FollowPuckViewportStateOptions(
  bearing: .course, // Tells viewport to update its camera's bearing based on current course
  pitch: 45,
)
let followPuckViewportState = mapView.viewport.makeFollowPuckViewportState(options: followPuckViewportStateOptions)

// Sets viewport state
mapView.viewport.transition(to: overviewViewportState)
```

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/ios/ja/ios/ja/assets/medias/follow-puck-viewport-bf563fb0d4b43d9f03b0eef14f4aa39a.mp4).

## Viewport transitions

The Mapbox Maps SDK provides a way to smoothly transition between different viewport states, either with animations or none. This can enhance the user experience by providing a smooth visual transition between different map views.

The SDK provides 2 implementations of [`ViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewporttransition/): [`DefaultViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/defaultviewporttransition/) and [`ImmediateViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/immediateviewporttransition/). To transition between viewport states, you first create an instance of the transition, and pass it to [`ViewportManager.transition(to:transition:completion:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/transition(to:transition:completion:)/).

### Immediate transition

Like the name suggested, [`ImmediateViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/immediateviewporttransition/) will transition immediately to the new viewport without any animation.

**SwiftUI**

```swift
@State vart viewport = Viewport.camera()

Map(viewport: $viewport)
  .onAppear {
    viewport = .camera(zoom: 4)
  }
```

**UIKit**

```swift
let immediateTransition = mapview.viewport.makeImmediateViewportTransition()
mapview.viewport.transition(to: newViewportState, transition: immediateTransition)
```

### Default transition

[`DefaultViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/defaultviewporttransition/) transitions between viewport states using an animation that offers cubic bezier easing. This is the default behavior of `ViewportManager` when transitioning between states.

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/ios/ja/ios/ja/assets/medias/default-viewport-transition-d1498018e97f1000fa2464a2a3a78151.mp4).

You can use convenience method [`ViewportManager.makeDefaultViewportTransition(options:)`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportmanager/makedefaultviewporttransition(options:)/) to create an instance of this transition. Optionally you can set a `maxDuration` for the transition.

**SwiftUI**

```swift
@State vart viewport = Viewport.camera()

Map(viewport: $viewport)
  .onAppear {
    withViewportAnimation(.default(maxDuration: 2)) {
      viewport = .camera(zoom: 4) 
    }
  }
```

**UIKit**

```swift
let defaultTransitionOptions = DefaultViewportTransitionOptions(maxDuration: 2) // If maxDuration is not defined, default value 3.5ms will be used.
let defaultTransition = mapview.viewport.makeDefaultViewportTransition(options: defaultTransitionOptions)

mapview.viewport.transition(to: newViewportState, transition: defaultTransition)
```

> **Note: Use camera animation before map is moved to window**
> 
> Note that any usage of Camera Animator before the map view is moved to new window and the display link is created is invalid, all animators will be marked as completed immediately.

## Customize Viewport state and transition

When developing the Mapbox Maps SDK, we emphasized the flexibility for developers to customize our maps, enabling you to achieve precisely tailored functionalities for your application. You can provide a custom implementation for [`ViewportState`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewportstate/) and [`ViewportTransition`](https://docs.mapbox.com/ios/maps/api/latest/documentation/mapboxmaps/viewporttransition/) to handle advanced use cases not covered by the provided implementations.

> **Note: Pre-warm viewport state's data source**
> 
> To decrease delays when becoming current, states should generally pre-warm their data sources as soon as they are created. Keep alive only the states that are currently (or soon-to-be) needed to release unneeded resources, such as location services.