> For the complete documentation index, see [llms.txt](https://developers.felt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.felt.com/js-sdk/getting-started.md).

# Getting started

The Felt SDK allows you to control your Felt maps and build powerful, interactive custom applications. You can control many aspects of the Felt UI and map contents, as well as receive notifications of events happening in the map such as clicks, selections, and more.

{% hint style="info" %}
Requires the Platform add-on, and included in the free trial. [Extensions](#extensions) require Business or Enterprise instead. See [Plans, access and limits](/plans-access-and-limits.md).
{% endhint %}

See our [examples](/js-sdk/examples.md) page to explore what you can build with the SDK.

There are two main ways to use the Felt SDK:

1. Extensions
2. Embedded maps

### Extensions

Write code directly within Felt using our [Extensions](https://help.felt.com/dashboards-and-apps/extensions) feature. Extensions run directly within the Felt environment, giving you immediate access to all SDK functionality without embedding or connection steps. They're available on the Business and Enterprise plans.

<figure><img src="https://293097899-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLlIfNdbm4rCsu755xrdc%2Fuploads%2FKVtYiPCK0XDSyd8RP6yt%2Fextensions.avif?alt=media&amp;token=9dcb3e74-9d71-43bf-a49b-14b14efc037b" alt=""><figcaption></figcaption></figure>

When creating an extension, you automatically have access to a [`FeltController`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller) object named `felt` with no setup required. This controller provides all the methods you need to interact with your Felt map, including `getViewport`, `createElement`, `setLayerStyle`, and many more.

```javascript
// In a Felt extension, the controller is automatically available
const layers = await felt.getLayers();

// Listen for map events
felt.onSelectionChange({
  handler: ({ selection }) => console.log("Selection changed:", selection),
});
```

### Embedded maps

Embed Felt maps in your own applications and control them remotely. This needs the Platform add-on. To show private maps to your app's users without Felt accounts, see [Authenticated embeds](/js-sdk/authenticated-embeds.md).

#### What you'll need

* A Felt map to embed. Open any map you have access to and grab its ID from the URL: in `felt.com/map/Readable-Title-xPV9BqMuYQxmUraVWy9C89BNA`, the ID is the trailing part, `xPV9BqMuYQxmUraVWy9C89BNA`.
* The map's sharing settings must allow the visitor to view it. Public and unlisted maps work out of the box; for private maps see [Authenticated embeds](/js-sdk/authenticated-embeds.md).

#### Installation

Install the SDK using your preferred package manager:

```bash
npm install @feltmaps/js-sdk
```

Alternatively, load it straight from a CDN in a `<script type="module">` — no build step required:

```javascript
import { Felt } from "https://esm.run/@feltmaps/js-sdk";
```

#### Embed your first map

Create an HTML page with a container element. Give the container an explicit height — an iframe inside a zero-height container renders as an invisible sliver, which is the most common first-run problem:

```html
<html>
  <head>
    <style>
      #container { height: 500px; }
    </style>
  </head>
  <body>
    <div id="container"></div>
    <script type="module" src="main.js"></script>
  </body>
</html>
```

Embed a Felt map in your container element and use the SDK to read from it:

```javascript
// main.js
import { Felt } from "@feltmaps/js-sdk";

const felt = await Felt.embed(
  document.querySelector("#container"),
  "FELT_MAP_ID", // Replace with your map's ID
);

const layers = await felt.getLayers();
console.log(`This map has ${layers.length} layers`);
```

**You should see your map load inside the container**, with the Felt legend and zoom controls visible. Open the browser console and you should see the layer count logged. If the container stays empty, check that the map ID is correct and that the map's sharing settings allow viewing. If the map appears but `Felt.embed` rejects after a few seconds, the map's workspace doesn't have the Platform add-on.

Throughout these docs, code examples assume a controller variable named `felt`, whether it came from `Felt.embed` or from the extension environment.

#### Next steps

* [General concepts](/js-sdk/general-concepts.md) — the mental model: controllers, promises, listeners, and what persists.
* [Controlling maps](/js-sdk/controlling-maps.md) — viewports, and connecting to existing iframes.
* [Embed options](/js-sdk/embed-options.md) — UI controls and initial viewport.
* [Authenticated embeds](/js-sdk/authenticated-embeds.md) — show private maps to your app's users, with server code.
* [Integrating with React](/js-sdk/integrating-with-react.md) — React hooks for the SDK, and the [React starter repo](https://github.com/felt/js-sdk-starter-react) for a quick start.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.felt.com/js-sdk/getting-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.