Framework integration

Calcite Components easily integrates with JavaScript frameworks and build tools, and an example repo is provided to help get started. Each example contains framework specific information. If there isn't an example using your framework or build tool of choice, then you can follow the instructions to get started using NPM.

TypeScript

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

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

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

Use dark colors for code blocks
         
1
2
3
4
5
6
7
8
9
// created elements will implicitly have the correct type
const loader = document.createElement("calcite-loader");
document.body.appendChild(loader);
loader.active = 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.active = true;

Calcite Components React

Calcite Components React is a set of React components that wrap the web components. React uses a synthetic event system, so the custom events emitted from the web components won't work with JSX in React. For example, to update a value when the calcite-slider component changes, using the standard web components, you need to save a ref to the element and add an event listener:

Use dark colors for code blocks
      
1
2
3
4
5
6
const sliderEl = useRef(null);
const [sliderValue, setSliderValue] = useState(50);

useEffect(() => {
  sliderEl.current.addEventListener("calciteSliderUpdate", event => setSliderValue(event.target.value));
}, [sliderEl]);

Using @esri/calcite-components-react, the events are connected for you:

Use dark colors for code blocks
  
1
2
const [sliderValue, setSliderValue] = useState(50);
<CalciteSlider onCalciteSliderUpdate={event => setSliderValue(event.target.value)} />;

If you're using TypeScript, you'll also get increased type safety for your event listeners, props, etc.

Usage

To install @esri/calcite-components-react, run:

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

The package includes the compatible version of the web component library as a dependency, so no need to install @esri/calcite-components separately. Next, follow the instructions to get started using NPM. Lastly, import the wrapped React components you wish to use in the application:

Use dark colors for code blocks
 
1
import { CalciteButton, CalciteIcon, CalciteSlider } from "@esri/calcite-components-react";

For a complete setup, check out the React example.

Gotchas

Passing boolean props to a wrapped React component converts the value to a string. There is a stencil issue for the problem. In practice, disabled={false} will end up as disabled={"false"}, which is truthy. The workarounds for falsy boolean prop values are:

  1. Don't set the prop
  2. Use undefined instead of false

For example, this CalcitePickListItem will be selected:

Use dark colors for code blocks
  
1
2
const selected = false;
<CalcitePickListItem key={0} label="Fried Egg Jellyfish" value="jellyfish" selected={selected}></CalcitePickListItem>

However, none of these items will be selected:

Use dark colors for code blocks
    
1
2
3
4
const selected = false;
<CalcitePickListItem key={1} label="Satanic Leaf-Tailed Gecko" value="gecko"></CalcitePickListItem>
<CalcitePickListItem key={2} label="Red-Lipped Batfish" value="batfish" selected={undefined}></CalcitePickListItem>
<CalcitePickListItem key={3} label="Star-Nosed Mole" value="mole" selected={selected ? true : undefined}></CalcitePickListItem>

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