Getting started

Components

The components are shared web components for Esri's design framework built with Stencil JS. The component library contains fundamental components such as alerts, buttons, inputs, modals, and much more. To see the components in action, view full component documentation .

Components via CDN

The most common approach for accessing web components is to use the hosted version. Reference the JS and CSS from our CDN to start using the components in your app. Components can be loaded via two <script> tags in the head of your HTML document:

  
1
2
<script type="module" src="https://js.arcgis.com/calcite-components/1.0.0-beta.63/calcite.esm.js"></script>
<script nomodule="" src="https://js.arcgis.com/calcite-components/1.0.0-beta.63/calcite.js"></script>

Browsers that support modules will load the first, while older browsers will load the second, bundled version.

Once these script tags are added, components can be used just like any other HTML element. Only components that are actually used will be loaded.

Styles

You will also need to explicitly load the calcite.css file:

 
1
<link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/1.0.0-beta.63/calcite.css" />

NPM installation

 
1
npm install --save @esri/calcite-components

Webpack

If you already have a Webpack build for your project, you can use @stencil/webpack to add calcite-components to your bundle.

After installing calcite-components, install the plugin as a dev dependency:

 
1
npm install --save-dev @stencil/webpack

Then import and call the plugin in webpack.config.js:

       
1
2
3
4
5
6
7
const stencil = require('@stencil/webpack');
module.exports = {
  ...
  plugins: [
    new stencil.StencilPlugin()
  ]
}

Lastly, add the import in your main bundle js (or ts) file:

 
1
import "@esri/calcite-components/dist/calcite.js";

This will add the initial stencil loader to your bundle, and copy over the actual component code to the output directory you've configured for Webpack. Components will still be lazy-loaded as they are needed. Note: you must use the .js file path for the Webpack plugin to work correctly, even if your bundle file is a TypeScript file.

TypeScript

Stencil provides a full set of typings for all the components in this repo. To make TypeScript aware of these components, just import the library:

 
1
import "@esri/calcite-components";

This will provide autocomplete of component names/properties, as well as additional HTML element types:

         
1
2
3
4
5
6
7
8
9
// created elements will implicitly have the correct type already
const loader = document.createElement("calcite-loader");
document.body.appendChild(loader);
loader.isActive = true;

// you can also explicitly type an element using the generated types
// the type name will always be formatted like HTML{CamelCaseComponentName}Element
const loader = document.querySelector(".my-loader-element") as HTMLCalciteLoaderElement;
loader.isActive = true;

TypeScript with Preact

For Preact applications using TypeScript, you must add an additional file to your tsconfig.json:

   
1
2
3
"files": [
  "node_modules/@esri/calcite-components/dist/types/preact.d.ts"
],

This allows you to use custom tags and provides auto-complete for calcite-components. See the Preact + TypeScript example for more details.

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