Core concepts

Calcite Components is a library of reusable web components for building web apps with minimal code. With Calcite Components, you can quickly build on-brand, lightweight, and accessible web applications.

Web components are a native browser standard, and many of the technical concepts necessary to develop with Calcite Components are not specific to the library. This page provides an introduction to key web concepts, which are necessary for effective development. For further reading, all of the concepts on this page can be found on MDN Web Docs and other web standard documentation sources.

Custom elements

Custom elements are part of the Web Components standards, which work across modern browsers using any JavaScript library or web framework with HTML. Custom elements encapsulate functionality, which prevents conflicts with the rest of your code.

Calcite Components are custom elements and can be used similar to native HTML elements. For instance:

1
<calcite-action-bar layout="horizontal"></calcite-action-bar>

Slots

Slots are placeholder elements that allow you to add your own content by referencing the slot's name. Slots are a common web components concept, and chances are you already use them. For example, take the following HTML:

1
2
3
4
5
<select>
  <option value="platypus">Platypus</option>
  <option value="sloth">Sloth</option>
  <option value="armadillo">Nine-banded armadillo</option>
</select>

In web component terminology, the option elements are placed in select's default slot. Additionally, the "Platypus", "Sloth", and "Nine-banded armadillo" text is placed in option's respective default slots.

Many Calcite Components also utilize default slots. For instance, in the calcite-action-bar below, the calcite-action elements are added to the default slot:

1
2
3
4
5
<calcite-action-bar layout="horizontal">
  <calcite-action text="Add" icon="plus" text-enabled></calcite-action>
  <calcite-action text="Save" icon="save" text-enabled></calcite-action>
  <calcite-tooltip slot="expand-tooltip">Toggle Action Bar</calcite-tooltip>
</calcite-action-bar>

In many cases, a default slot is all that is needed. However, as components become more complicated, the need arises to position and style child elements differently. This is where named slots come into play. In the example above, a calcite-tooltip is placed into the Action Bar's expand-tooltip slot. This informs the component that the tooltip should be handled differently than the elements in the default slot.

If a component has slots, they will be listed in the documentation, such as the slots for calcite-card. You can also learn more about slots on MDN.

Shadow DOM

Custom elements are encapsulated, which keeps their markup structure, style, and behavior hidden and separate from other code on the page. The Shadow DOM is the mechanism that encapsulates custom elements. As a result, Shadow DOM hides and separates a web component's DOM elements, so they are rendered in the browser, but do not clash with the rest of your code.

The Shadow DOM encapsulation creates persistent styling and functionality across your applications, enabling your users to have a consistent user experience.

CSS variables

Calcite Components provide CSS variables to override styles. Due to web components' shadow DOM, the styles can not be easily altered without CSS variables. There are CSS variables for tokens that are used throughout the design system, including color and typography.

Additionally, some Calcite Components have their own CSS variables to change component-specific styles. These CSS variables can be found in a component's documentation, such as the CSS variables for calcite-loader.

An example use case is swapping the foreground and text colors in calcite-notice using CSS variables.

1
2
3
4
calcite-notice {
  --calcite-color-foreground-1: #151515;
  --calcite-color-text-1: #ffffff;
}

The CSS variable MDN documentation provides a detailed explanation of the functionality.

Loading components

Web components start as plain HTML elements, and are upgraded as soon as their implementations are defined in the browser. Calcite Components are automatically defined when they are imported and used in an application. However, sometimes it is necessary to wait until a component is defined before executing specific code.

Hydration

Calcite Components provide the option to add a flag when a component and all of its child components have finished hydrating. This helps prevent any flash of unstyled content (FOUC) as various components are asynchronously loaded and rendered. In Calcite Components, the calcite-hydrated attribute is added to components once they are hydrated, and is useful when debugging your application.

When defined

The whenDefined() method of the customElementRegistry interface returns a promise, which is fulfilled when the specified element is defined.

Once the promise is fulfilled, you can run code that requires the component to be defined, like so:

1
customElements.whenDefined("calcite-button").then(() => document.querySelector("calcite-button").setFocus());

Component on ready

To determine when a component is rendered, you can use the componentOnReady() method. The method returns a Promise that resolves after the component is rendered and can be accessed in the DOM. It is recommended to ensure a component is loaded before using its methods, or when one component is dependent on another.

For example, you may want to display calcite-loader until other component(s) finish rendering:

1
2
await document.querySelector("calcite-alert").componentOnReady();
document.querySelector("calcite-loader").hidden = true;

1
2
3
4
5
(async () => {
  await customElements.whenDefined("calcite-alert");
  await document.querySelector("calcite-alert").componentOnReady();
  document.querySelector("calcite-loader").hidden = true;
})();

Calling a component's method as the callback of requestAnimationFrame ensures the user interface updates with the component's state. For example, if you want to set the current step for calcite-stepper based on the user's browsing history, you can use the goToStep() method:

1
2
3
4
5
(async () => {
  await customElements.whenDefined("calcite-stepper");
  const el = await document.querySelector("calcite-stepper").componentOnReady();
  requestAnimationFrame(() => el.goToStep(3));
})();

Events

Calcite Components creates and triggers events using the CustomEvent() constructor.

CustomEvent behaves similarly to Event, which is emitted by HTML elements, such as when clicking a button. For example, you can still access the element in the event payload's target property.

You can view a component's documentation page to determine whether it has any events, such as the calcite-pagination event. For example:

1
2
3
document.addEventListener("calcitePaginationChange", event => {
  console.log(`Starting item number on the page: ${event.target.startItem}`);
});

Open and close event behavior

Some components are positioned and displayed when toggling the open boolean property. When the open property's value changes, due to user interaction or programmatic control, the component emits corresponding events to signal the change.

For example, when Dialog is opened or closed, it emits calciteDialogOpen and calciteDialogClose events.

Some components like Block use the expanded property instead of open, but follow a similar pattern for event emission.

This design ensures consistency with transition animations and timing, but it may lead to confusion if you're expecting events to only reflect user interaction.

There is no built-in way to distinguish whether an open or close event has been triggered through user interaction, such as clicking a button, or programmatically, such as setting element.open = false. However, it is possible to track programmatic changes using a flag.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
let isProgrammaticClose = false;

const dialog = document.querySelector("calcite-dialog");
const cancelButton = document.getElementById("dialog-cancel-button");

// Listen for the close event
dialog.addEventListener("calciteDialogClose", () => {
  if (isProgrammaticClose) {
    console.log("Dialog closed programmatically");
  } else {
    console.log("Dialog closed by user interaction");
  }

  // Always reset the flag after handling the event
  isProgrammaticClose = false;
});

// Close the dialog programmatically
function closeDialog() {
  isProgrammaticClose = true;
  dialog.open = false;
}

cancelButton.addEventListener("click", () => {
  closeDialog();
});

Global configuration

Version

Since 2.10, developers can use the calciteConfig global variable to detect the Calcite version at runtime.

1
window.addEventListener("load", () => console.log(window.calciteConfig.version));

Log messages

Since 2.11, key messages are logged to the console, such as component deprecations. Developers can opt to remove messaging from production environments and builds using calciteConfig:

1
2
3
var calciteConfig = {
  logLevel: "off"
};

Forms

Each component within a form must be populated with a name attribute in order to pass the value properly on form submission. For instance, adding name attributes to Input Date Picker and Text Area:

1
2
3
4
5
6
7
8
9
10
11
<form>
  <calcite-label>
    Observation date:
    <calcite-input-date-picker name="observation-date"></calcite-input-date-picker>
  </calcite-label>
  <calcite-label>
    Observation notes:
    <calcite-text-area name="observation-notes" placeholder="Observation notes" max-length="250"></calcite-text-area>
  </calcite-label>
  <calcite-button type="submit">Submit</calcite-button>
</form>

For additional considerations with forms, explore accessibility with forms.

Form validation

Form validation includes the use of the status, validationMessage, and validationIcon properties. The properties support default and custom validation messages and icons when a component's status property is "invalid".

Validation constraints

To set up custom constraints:

• Create a validation constraints array to define custom constraints, messages, and icons for specific fields using their id.

• Utilize a function like setCustomValidity to set the validationMessage, validationIcon, and status on the respective fields.

• Use an event listener to check the user input against the predefined validation constraints. If the user input does not meet the specified constraints, a custom validation message is set using the setCustomValidity function.

Patterns

The use of the pattern attribute can support constraints used for form validation. When used, it defines a regular expression that the input value must match in order for the form to be considered valid. For instance, defining validationMessages and validationIcons that will be displayed when a specified part of the pattern is matched.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
  <calcite-label>
    Full Name:
    <calcite-input-text pattern="[a-zA-Z]{1,15}\s[a-zA-Z]{1,15}" placeholder="John Doe" name="fullName" id="fullName"
      validation-message="Full name is a required field." validation-icon="exclamation-mark-triangle" status="invalid"
      required></calcite-input-text>
  </calcite-label>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
    // Defines an array of objects with validation constraints, icons, and messages for fields.
    const validationConstraints = [
      {
        id: "fullName",
        patterns: [
          {
            value: /^\w{16,}/,
            message: "First name must not be longer than 15 letters.",
            icon: "exclamation-mark-triangle-f"
          },
          {
            value: /^\w+\s\w{16,}$/,
            message: "Last name must not be longer than 15 letters.",
            icon: "exclamation-mark-triangle-f"
          },
          {
            value: /^\w*[^\s]\w*$/,
            message: "First and last name are required.",
            icon: "exclamation-mark-triangle-f"
          },
          {
            value: /^[a-zA-Z]*$/,
            message: "First and last name are required.",
            icon: "exclamation-mark-triangle-f"
          },
        ]
      }
    ];

    // Specifies the custom validationMessage, validationIcon, and status when the user interacts with the component.
    function setCustomValidity(el, message, icon) {
      if (message) {
        el.validationMessage = message;
        el.validationIcon = icon;
        el.status = "invalid";
      } else {
        el.validationMessage = "";
        el.validationIcon = false;
        el.status = "idle";
      }
    }

    window.onload = () => {
      // Adds event listeners to form elements to update the validationMessage, validationIcon, and status on blur.
      validationConstraints.forEach(constraint => {
        document.querySelector(`#${constraint.id}`)?.addEventListener("blur", ({ target }) => {
          // Set a custom validationMessage for the 'pattern' constraint.
          if (typeof constraint?.patterns === "object" && constraint?.patterns?.length > 0) {
            for (const pattern of constraint?.patterns) {
              if (target.value?.match(pattern?.value)) {
                setCustomValidity(target, pattern?.message, pattern?.icon ?? true);
                return;
              }
            }
          }
          // Clear the custom validation message if all of the constraints are met.
          setCustomValidity(target, "");
        });
      });
    };

Modes

Calcite Components provides light and dark modes, which can be changed using their corresponding CSS classes: calcite-mode-light and calcite-mode-dark. There is also a calcite-mode-auto class which defers to the browser's prefers-color-scheme CSS media query to decide whether the light or dark mode will be used.

Setting the mode class on an element changes all of its child nodes as well. Therefore, to switch the entire application from light to dark, you can do the following:

1
2
3
<body class="calcite-mode-dark">
  <!-- Your application content -->
</body>