> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementlabs.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> The events the map raises, the events it listens for, and how it affects other resources while open.

All events on this page are client-side and local to the client. Use `AddEventHandler` to listen and
`TriggerEvent` to raise.

## Contract

### Raised by the map

| Event                | Arguments       | When                                                                                 |
| -------------------- | --------------- | ------------------------------------------------------------------------------------ |
| `el:map:ready`       | none            | The map's client side has finished loading and its exports are callable.             |
| `el:map:open`        | `view: string`  | The map has begun opening, on that view. The camera transition has not finished yet. |
| `el:map:close`       | none            | The map has closed and the camera has returned.                                      |
| `el:map:view:enter`  | `view: string`  | A view is on screen. Raised with `el:map:open`, and again after a `SwitchView`.      |
| `el:map:view:leave`  | `view: string`  | That view is no longer on screen.                                                    |
| `el:map:stop`        | none            | The `element_map` resource is stopping.                                              |
| `el:map:page:enter`  | `id: string`    | A page registered with `RegisterPage` is on screen.                                  |
| `el:map:page:leave`  | `id: string`    | A page was left, or the map closed under it.                                         |
| `el:map:page:action` | `action: table` | Something in a page was used. See [Pages](/products/map/reference/pages).            |

### Listened for by the map

| Event               | Arguments                         | Effect                                                                                                         |
| ------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `el:map:blip:meta`  | `handle: number`, `fields: table` | Attaches map information to a marker created with the game's own functions. The same as calling `SetBlipMeta`. |
| `el:map:blip:gone`  | `handle: number`                  | Forgets the information attached to that marker.                                                               |
| `el:map:blip:new`   | `handle: number`                  | Tells the map a marker was created, so it appears without waiting for the next sweep.                          |
| `el:map:blip:touch` | `handle: number`                  | Tells the map a marker has changed, so its appearance is refreshed.                                            |

A view also reports itself through the SDK's hooks — `el:map:view:open`, `el:map:view:ready`,
`el:map:view:close` and `el:map:view:params` — which is where a resource takes part rather than only
being told. `el:map:view:open` is the one that can refuse an open. See
[Views](/products/map/reference/views).

The four listened-for events are what the map's integration uses. Raising them yourself is
supported, and is the alternative to `SetBlipMeta` when your code cannot reach the export.

## Inputs

The page events carry the `id` you gave `RegisterPage`. Compare against your own id: every
registered page raises the same events.

The `fields` table of `el:map:blip:meta` accepts the same keys as `SetBlipMeta`. See
[Exports](/products/map/reference/exports). Repeated calls for one marker are merged.

## Outputs

`el:map:open` is raised as the map starts opening, so a handler runs before the camera has finished
moving. Use it to prepare state, not to assume the map is on screen.

`el:map:close` is raised in every case the map stops being open: the player closed it, the player
died, or the resource was stopped. It is also raised if opening failed part way through, so an
`el:map:open` handler is always followed by an `el:map:close` handler.

`el:map:open` carries the id of the view being opened, so a handler can tell the standard map from a
view of its own without asking. `el:map:view:leave` is raised for every view that leaves the screen,
including when the map closes and when a resource stop takes it down.

`el:map:ready` is raised once per resource start. A resource that starts after the map has already
started never sees it. Use `GetResourceState('element_map')` in that case.

## Errors

None of these events report failure. An unknown marker handle is ignored, and an unregistered page id
never occurs in the page events because the map only raises ids it was given.

## While the map is open

The integration changes one thing in your other resources: while the map is open, the game's
pause-menu check reports that the pause menu is active. The map takes the place of the pause map, so
code that pauses on the pause menu behaves the same way for the map.

This applies inside every resource the integration was installed into, and only while the map is
open. If a resource of yours must tell the two apart, listen for `el:map:open` and `el:map:close`
and track it yourself.

See [Product integrations](/concepts/integrations) for what the integration is and how to install
it.

## Example

Waiting for the map to be ready, then registering a page and reacting to it:

```lua theme={null}
AddEventHandler('el:map:ready', function()
  exports.element_map:RegisterPage({
    id = 'jobs',
    label = 'Jobs',
    order = 2,
    content = { schemaVersion = 1, title = 'Jobs', sections = {} },
  })
end)

AddEventHandler('el:map:page:action', function(event)
  if event.page == 'jobs' and event.action == 'refresh' then
    exports.element_map:SetPageContent('jobs', jobsPage())
  end
end)
```

The content of a page and what it reports are described in [Pages](/products/map/reference/pages).

Pausing your own work while the map is open:

```lua theme={null}
local mapOpen = false

AddEventHandler('el:map:open', function() mapOpen = true end)
AddEventHandler('el:map:close', function() mapOpen = false end)
```

Attaching information to a marker without calling the export:

```lua theme={null}
local handle = AddBlipForCoord(-1037.0, -2738.0, 20.0)
TriggerEvent('el:map:blip:meta', handle, { name = 'Airport', category = 3 })
```

## Related

* [Exports](/products/map/reference/exports)
* [Views](/products/map/reference/views)
* [Product integrations](/concepts/integrations)