> For the complete documentation index, see [llms.txt](https://docs.carpose.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carpose.de/components/03_360-exterior-viewer.md).

# 360° Exterior Viewer

### Overview <a href="#overview" id="overview"></a>

The `Exterior Viewer` component displays an interactive 360° view of a vehicle's exterior. It provides navigation controls for rotating the vehicle, autoplay functionality, and fullscreen viewing, allowing users to examine the exterior of a vehicle from all angles.

### Installation <a href="#installation" id="installation"></a>

The component is part of the Carpose application and requires no separate installation.

### Usage <a href="#usage" id="usage"></a>

To use the Exterior Viewer component in a standard HTML page:

```html
<div
  data-carpose-component="exterior-viewer"
  data-api-key="your-api-key"
  data-identifier="your-identifier"
  data-vehicle-id="your-car-id"
></div>
```

### Configuration Attributes <a href="#configuration-attributes" id="configuration-attributes"></a>

The component reads configuration from data attributes on the provided element:

| Attribute                | Type   | Default | Description                                                                               |
| ------------------------ | ------ | ------- | ----------------------------------------------------------------------------------------- |
| `data-carpose-component` | string | -       | Identifies the component type, must be set to "exterior-viewer"                           |
| `data-api-key`           | string | -       | API key for authentication with the Carpose backend services. Required for data fetching. |
| `data-identifier`        | string | -       | Identifier for the exterior images. Required if car-id is not provided.                   |
| `data-vehicle-id`        | string | -       | ID of the car to display exterior view for. Required if identifier is not provided.       |

### Features <a href="#features" id="features"></a>

* Interactive 360° view of vehicle exteriors
* Navigation controls for:
  * Rotating left and right
  * Autoplay with play/pause functionality
  * Fullscreen viewing (on non-mobile devices)
* Loading indicator while images are being fetched
* Fallback screen when no exterior images are available
* Overlay with usage hints
* Event notifications when viewer loads successfully or encounters errors

### Example <a href="#example" id="example"></a>

```html
<!-- Using identifier -->
<div
  data-carpose-component="exterior-viewer"
  data-api-key="your-api-key"
  data-identifier="vehicle-exterior-123"
></div>

<!-- Using car ID -->
<div
  data-carpose-component="exterior-viewer"
  data-api-key="your-api-key"
  data-vehicle-id="550e8400-e29b-41d4-a716-446655440000"
></div>
```

### Behavior <a href="#behavior" id="behavior"></a>

1. **Data Loading**:
   * On initialization, the component fetches the exterior images from the API using either the provided identifier or car ID.
   * A loading screen is displayed while the images are being loaded.
   * If no images are available, a message is displayed indicating that no 360° exterior view is available.
   * The component triggers custom events to notify parent components of successful loading or errors.
2. **Navigation Controls**:
   * Left/right arrow buttons allow rotating the vehicle view
   * Play/pause button toggles automatic rotation
   * Fullscreen button toggles fullscreen mode (not available on mobile devices)
   * Users can also navigate by dragging the view with their mouse or touch gestures
3. **Responsive Behavior**:
   * The component adapts to the container size
   * Controls are accessible on both desktop and mobile devices
   * Fullscreen option is automatically disabled on mobile devices
4. **Events**:

   * `carpose-vehicle-viewer-load`: Triggered when the viewer loads successfully. `data.viewer` is `"exterior"`.
   * `carpose-vehicle-viewer-unavailable`: Triggered when no exterior images are available, or when the media fetch fails. `data.viewer` is `"exterior"`; `data.reason` distinguishes "no media at all" (`no-media`) from "fetch failed" (`fetch-failed`). `detail.component` reports whichever widget this viewer is mounted inside (e.g. `exterior-viewer` when mounted standalone as above, or `vehicle-detail` when it's nested inside the vehicle detail view) — it no longer doubles as the failure-mode discriminator.

   See [Vehicle Search: Viewer](/events/02_vehicle-search.md#viewer) for the full event reference.