Get started

Calcite Components is a rich library of flexible, framework-agnostic web components for building web applications. View the component documentation for component descriptions, examples, and API reference, which includes properties, slots, styles, and themes. Follow the steps below to get started using Calcite Components.

First, an ArcGIS account is required to use Calcite Components. If you don't have an account, you can create one for free!

Next, load Calcite Components using the content delivery network (CDN) or Node package manager (NPM) library.

Use the CDN

The most common approach for loading Calcite Components is to use the version hosted on the ArcGIS CDN. The components can be loaded via <script> and <link> tags in the head of your HTML document:

Use dark colors for code blocks
  
1
2
<script type="module" src="https://js.arcgis.com/calcite-components/1.0.0-beta.82/calcite.esm.js"></script>
<link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/1.0.0-beta.82/calcite.css" />

Once these tags are added, components can be used like any other HTML element. Only components that are used in the application will be loaded.

Use the NPM package

Calcite Components is also provided as an NPM package. To get started, first install the package, then follow the steps below. Alternatively, you can find examples using different frameworks and build tools here.

Use dark colors for code blocks
 
1
npm install @esri/calcite-components

Choose a build

Choose one of the two builds provided by Calcite Components.

Custom Elements

Custom Elements is the recommended build when leveraging a frontend framework. To use this build, you will need to set the path to Calcite Components' assets. You can either use local assets, which will be explained in a subsequent step, or assets hosted on the CDN.

Use dark colors for code blocks
      
1
2
3
4
5
6
import { setAssetPath } from "@esri/calcite-components/dist/components";
// CDN hosted assets
setAssetPath("https://js.arcgis.com/calcite-components/1.0.0-beta.82/assets");

// Local assets
// setAssetPath(PATH); // PATH depends on framework, more info below

Next, you need to import each component you use from the custom elements build. This will automatically define the custom elements on the window.

Use dark colors for code blocks
   
1
2
3
import "@esri/calcite-components/dist/components/calcite-button";
import "@esri/calcite-components/dist/components/calcite-icon";
import "@esri/calcite-components/dist/components/calcite-slider";

Distribution

When using the Distribution build, you'll need to define the custom elements on the window. You can also choose between local and CDN hosted assets.

Use dark colors for code blocks
        
1
2
3
4
5
6
7
8
import { defineCustomElements } from "@esri/calcite-components/dist/loader";
// CDN hosted assets
defineCustomElements(window, {
  resourcesUrl: "https://js.arcgis.com/calcite-components/1.0.0-beta.82/assets"
});

// Local assets
// defineCustomElements(window);

Since you defined the custom elements on the window, you do not need to import individual components.

Load the assets

Some components, such as calcite-icon and calcite-date-picker, rely on assets being available at a particular path. As mentioned, with the NPM package you have the option to provide a local path or the URL to the assets hosted on the CDN. Using the CDN hosted assets can help decrease on disk build size.

To use the assets locally, they need to be copied using a build tool or NPM script. The directory for the local assets must be named assets, which eases the copying process. For example, /public/calcite/assets will work, however /public/calcite-assets will not.

The Calcite Components examples repo demonstrates using local assets in a variety of JavaScript frameworks and build tools. Each example has a README with a framework or build tool specific explanation.

Use dark colors for code blocks
 
1
cp -r node_modules/@esri/calcite-components/dist/calcite/assets/* ./public/assets/

Import the styles

Finally, load the Cascading Style Sheet (CSS). This is also dependent on your framework or build tool, however in many cases it can be imported in JavaScript:

Use dark colors for code blocks
 
1
import "@esri/calcite-components/dist/calcite/calcite.css";

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.