Studiometa Vue Mapbox GL

https://github.com/studiometa/vue-mapbox-gl
Admin
A small components library to integrate Mapbox GL into Vue 3 applications, offering components for...
Tokens:16,557
Snippets:55
Trust Score:9.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Setup @studiometa/vue-mapbox-gl

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/README.md

This snippet shows how to clone the repository, navigate into the directory, and install project dependencies using npm. It's the standard setup for contributing to or using the library.

```bash
git clone git@github.com:studiometa/vue-mapbox-gl.git
cd vue-mapbox-gl
npm i
```

--------------------------------

### StoreLocator Component Example

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Shows a detailed example of using the StoreLocator component with custom props, slots, and data binding.

```APIDOC
## StoreLocator Component Example

### Description
This example demonstrates how to use the `StoreLocator` component to display data from `earthquake.json` on a map with a synchronized list. It includes custom configurations for Mapbox, loader slots, and list content.

### Method
Vue Component Rendering

### Endpoint
N/A

### Parameters

#### Props
- **items** (Array<{ lat: number, lng: number, id: string, [prop: string]: unknown }>) - Required - A list of items to display. Each item must have `lat`, `lng`, and a unique `id`.
- **accessToken** (String) - Required - Your Mapbox access token.
- **mapboxMap** (MapboxMapProps) - Optional - Props for the `MapboxMap` component.
- **mapboxCluster** (MapboxClusterProps) - Optional - Props for the `MapboxCluster` component.
- **mappboxGeocoder** (MapboxGeocoder) - Optional - Props for the `MapboxGeocoder` component.
- **transitions** (StoreLocatorTransitionsProp) - Optional - Props for managing transitions within the component.

### Request Example
```vue
<script setup>
  // Import the component and its CSS
  import { StoreLocator } from '@studiometa/vue-mapbox-gl';
  import '@studiometa/vue-mapbox-gl/index.css';

  // Import Mapbox required CSS stylesheets
  import 'mapbox-gl/dist/mapbox-gl.css';
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';
</script>

<template>
  <StoreLocator
    :items="items"
    :access-token="MAPBOX_API_KEY"
    :mapbox-map="{ mapStyle: 'mapbox://styles/mapbox/streets-v11' }">

    <!-- Loader slot -->
    <template #loader>
      <div class="z-50 absolute inset-0 bg-white flex items-center justify-center">
        <div class="absolute inset-0 bg-gray-300 rounded animate-pulse" />
        <svg class="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
        </svg>
      </div>
    </template>

    <!-- Before list slot -->
    <template #before-list="{ filteredItems }">
      <p class="m-0">Total: {{ filteredItems.length }}</p>
    </template>

    <!-- After list slot -->
    <template #after-list="{ filteredItems }">
      <p v-if="filteredItems.length <= 0">
        No result.
      </p>
    </template>

    <!-- Panel slot -->
    <template #panel="{ close, item }">
      <button @click="close">Close</button>
      <p>{{ item }}</p>
    </template>
  </StoreLocator>
</template>
```

### Response
N/A
```

--------------------------------

### StoreLocator with Data and Slots - Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Provides an example of using the StoreLocator component with data binding for items and Mapbox API key, including custom slots for loader, before list, after list, and panel content.

```vue
<script setup>
  // Import the component and its CSS
  import { StoreLocator } from '@studiometa/vue-mapbox-gl';
  import '@studiometa/vue-mapbox-gl/index.css';

  // Import Mapbox required CSS stylesheets
  import 'mapbox-gl/dist/mapbox-gl.css';
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';
</script>

<template>
  <StoreLocator
    :items="items"
    :access-token="MAPBOX_API_KEY"
    :mapbox-map="{ mapStyle: 'mapbox://styles/mapbox/streets-v11' }">

    <!-- Loader slot -->
    <template #loader>
      <div class="z-50 absolute inset-0 bg-white flex items-center justify-center">
        <div class="absolute inset-0 bg-gray-300 rounded animate-pulse" />
        <svg class="animate-spin h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
        </svg>
      </div>
    </template>

    <!-- Before list slot -->
    <template #before-list="{ filteredItems }">
      <p class="m-0">Total: {{ filteredItems.length }}</p>
    </template>

    <!-- After list slot -->
    <template #after-list="{ filteredItems }">
      <p v-if="filteredItems.length <= 0">
        No result.
      </p>
    </template>

    <!-- Panel slot -->
    <template #panel="{ close, item }">
      <button @click="close">Close</button>
      <p>{{ item }}</p>
    </template>
  </StoreLocator>
</template>
```

--------------------------------

### Basic Mapbox Map and Marker in Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/guide/usage/index.md

Demonstrates the basic setup for rendering a Mapbox GL map and a marker using Vue.js components from '@studiometa/vue-mapbox-gl'. Requires Mapbox GL CSS import.

```vue
<script setup>
  import { MapboxMap, MapboxMarker } from '@studiometa/vue-mapbox-gl';
  import 'mapbox-gl/dist/mapbox-gl.css';
</script>

<template>
  <MapboxMap access-token="...">
    <MapboxMarker position="[0, 0]" />
  </MapboxMap>
</template>
```

--------------------------------

### Basic MapboxMap Usage in Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMap/index.md

Demonstrates the basic setup and rendering of a Mapbox map using the MapboxMap component. It requires an access token and map style. The 'center' prop is bound to a reactive Vue ref.

```vue
<script setup>
  import { ref } from 'vue';
  import { MapboxMap } from '@studiometa/vue-mapbox-gl';

  const mapCenter = ref([0, 0]);
</script>

<template>
  <MapboxMap
    style="height: 400px"
    access-token="..."
    map-style="mapbox://styles/mapbox/streets-v11"
    :center="mapCenter"
    :zoom="1" />
</template>
```

--------------------------------

### MapboxCluster with Popup on Click (Vue)

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxCluster/index.md

Shows how to implement a popup that opens when a clustered feature is clicked. This example utilizes a separate Vue component for the demo and highlights the importance of setting the ':center' prop correctly on the MapboxMap component.

```vue
<<< @/.vitepress/components/MapboxClusterWithPopupDemo.vue{6-8,10-28,38-47}
```

--------------------------------

### Vue: Import and use MapboxNavigationControlDemo

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxNavigationControl/index.md

This snippet shows how to import the MapboxNavigationControlDemo component from a local path and use it within a Vue's script setup.

```vue
<script setup>
  import { MapboxNavigationControlDemo } from '../../.vitepress/components/index.js';
</script>
```

--------------------------------

### Basic Mapbox Geocoder Integration

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxGeocoder/index.md

Integrates the Mapbox Geocoder component within a Mapbox map. Requires Mapbox API key and manual import of geocoder CSS. This example demonstrates basic setup.

```vue
<template>
  <MapboxMap
    style="margin-top: 1em; height: 400px;"
    :access-token="MAPBOX_API_KEY"
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxGeocoder />
  </MapboxMap>
</template>

<script>
  // MaboxGeocoder stylesheet needs to be imported manually.
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';
</script>
```

--------------------------------

### Accessing Mapbox Map Instance via Event in Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/guide/usage/index.md

Shows how to get the Mapbox map instance when it's created using the 'mb-created' event on the MapboxMap component. This allows for direct interaction with the Mapbox API.

```vue
<script setup>
  import { ref } from 'vue';
  import { MapboxMap } from '@studiometa/vue-mapbox-gl';

  const map = ref();
</script>

<template>
  <MapboxMap
    access-token="..."
    @mb-created="(mapboxInstance) => map = mapboxInstance" />
</template>
```

--------------------------------

### Vue Mapbox GL - Basic MapboxGeolocateControl Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxGeolocateControl/index.md

Demonstrates the basic integration of the MapboxGeolocateControl component within a MapboxMap in a Vue application. This example shows how to import and include the necessary components for a functional geolocation control.

```vue
<script setup>
  import { MapboxMap, MapboxGeolocateControl } from '@studiometa/vue-mapbox-gl';
</script>

<MapboxMap
  style="height: 400px"
  access-token="..."
  map-style="mapbox://styles/mapbox/streets-v11">
  <MapboxGeolocateControl />
</MapboxMap>
```

--------------------------------

### Standalone Mapbox Geocoder Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxGeocoder/index.md

Demonstrates using the Mapbox Geocoder component outside of a Mapbox map. Requires the access token and manual import of the geocoder CSS. It also shows how to get the geocoder instance.

```vue
<script setup>
  import { ref } from 'vue';

  // MaboxGeocoder stylesheet needs to be imported manually.
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';

  const control = ref();
</script>

<template>
  <MapboxGeocoder
    :access-token="MAPBOX_API_KEY"
    @mb-created="instance => control = instance" />
</template>
```

--------------------------------

### Build, Test, Lint, and Fix @studiometa/vue-mapbox-gl

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/README.md

This snippet outlines essential npm commands for managing the @studiometa/vue-mapbox-gl project. It includes commands for building the project for deployment, running tests, linting code for style consistency, and automatically fixing linting errors.

```bash
# Build for deployment
npm run build
# Test before deployment
npm run test
# Lint files
npm run lint
# Fix linting errors
npm run fix
```

--------------------------------

### StoreLocator Component Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Demonstrates how to import and use the StoreLocator component, including necessary CSS files.

```APIDOC
## StoreLocator Component Usage

### Description
This section provides instructions on how to import the `StoreLocator` component and its associated CSS files for basic usage.

### Method
Import Statement

### Endpoint
N/A

### Parameters
N/A

### Request Example
```vue
<script setup>
  // Import the component and its CSS
  import { StoreLocator } from '@studiometa/vue-mapbox-gl';
  import '@studiometa/vue-mapbox-gl/index.css';

  // Import Mapbox required CSS stylesheets
  import 'mapbox-gl/dist/mapbox-gl.css';
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';
</script>

<template>
  <StoreLocator>
    ...
  </StoreLocator>
</template>
```

### Response
N/A
```

--------------------------------

### MapboxMarker API

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMarker/index.md

Documentation for the MapboxMarker component, including its props, events, and slots for displaying markers on a Mapbox map.

```APIDOC
## MapboxMarker Component Documentation

Display a marker on the map. This component is a wrapper around the Mapbox GL JS `Marker` class.

### Props

- **`lngLat`** (Array) - Required: `true` - The longitude and latitude of the marker.
- **`popup`** (Object | Boolean) - Required: `false` - Controls the popup associated with the marker. Can be an object with popup options or `false` to disable.
- **`element`** (HTMLElement) - Required: `false` - A custom HTML element to use as the marker.
- **`offset`** (Point | Array) - Required: `false` - The offset of the marker from its `lngLat`.
- **`anchor`** (String) - Required: `false` - Specifies the anchor point of the marker. Defaults to `'center'`.
- **`color`** (String) - Required: `false` - The color of the marker.
- **`scale`** (Number) - Required: `false` - The scale of the marker. Defaults to `1`.
- **`draggable`** (Boolean) - Required: `false` - Whether the marker is draggable. Defaults to `false`.
- **`rotation`** (Number) - Required: `false` - The rotation of the marker in degrees. Defaults to `0`.
- **`pitchAlignment`** (String) - Required: `false` - Specifies the alignment of the marker with the map's pitch. Defaults to `'auto'`.
- **`rotationAlignment`** (String) - Required: `false` - Specifies the alignment of the marker with the map's rotation. Defaults to `'auto'`.

### Events

All events available on the `Marker` class are also available on the `MapboxMarker` component, prefixed by `mb-`.

- **`mb-dragstart`**: Emitted when the marker drag starts.
- **`mb-drag`**: Emitted when the marker is being dragged.
- **`mb-dragend`**: Emitted when the marker drag ends.

### Slots

- **`default`**: Used for markers with custom HTML content.
- **`popup`**: Content rendered inside the attached popup.

### Examples

#### Basic Usage

```vue
<template>
  <MapboxMap
    style="height: 400px"
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxMarker :lng-lat="[0, 0]" />
  </MapboxMap>
</template>

<script setup>
  import { MapboxMap, MapboxMarker } from '@studiometa/vue-mapbox-gl';
</script>
```

#### Custom HTML Marker

```vue
<template>
  <MapboxMap
    style="height: 400px"
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxMarker :lng-lat="[0, 0]">
      <template #default>
        <div>Custom Marker HTML</div>
      </template>
    </MapboxMarker>
  </MapboxMap>
</template>

<script setup>
  import { MapboxMap, MapboxMarker } from '@studiometa/vue-mapbox-gl';
</script>
```

#### Marker with Popup

```vue
<template>
  <MapboxMap
    style="height: 400px"
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxMarker :lng-lat="[0, 0]" :popup=
```

```text

```

```text

```

```text

```

```text

```

```text

```

```text

```

```text

```

```text

```

```text

```

--------------------------------

### MapboxCluster Component Documentation

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxCluster/index.md

Documentation for the MapboxCluster component, including its usage, props, and events.

```APIDOC
## MapboxCluster

Display a cluster on the map with data coming from a GeoJSON source.

### Description

This component is used to display clusters of points on a Mapbox map. It takes GeoJSON data and visually groups nearby points into clusters, which can be expanded on zoom.

### Props

#### `data`

- Type: `String` or `Object`
- Required: `true`

The source of the data for the clustered points. Must be a String or an Object of GeoJSON format.

#### `clusterMaxZoom`

- Type: `Number`
- Default: `14`

The maximum zoom level at which points are still clustered. Beyond this zoom level, individual points will be displayed.

#### `clusterRadius`

- Type: `Number`
- Default: `50`

The radius (in pixels) for each cluster when clustering points. This affects how close points need to be to be grouped together.

#### `clusterMinPoints`

- Type: `Number`
- Default: `2`

The minimum number of points required to form a cluster. If a group of points has fewer than this number, they will not be clustered.

#### `clusterProperties`

- Type: `Object`
- Default: `{}`

An object where you can define custom properties for the generated clusters. This allows for advanced styling or data aggregation on clusters.

#### `clustersLayout`

- Type: `Object`
- Default: `{}`

An object to configure the layout properties for the circles representing clusters. Refer to Mapbox GL JS Style Specification for available options.

#### `clustersPaint`

- Type: `Object`
- Default: `{ 'circle-color': '#000', 'circle-radius': 40 }`

An object to configure the paint properties for the circles representing clusters. This controls the visual appearance like color and size.

#### `clusterCountLayout`

- Type: `Object`
- Default: `{ 'text-field': [ 'get', 'point_count_abbreviated' ] }`

An object to configure the layout properties for the text displaying the count of points within a cluster. By default, it shows an abbreviated point count.

#### `clusterCountPaint`

- Type: `Object`
- Default: `{ 'text-color': 'white' }`

An object to configure the paint properties for the text displaying the count of points within a cluster. This controls the text color and other text-related styles.

#### `unclusteredPointLayerType`

- Type: `String`
- Default: `'circle'`

Specifies the type of layer to use for rendering unclustered points (e.g., 'circle', 'symbol').

#### `unclusteredPointLayout`

- Type: `Object`
- Default: `{}`

An object to configure the layout properties for the individual unclustered points. Useful for custom markers or icons.

#### `unclusteredPointPaint`

- Type: `Object`
- Default: `{ 'circle-color': '#000', 'circle-radius': 4 }`

An object to configure the paint properties for the individual unclustered points. This defines their visual appearance when they are not part of a cluster.

### Events

#### `mb-cluster-click`

Emitted when the user clicks on a cluster.

- **Params**
  - `clusterId`: the ID of the cluster being clicked
  - `event`: the Mapbox event object sent by the layer

#### `mb-feature-click`

Emitted when the user clicks on an unclustered point (a feature).

- **Params**
  - `feature`: the feature being clicked on
  - `event`: the Mapbox event object sent by the layer

#### `mb-feature-mouseenter`

Emitted when the user's mouse enters an unclustered point.

- **Params**
  - `feature`: the feature being clicked on
  - `event`: the Mapbox event object sent by the layer

#### `mb-feature-mouseleave`

Emitted when the user's mouse leaves an unclustered point.

- **Params**
  - `event`: the Mapbox event object sent by the layer

### Examples

#### Basic Usage

```vue
<template>
  <MapboxMap
    style="height: 400px"
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxCluster data="/earthquakes.json" />
  </MapboxMap>
</template>

<script setup>
  import { MapboxMap, MapboxCluster } from '@studiometa/vue-mapbox-gl';
</script>
```

#### Open popup on feature click

(See the `MapboxClusterWithPopupDemo.vue` component for this example.)

:::warning
The `:center` prop of the `MapboxMap` component must be set via a data property (see `mapCenter` in the example above) instead of directly in the template, as it can create unexpected behaviours when clicking on a cluster feature.
:::

#### Custom marker for unclustured points

(See the `MapboxClusterWithCustomImageDemo.vue` component for this example.)
```

--------------------------------

### Import StoreLocator Component and CSS - Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Demonstrates how to import the StoreLocator component and its associated CSS files, along with Mapbox GL JS and Mapbox Geocoder CSS, for basic usage in a Vue application.

```vue
<script setup>
  // Import the component and its CSS
  import { StoreLocator } from '@studiometa/vue-mapbox-gl';
  import '@studiometa/vue-mapbox-gl/index.css';

  // Import Mapbox required CSS stylesheets
  import 'mapbox-gl/dist/mapbox-gl.css';
  import '@mapbox/mapbox-gl-geocoder/lib/mapbox-gl-geocoder.css';
</script>

<template>
  <StoreLocator>
    ...
  </StoreLocator>
</template>
```

--------------------------------

### Basic MapboxMarker Usage in Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMarker/index.md

Demonstrates how to display a basic marker on a Mapbox map using the MapboxMarker component. Requires Mapbox API key and map style configuration.

```vue
<script setup>
  import { MapboxMap, MapboxMarker } from '@studiometa/vue-mapbox-gl';
</script>

<template>
  <MapboxMap
    style="height: 400px"
    access-token="..."
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxMarker :lng-lat="[0, 0]" />
  </MapboxMap>
</template>
```

--------------------------------

### StoreLocator Props

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Details the available props for the StoreLocator component, including their types, default values, and descriptions.

```APIDOC
## StoreLocator Props

### Description
This section details all the configurable properties (props) for the `StoreLocator` component.

### Method
Component Props

### Endpoint
N/A

### Parameters

#### `items`
- **Type**: `Array<{ lat: number, lng: number, id: string, [prop: string]: unknown }>`
- **Required**: `true`
- **Description**: A list of items to display on the map and in the list. Each item must include `lat`, `lng` coordinates and a unique `id`.

#### `itemZoomLevel`
- **Type**: `Number`
- **Default**: `14`
- **Description**: The zoom level applied when an individual item is selected and the map zooms to it.

#### `accessToken`
- **Type**: `String`
- **Default**: `no-token`
- **Description**: Your Mapbox access token, necessary for map rendering and API requests.

#### `mapboxMap`
- **Type**: `MapboxMapProps`
- **Default**: `{}`
- **Description**: Allows passing props directly to the underlying `MapboxMap` component for customization. Refer to the [MapboxMap component props](/components/MapboxMap/#props) for available options.

#### `mapboxCluster`
- **Type**: `MapboxClusterProps`
- **Default**: `{}`
- **Description**: Allows passing props directly to the underlying `MapboxCluster` component for customizing marker clustering. Refer to the [MapboxCluster component props](/components/MapboxCluster/#props) for available options.

#### `mappboxGeocoder`
- **Type**: `MapboxGeocoder`
- **Default**: `{}`
- **Description**: Allows passing props directly to the underlying `MapboxGeocoder` component for search functionality. Refer to the [MapboxGeocoder component props](/components/MapboxGeocoder/#props) for available options.

#### `transitions`
- **Type**: `StoreLocatorTransitionsProp`
```ts
interface StoreLocatorTransitionsProp {
  loader?: {
    default?: TransitionProps,
    map?: TransitionProps,
    search?: TransitionProps,
    list?: TransitionProps
  },
  panel?: TransitionProps
}
```
- **Default**: `{}` for each `TransitionProps`
- **Description**: Configuration object for managing transitions for various parts of the component, including loader states (default, map, search, list) and the information panel. Consult the [Vue Transition component documentation](https://vuejs.org/v2/api/#transition) for details on `TransitionProps`.

### Response
N/A
```

--------------------------------

### Vue Mapbox Popup Basic Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxPopup/index.md

Demonstrates the basic integration of the MapboxPopupDemo component in a Vue application. It requires an API key for Mapbox.

```javascript
<script setup>
  import { MapboxPopupDemo } from '../../.vitepress/components/index.js';
</script>

<ClientOnly>
  <MapboxPopupDemo api-key="MAPBOX_API_KEY" />
</ClientOnly>
```

--------------------------------

### MapboxPopup Component

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxPopup/index.md

Detailed documentation for the MapboxPopup component, including its props, events, and slots.

```APIDOC
## MapboxPopup Component

Display a popup on the map.

### Description
This component allows you to display informative popups associated with specific locations on a Mapbox map. It leverages Mapbox GL JS for its functionality.

### Props

#### `lngLat`
- **Type**: `[ LngLat, Array, Object ]`
- **Required**: `true`
- **Description**: Center position for the popup.

#### `closeButton`
- **Type**: `[ Boolean ]`
- **Required**: `false`
- **Default**: `true`
- **Description**: Display a close button on the popup.

#### `closeOnClick`
- **Type**: `[ Boolean ]`
- **Required**: `false`
- **Default**: `true`
- **Description**: Close the popup on close button click.

#### `closeOnMove`
- **Type**: `[ Boolean ]`
- **Required**: `false`
- **Default**: `false`
- **Description**: Close the popup when the map moves.

#### `anchor`
- **Type**: `[ String ]`
- **Required**: `false`
- **Description**: A string indicating the part of the Popup that should be positioned closest to its coordinate. Refer to Mapbox GL JS documentation for details.

#### `offset`
- **Type**: `[ Number, Point, Array, Object ]`
- **Required**: `false`
- **Default**: `null`
- **Description**: Offset the popup from its original lngLat position.

#### `className`
- **Type**: `[ String ]`
- **Required**: `false`
- **Default**: `null`
- **Description**: Add a className to the popup.

#### `maxWidth`
- **Type**: `[ String ]`
- **Required**: `false`
- **Default**: `240px`
- **Description**: Set a max-width to the popup.

#### `renderless`
- **Type**: `[ Boolean ]`
- **Required**: `false`
- **Default**: `false`
- **Description**: Do not add the popup to the map on creation.

### Events

#### `mb-open`
- **Description**: Emitted when the popup is opened manually or programmatically.
- **Parameters**:
  - `popup`: The object that was opened.
  - `event`: The Mapbox event object sent by the layer.

#### `mb-close`
- **Description**: Emitted when the popup is closed manually or programmatically.
- **Parameters**:
  - `popup`: The object that was closed.
  - `event`: The Mapbox event object sent by the layer.

### Slots

#### `default`
- **Description**: The default slot will be rendered inside the popup.
```

--------------------------------

### MapboxImages Component Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxImages/index.md

Demonstrates how to add multiple images to a Mapbox map using the MapboxImages component.

```APIDOC
## MapboxImages Component Usage

### Description
This component allows you to add multiple images to your Mapbox map simultaneously. It iterates through a provided list of image sources and uses the `MapboxImage` component internally to add each one.

### Method
POST (Implicit via component rendering)

### Endpoint
N/A (Component-based integration)

### Props

#### `sources` (Array) - Required
A list of images to add to the map. Each item in the array should be an object with the following properties:

- **`id`** (String) - Required - The unique identifier for the image.
- **`src`** (String | HTMLImageElement | ImageData | Object) - Required - The image data itself. Can be a URL, an `HTMLImageElement`, `ImageData`, or an object with `width`, `height`, and `data` properties.
- **`options`** (Object) - Optional - Configuration options passed directly to Mapbox GL JS's `addImage` method. Defaults to `{ pixelRatio: 1, sdf: false }`.

### Events

#### `add`
Emitted for each image added to the map.

**Properties:**
- `image` (Object) - Information about the added image.
  - `id` (String) - The ID of the image.
  - `src` (HTMLImageElement | ImageData | Object) - The source of the image.
  - `options` (Object) - The options used for adding the image.
- `index` (Number) - The index of the image in the `sources` array.
- `total` (Number) - The total number of images being added.

#### `ready`
Emitted when all images have been successfully added to the map.

**Properties:**
- `images` (Array) - An array of objects, each containing information about an added image.

### Slots

#### `default`
Content placed in the default slot is rendered after all images have been added to the map, typically coinciding with the `ready` event.
```

--------------------------------

### MapboxMap Component - Accessing Map Instance

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMap/index.md

Illustrates how to access the Mapbox GL Map instance using the `@mb-created` event, allowing for programmatic control of the map such as using methods like `flyTo` or `panTo`.

```APIDOC
## MapboxMap Component - Accessing Map Instance

### Description
This example demonstrates how to get a reference to the Mapbox GL Map instance. The `MapboxMap` component emits an `mb-created` event with the Mapbox instance as a payload, enabling direct interaction with the map's API.

### Method
N/A (Component Usage)

### Endpoint
N/A (Component Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```vue
<template>
  <MapboxMap
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11"
    @mb-created="(mapInstance) => map = mapInstance" />
</template>

<script>
  import 'mapbox-gl/dist/mapbox-gl.css';
  import MapboxMap from '@studiometa/vue-mapbox-map/dist/components/MapboxMap';

  export default {
    components: {
      MapboxMap,
    },
    data() {
      return {
        map: null,
      };
    },
  };
</script>
```

### Response
#### Success Response (200)
N/A (Component Rendering)

#### Response Example
N/A (Component Rendering)
```

--------------------------------

### MapboxMap Component - Basic Usage

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMap/index.md

Demonstrates the fundamental usage of the MapboxMap component to display a map with specified access token, map style, and center coordinates.

```APIDOC
## MapboxMap Component - Basic Usage

### Description
This example shows how to integrate the MapboxMap component into a Vue application to display a map. It includes essential props like `access-token`, `map-style`, and `center`.

### Method
N/A (Component Usage)

### Endpoint
N/A (Component Usage)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```vue
<script setup>
  import { ref } from 'vue';
  import { MapboxMap } from '@studiometa/vue-mapbox-gl';

  const mapCenter = ref([0, 0]);
</script>

<template>
  <MapboxMap
    style="height: 400px"
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    map-style="mapbox://styles/mapbox/streets-v11"
    :center="mapCenter"
    :zoom="1" />
</template>
```

### Response
#### Success Response (200)
N/A (Component Rendering)

#### Response Example
N/A (Component Rendering)
```

--------------------------------

### Basic MapboxCluster Usage in Vue

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxCluster/index.md

Demonstrates the basic integration of the MapboxCluster component within a Vue application. It requires importing MapboxMap and MapboxCluster, setting a Mapbox API key, and providing a GeoJSON data source.

```vue
<script setup>
  import { MapboxMap, MapboxCluster } from '@studiometa/vue-mapbox-gl';
</script>

<template>
  <MapboxMap
    style="height: 400px"
    access-token="..."
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxCluster data="/earthquakes.json" />
  </MapboxMap>
</template>
```

--------------------------------

### Accessing Mapbox Instance via mb-created Event

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMap/index.md

Shows how to access the Mapbox GL JS Map instance using the 'mb-created' event. This event emits the Mapbox instance, allowing you to call methods like 'flyTo' or 'panTo'. It also includes necessary imports for Mapbox CSS and the component.

```vue
<template>
  <MapboxMap
    access-token="..."
    map-style="..."
    @mb-created="(mapInstance) => map = mapInstance" />
</template>

<script>
  import 'mapbox-gl/dist/mapbox-gl.css';
  import MapboxMap from '@studiometa/vue-mapbox-map/dist/components/MapboxMap';

  export default {
    components: {
      MapboxMap,
    },
    data() {
      return {
        map: null,
      };
    },
  },
</script>
```

--------------------------------

### Vue Mapbox GL Default Class Structure (JavaScript)

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/StoreLocator/index.md

Provides the default BEM (Block, Element, Modifier) structure for CSS classes in the Vue Mapbox GL component, organizing styles for different parts of the UI.

```javascript
{
  root  : 'store-locator',
  region: {
    map: [
      'store-locator__region',
      'store-locator__region--map'
    ],
    search: [
      'store-locator__region',
      'store-locator__region--search'
    ],
    list: [
      'store-locator__region',
      'store-locator__region--list'
    ],
    panel: [
      'store-locator__region',
      'store-locator__region--panel',
    ],
  },
  map          : 'store-locator__map',
  search       : 'store-locator__search',
  list         : 'store-locator__list',
  listItem     : 'store-locator__list-item',
  panel        : 'store-locator__panel',
}
```

--------------------------------

### Vue: Basic Usage of MapboxNavigationControl

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxNavigationControl/index.md

Demonstrates the basic integration of the MapboxNavigationControlDemo component within a Vue application. It uses ClientOnly to ensure the component renders only on the client side.

```vue
<ClientOnly>
  <MapboxNavigationControlDemo style="margin-top: 1em;" />
</ClientOnly>
```

--------------------------------

### MapboxMap Component Props

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxMap/index.md

A comprehensive list of all available props for the MapboxMap component, detailing their types, default values, and descriptions. These props map directly to Mapbox GL's Map constructor options.

```APIDOC
## MapboxMap Component Props

### Description
This section details all the configurable properties (props) for the `MapboxMap` component. These props allow you to customize the map's behavior, appearance, and data sources, mirroring the options available in the Mapbox GL JS Map constructor.

### Method
N/A (Component Props)

### Endpoint
N/A (Component Props)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Props List:

- **`accessToken`** (String, Required: true) - Your Mapbox access token.
- **`mapStyle`** (String | Object, Required: true) - A map style definition, can be a JSON object following the [Mapbox Style specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/) or a URL to such a JSON. This prop is mapped to the `options.style` configuration of the map creation.
- **`container`** (HTMLElement | String, Default: undefined) - The DOM element or selector for the map container.
- **`minZoom`** (Number, Default: 0) - Minimum zoom level.
- **`maxZoom`** (Number, Default: 22) - Maximum zoom level.
- **`minPitch`** (Number, Default: 0) - Minimum pitch (tilt) allowed.
- **`maxPitch`** (Number, Default: 60) - Maximum pitch (tilt) allowed.
- **`hash`** (Boolean, Default: false) - If true, the map's hash (zoom, center, bearing, pitch) will be synced to the URL's hash.
- **`interactive`** (Boolean, Default: true) - Enables or disables interactive map features (panning, zooming, rotating).
- **`bearingSnap`** (Number, Default: 7) - The threshold, in degrees, at which the map's bearing will snap to the nearest increment of this value.
- **`pitchWithRotate`** (Boolean, Default: true) - If true, the pitch will change as the map is rotated.
- **`clickTolerance`** (Number, Default: 3) - The tolerance, in pixels, within which the map will respond to clicks.
- **`attributionControl`** (Boolean, Default: true) - Whether to display the Mapbox attribution control.
- **`customAttribution`** (String | Array, Default: null) - Custom attribution string or array to display.
- **`logoPosition`** (String, Default: 'bottom-left') - Position of the Mapbox logo.
- **`failIfMajorPerformanceCaveat`** (Boolean, Default: false) - If true, the map will fail to load if a major performance caveat is detected.
- **`preserveDrawingBuffer`** (Boolean, Default: false) - If true, the drawing buffer will be preserved after rendering, allowing for exports.
- **`antialias`** (Boolean, Default: false) - If true, enables anti-aliasing for smoother rendering.
- **`refreshExpiredTiles`** (Boolean, Default: true) - If true, expired tiles will be refreshed.
- **`maxBounds`** (LngLatBounds | Array, Default: undefined) - Sets the map's maximum bounds.
- **`scrollZoom`** (Boolean | Object, Default: true) - Enables or disables scroll wheel zooming.
- **`boxZoom`** (Boolean, Default: true) - Enables or disables box zoom.
- **`dragRotate`** (Boolean, Default: true) - Enables or disables drag-to-rotate.
- **`dragPan`** (Boolean | Object, Default: true) - Enables or disables drag-to-pan.
- **`keyboard`** (Boolean, Default: true) - Enables or disables keyboard navigation.
- **`doubleClickZoom`** (Boolean, Default: true) - Enables or disables double-click to zoom.
- **`touchZoomRotate`** (Boolean | Object, Default: true) - Enables or disables pinch-to-zoom and two-finger-rotate gestures.
- **`trackResize`** (Boolean, Default: true) - If true, the map will automatically track and update its size when the window is resized.
- **`center`** ([LngLat, Array, Object], Default: () => [0, 0]) - The initial center coordinates of the map.
- **`zoom`** (Number, Default: 0) - The initial zoom level of the map.
- **`bearing`** (Number, Default: 0) - The initial bearing (rotation) of the map.
- **`pitch`** (Number, Default: 0) - The initial pitch (tilt) of the map.
- **`bounds`** ([LngLatBounds, Array], Default: undefined) - Sets the map's initial bounds.
- **`fitBoundsOptions`** (Object, Default: null) - Options for fitting the map to the bounds.
- **`renderWorldCopies`** (Boolean, Default: true) - If true, renders world copies.
- **`maxTileCacheSize`** (Number, Default: null) - Maximum size of the tile cache.
- **`localIdeographFontFamily`** (String, Default: 'sans-serif') - Font family for local ideographs.
- **`transformRequest`** (Function, Default: null) - A function to transform requests.
- **`collectResourceTiming`** (Boolean, Default: false) - If true, collects resource timing information.
- **`fadeDuration`** (Number, Default: 300) - Duration of the fade animation when changing styles or tiles.
- **`crossSourceCollisions`** (Boolean, Default: true) - If true, allows sources to collide.
- **`cooperativeGestures`** (Boolean, Default: false) - If true, enables cooperative gestures for touch devices.
- **`language`** (String | Array, Default: null) - Specifies the language for map labels.
- **`locale`** (Object, Default: null) - Locale object for internationalization.
- **`localFontFamily`** (String, Default: false) - Font family for local fonts.
- **`minTileCacheSize`** (Number, Default: null) - Minimum size of the tile cache.
```

--------------------------------

### Vue Component Definition for MapboxImages

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxImages/index.md

Defines the Vue component for MapboxImages, importing necessary sub-components and setting up the script for composition API. It utilizes the MapboxImagesDemo component for showcasing functionality.

```vue
<script setup>
  import { MapboxImagesDemo } from '../../.vitepress/components/index.js';
</script>

# MapboxImages

Add multiple images at once to be used used in `icon-image`, `background-pattern`, `fill-pattern`, and `line-pattern`. This component is a wrapper around the [`MapboxImage`](/components/MapboxImage/) component.

<h2>Table of contents</h2>

[[toc]]

## Examples

### Add multiple icons to the map

<ClientOnly>
  <MapboxImagesDemo style="margin-top: 1rem;" api-key="MAPBOX_API_KEY" />
</ClientOnly>

<<< @/.vitepress/components/MapboxImagesDemo.vue{4-13,15-49,59-61}
```

--------------------------------

### MapboxPopupDemo Component Structure

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxPopup/index.md

Shows the internal structure of the MapboxPopupDemo Vue component, highlighting the props it accepts for controlling popup behavior.

```vue
<script setup>
import { defineProps } from 'vue';

defineProps({
  apiKey: {
    type: String,
    required: true,
  },
});
</script>

<template>
  <div class="mapbox-popup-demo">Popup Content Here</div>
</template>

<style scoped>
.mapbox-popup-demo {
  padding: 10px;
  background-color: white;
  border-radius: 4px;
}
</style>
```

--------------------------------

### MapboxCluster with Custom Unclustered Marker (Vue)

Source: https://github.com/studiometa/vue-mapbox-gl/blob/develop/packages/docs/components/MapboxCluster/index.md

Illustrates how to customize the marker for individual, unclustered points on the map. This involves using the 'unclusteredPointLayout' and 'unclusteredPointPaint' props or a dedicated component for custom rendering.

```vue
<<< @/.vitepress/components/MapboxClusterWithCustomImageDemo.vue{8,12-15,17}
```
Tokens:
Raw