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 the div element, web components or components built using a JavaScript framework. These can be used in combination with the [Calcite Design System] (https://developers.arcgis.com/calcite-design-system/).
Here is pseudocode demonstrating the concept for adding a single div element:
index.html - add a <div
element that displays a custom message:
<!-- Define the custom div element -->
<div id="customTextDiv">My custom text</div>
styles.css - style the custom <div
element:
/* Style the custom div */
#customTextDiv {
width: 30px;
height: 20px;
color: red;
}
main.js - add the <div
to the view:
// 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 Map
or Scene
using the methods in the Default
class. The API automatically handles positioning when there are multiple elements, as well as adapting to different view sizes.
For demonstration, below is React pseudocode to create a basic component called Simple
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 my
property.
SimpleComponent.jsx
/**
* 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
// 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 - Getting started with npm
- JSX reference