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:
This will provide autocomplete of component names/properties, as well as additional HTML element types:
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:
Using @esri/calcite-components-react
, the events are connected for you:
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:
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 Calcite's React components you wish to use in the application:
For a complete setup, check out the React example.
Gotchas
Boolean attributes
Passing boolean
attributes to Calcite's React components converts the value to a string
, which is due to React compatibility issues with web components. There are Stencil and React issues for the problem. In practice, disabled={false}
will end up as disabled={"false"}
, which is truthy. The workarounds for falsy boolean attribute values are:
- Don't set the attribute
- Use
undefined
instead offalse
For example, this Calcite
will be selected:
However, none of these items will be selected:
Configuring Jest
If configuring Jest, you will need to add @esri/calcite-components-react
to the transform
in the Jest configuration file: