Custom UI basics

Introduction

The ArcGIS Maps SDK for JavaScript provides the ability to add custom UI building blocks to your application. You can set up simple layouts using methods to place components into the corners of the view. Components are typically DOM elements such as DIVs, web components or components built using a JavaScript framework. These can be used in combination with the Calcite Design System.

Here is psuedocode demonstrating the concept for adding a single DIV element:

index.html - add a <div> element that displays a custom message:

1
2
   <!-- Define the custom div element -->
   <div id="customTextDiv">My custom text</div>

styles.css - style the custom <div> element:

1
2
3
4
5
6
  /* Style the custom div */
  #customTextDiv {
    width: 30px;
    height: 20px;
    color: red;
  }

main.js - add the <div> to the view:

1
2
   // Add the custom div to the top right of the view
   view.ui.add(document.getElementById("customTextDiv"), "top-right");

The DefaultUI class provides methods to add, move and remove SDK widgets or other DOM elements. The Using the view's UI sample demonstrates the capabilities.

Custom Framework components

Front-end JavaScript frameworks such as React, Angular and Vue.js use components as their basic building blocks. You can add these to your mapping application's view using the same pattern demonstrated above.

It is recommended to use the @arcgis/core ES modules with JavaScript frameworks. Choose the framework that best fits your requirements. The framework's component architecture can be loosely coupled with the functionality in the JavaScript Maps SDK. This approach provides the best level of integration because you have full control over the user experience, user interface and life-cycle.

Implementation patterns

JavaScript framework components consist of markup such as JSX, HTML elements, CSS and JavaScript. Framework components also provide capabilities for handling user input, managing state, as well as managing interactivity with the rest of the mapping application. The different frameworks often share similar concepts of how components work, however the implementation patterns are often completely different.

These components can be added, moved and removed from the MapView or SceneView using the methods in the DefaultUI class. The API automatically handles positioning when there are multiple elements, as well as adapting to different view sizes.

For demonstration, below is React psuedocode to create a basic component called SimpleComponent that returns a single HTML <div> element, and then adds it to the view. To see a working application built with React and Vite, refer to the jsapi-custom-ui sample.

Create a simple component

Create a component with a <div> element that can be assigned an id and myMessage property.

SimpleComponent.jsx

1
2
3
4
5
6
7
8
9
10
11
/**
* A simple component for displaying a message
* @param {string} id - The `id` of the components parent HTML div
* @param {string} myMessage - A simple message to display
* @returns A single div element
*/
const SimpleComponent = ({ id, myMessage }) => {
   return <div id={id}>{myMessage}</div>
}

export default SimpleComponent;

Import the component into your application

Import the component into your application by adding it to the view. Be sure to enable any life-cycle hooks and data bindings to ensure the component is initialized correctly and synchronized with your JavaScript Maps SDK functionality.

App.jsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Import the custom component into your mapping app
import SimpleComponent from "./SimpleComponent.jsx";

// Add a hook to access the component's DOM element
const simpleComponentID = useRef("simple-component");

// Set a message to display
const message = "Hello World";

. . .

// Add the component to the view using the DefaultUI's `add()` method.
view.ui.add(document.getElementById(simpleComponentID.current), "top-right");

// Implement the component in markup and set the `id` and `myMessage`.
// This will display "Hello World" in the top-right of the view.
return {
  <SimpleComponent id={simpleComponentID.current} myMessage={message}></SimpleComponent>;
);

Custom UI themes

Custom UI elements are often styled using their parent design system, such as Material UI for React and Angular. However, if you want to the match the look-and-feel of the out-of-the-box JavaScript Maps SDK widgets, then be sure to look at the Calcite Design System guide page.

Additional information

Please refer to these additional links for further information:

• Guide - Build with ES modules
• JSX reference