/

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:

Result of the quick start simple dotAtlas visualization.
Visualization produced by the ~30-line dotAtlas example.