Skip to main content Skip to navigation Skip to search

Clarity Core is a Web Component implementation of the Clarity Design System. Clarity Core provides a set of reusable UI components that work in any JavaScript framework or no framework at all.

Here you will find general installation process that applies regardless of the framework, as well as examples of how to include core components in some of the more popular frameworks.

Installation

1. Install the Clarity Core package from npm

npm install @cds/core @cds/city --save

2. Global Styles

Clarity Core provides a global stylesheet that contains our foundational styles. These global styles include our CSS Custom Properties, layout utilities, and typography utilities.

We also recommend using normalize.css to eliminate any browser differences.

To get started quickly you can install our global single bundle which includes all our global style modules. To install the global styles you can import via CSS Preprocessor like Sass/Less or reference the CSS directly in your HTML.

@import '~normalize.css/normalize.css'; // css reset
@import '~@cds/core/global.min'; // clarity global styles
@import '~@cds/core/styles/module.shims.min'; // non-evergreen browser shims
@import '~@cds/city/css/bundles/default.min'; // load base font
<link href="/node_modules/normalize.css/normalize.css" rel="stylesheet" />
<link href="/node_modules/@cds/core/global.min.css" rel="stylesheet" />
<link href="/node_modules/@cds/core/styles/module.shims.min.css" rel="stylesheet" />
<link href="/node_modules/@cds/city/css/bundles/default.min.css" rel="stylesheet" />

Add the following to your HTML to set the default Clarity body typography.

<body cds-text="body">
  ...
</body>

3. Use Web Components with JavaScript

Currently Core requires a JavaScript bundler to import the required dependencies. Core is compatible with tools such as Webpack, RollupJS, Parcel as well as most Framework CLIs. Additional documentation and examples will be added soon for no build step prototyping.

To use a component, import the component into your JavaScript or TypeScript.

import '@cds/core/button/register.js';

Once imported, the component is automatically registered and ready to use in your HTML and JavaScript.

Hello World
<cds-button status="success">Hello World</cds-button>
<script>
  const button = document.querySelector('cds-button');
  button.action = 'outline';
</script>
Example Apps

Frameworks

Core works in most JavaScript frameworks. For detailed install steps for your framework, see our guides below. More framework guides and demos will be added in the near future.

Angular

To use Clarity Core with Angular follow the package installation instructions. To work fully with the Angular compiler, we have also created an Angular package specifically to help the Angular compiler understand the custom element bindings. Normally custom elements require you to use the CUSTOM_ELEMENTS_SCHEMA (opens new window) which allows non-Angular elements to be processed, but this has the side effect of not supporting strict checks in templates. Our @cds/angular package provides Angular component definitions so that you can use Clarity Core components like normal Angular components.

npm install @cds/angular --save

Then you'll want to add the CdsModule to your AppModule, as well as import the component(s) you plan to use.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CdsModule } from '@cds/angular';
import { AppComponent } from './app.component';

import '@cds/core/alert/register.js';

@NgModule({
  imports: [BrowserModule, CdsModule],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
})
export class AppModule {}

To set properties on a Web Component use the Angular [property] binding syntax. To listen to events use the Angular (event) binding syntax.

<!--
- status - attribute style hook
- [closable] - setting the 'closable' property on the element
- (closeChange) - listen for the 'closeChange' custom event
-->

<cds-alert status="info" [closable]="true" (closeChange)="log($event.detail)">
  Hello World
</cds-alert>
Example Angular App

Vue

To use Clarity Core with Vue follow the package installation instructions.

Once installed import the component into your JavaScript file.

import '@cds/core/alert/register.js';

To set properties on a Web Component use the Vue :property binding syntax. To listen to events use the Vue @event binding syntax.

<!--
Example of a alert web component in Vue
- status - attribute style hook
- :closable - setting the 'closable' property on the element
- @closeChange - listen for the 'closeChange' custom event
-->

<cds-alert status="info" :closable="true" @closeChange="log"> Hello World </cds-alert>`
Example Vue App

React

To use Clarity Core with React follow the package installation instructions.

In addition, because React doesn't fully interoperate with custom elements (opens new window) we have developed a library of React wrapper components (opens new window) which must be installed in addition to the core package.

npm install @cds/react --save

Once installed import the component into your JavaScript or Typescript file.

import { CdsAlert } from '@cds/react/alert';

Web Components are kebab cased tag name which in @cds/react will be converted to Pascal case. For example, <cds-alert> element will be <CdsAlert> in React. Our event props will follow the React naming convention of camel case for props and start with on. The custom event closeChange will be onCloseChange in React.

/*
Example of an alert component in React
- status - attribute/property style hook
- closable - setting the 'closable' property on the element
- onCloseChange - listen for the 'closeChange' custom event
*/

<CdsAlert status="info" closable={this.state.closable} onCloseChange={this.log}>
  Hello World
</CdsAlert>

Using refs

In React refs (opens new window) provide a way to access DOM nodes or React elements created in the render method. Because web components' lifecycle lives outside of react's lifecycle our components provide a way to use refs when the underlying web component has finished rendering:

import React from 'react';
import { CdsButton } from '@cds/react/button';

export default class App extends React.Component<{}, {}> {
  buttonRef: React.RefObject<CdsButton>;

  constructor(props: any) {
    super(props);
    this.buttonRef = React.createRef<CdsButton>();
  }

  componentDidMount() {
    this.buttonRef.current.nativeElement.then(element => {
      element.focus();
    });
  }

  render() {
    return (
      <div>
        <CdsButton ref={this.buttonRef}>My button</CdsButton>
      </div>
    );
  }
}
Example React App

Preact

To use Clarity Core with Preact follow the package installation instructions.

Once installed import the component into your JavaScript file.

import '@cds/core/alert/register.js';

To listen to custom events in Preact the event must be prefixed with on.

/*
Example of an alert web component in Preact
- status - attribute style hook
- closable - setting the 'closable' property on the element
- onCloseChange - listen for the 'closeChange' custom event
*/

<cds-alert status="info" closable={this.state.closable} onCloseChange={this.log}>
  Hello World
</cds-alert>

AngularJS (> 1.8.0)

To use Clarity Core with Angular JS you must be on AngularJS version 1.7.3 or later.

To use Clarity Core with AngularJS follow the package installation instructions.

Once installed import the register path in your JavaScript.

import angular from 'angular';
import '@cds/core/alert/register.js';
import '@cds/core/button/register.js';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    <cds-button status="primary" ng-click="$ctrl.showAlert = true">show alert</cds-button>

    <cds-alert ng-if="$ctrl.showAlert" ng-prop-status="$ctrl.status" ng-on-close_change="$ctrl.showAlert = false" closable>
      This is an alert message.
    </cds-alert>
  `,
  controller: function () {
    this.status = 'danger';
    this.showAlert = false;
  },
});

To set properties on a Web Component use the ng-prop directive (opens new window). To listen to custom events use the ng-on directive (opens new window).

<!--
- status - attribute style hook
- ng-prop-closable - setting the 'closable' property on the element
- ng-on-close_change - listen for the 'closeChange' custom event
-->

<cds-alert status="info" ng-prop-closable="$ctrl.closable" ng-on-close_change="$ctrl.log($event.detail)">
  Hello World
</cds-alert>
Example AngularJS App

Advanced Installation (Optional)

Base Font Size

By default, Clarity has a default base font size of 20px/125%. This means that if you use CSS relative values such as rem, then 1rem is equal to 20px. If you have an existing application that uses the default browser font size (16px = 1rem) then add the following to your root HTML tag.

<html cds-base-font="16">
  ...
</html>

This setting will configure Clarity to adjust its CSS custom properties to be relative to the browser default of 16px without noticeable differences. This setting will also allow applications to more easily adopt Clarity without requiring to change the global base font size.

Global CSS Performance

If you would like to reduce your bundle sizes, you can choose a subset of the global styles by importing the module individually. However, we recommend at a minimum, including normalize and the reset module, to ensure consistent styling across browsers.

@import '~normalize.css/normalize.css';
@import '@cds/core/styles/module.reset.min.css';
@import '@cds/core/styles/module.tokens.min.css';
@import '@cds/core/styles/module.layout.min.css';
@import '@cds/core/styles/module.typography.min.css';
@import '@cds/core/styles/module.shims.min.css';
@import '@cds/city/css/bundles/default.min.css';