Docs
`/`

# API elements

No matching results

# Sections and content

No matching results

- `Enter` to go to the highlighted result.
- `↑` and `↓` to change highlight.
- `Tab` to switch between result lists.
- `Esc` to hide the results.

# Quick start

This article shows how to build your first simple dotAtlas visualization. See the ES6 + NPM + React or plain old JavaScript options below.

##
ES6 + NPM + React

To add dotAtlas to your React-based application, follow these steps.

1. Add dotAtlas dependency to your project:

       npm install @carrotsearch/dotatlas

   or

       yarn add @carrotsearch/dotatlas

2. Create a React component that will embed dotAtlas into your application.

       import React, { useEffect, useRef } from "react";
       import { DotAtlas as DotAtlasImpl } from "@carrotsearch/dotatlas";

       export const DotAtlas = () => {
         const element = useRef(null);
         useEffect(() => {
           const points = [
             { x: 0, y: 0, elevation: 1.0, label: "Central peak" },
             { x: -1, y: 0, elevation: 0.6, label: "West peak" },
             { x: 1, y: 0, elevation: 0.6, label: "East peak" },
             { x: 0, y: -1, elevation: 0.4, label: "North peak" },
             { x: 0, y: 1, elevation: 0.4, label: "South peak" }
           ];

           const dotatlas = DotAtlasImpl.embed({
             element: element.current,
             layers: [
               { points: points, type: "elevation" },
               { points: points, type: "marker" },
               { points: points, type: "label" }
             ]
           });

           return () => dotatlas.dispose();
         }, []);

         return <div ref={element} style={{ width: 400, height: 300 }} />;
       };

3. Use the component in your application. See the dotAtlas quick start CodeSandbox for a complete working example.

##
Plain old JavaScript

To get your first dotAtlas visualization, follow these three steps:

1. Include `dotatlas.min.js` in the code of your page. You can get it from the dotAtlas distribution package or from the UNPKG CDN:

       https://unpkg.com/@carrotsearch/dotatlas@%NPM_VERSION%/dotatlas.min.js

2. Define an HTML element into which dotAtlas should be embedded. The element must have non-zero dimensions.

3. Initialize dotAtlas by calling the `DotAtlas.embed()` method. In the options object passed to the method, provide a reference to the HTML element and some data to visualize.

The code below is a complete working example. Please note you may need to correct the path to `dotatlas.js` depending on the structure of your project.

    <!doctype html>
    <html>
      <head>
        <title>dotAtlas Hello World</title>
        <meta charset="utf-8" />
      </head>

      <body>
        <div id="dotatlas" style="width: 600px; height: 400px"></div>  <!-- highlight-line -->
        <script src="dotatlas.min.js"></script>  <!-- highlight-line -->
        <script>

          window.addEventListener("load", function () {
            const points = [
              { x:  0, y: 0,  elevation: 1.0, label: "Central peak" },
              { x: -1, y: 0,  elevation: 0.6, label: "West peak" },
              { x:  1, y: 0,  elevation: 0.6, label: "East peak" },
              { x:  0, y: -1, elevation: 0.4, label: "North peak" },
              { x:  0, y: 1,  elevation: 0.4, label: "South peak" },
            ];

            const dotatlas = DotAtlas.embed({
              element: document.getElementById("dotatlas"),
              layers: [
                { points: points, type: "elevation" },
                { points: points, type: "marker" },
                { points: points, type: "label" }
              ]
            });
          });
        </script>
      </body>
    </html>

A ~30-line working dotAtlas example with elevations, marker and label layers.

Notice that dotAtlas is initialized in the `load` event listener to ensure that the provided HTML element has non-zero dimensions.

If everything worked correctly, you should see the following visualization:

Visualization produced by the ~30-line dotAtlas example.
previous article
Hello, dotAtlas!
next article
Requirements