Skip to main content Skip to navigation Skip to search

Developing

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. The paths listed below may be different depending on your build tooling

// Sass file syntax
@import '~modern-normalize/modern-normalize.css'; // css reset
@import '~@cds/core/global.min.css'; // clarity global styles
@import '~@cds/city/css/bundles/default.min.css'; // load base font
<!-- HTML file syntax -->
<link href="/node_modules/modern-normalize.css/modern-normalize.css" rel="stylesheet" />
<link href="/node_modules/@cds/core/global.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

We have created an Angular package that helps 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.

You can use the Angular CLI to set up Clarity Core in an Angular project.

ng add @cds/angular

Manually adding Clarity Core to an Angular project

Alternatively, you can set up Clarity Core manually.

First, follow the package installation instructions.

Then, install @cds/angular.

npm install @cds/angular --save

Finally, add the CdsModule to your AppModule.

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

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

Using Clarity Core components

Once you have Clarity Core set up in your project, 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. You'll repeat these steps for any additional components that you use.

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 '~modern-normalize.css/modern-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/city/css/bundles/default.min.css';