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.
<cds-button status="success">Hello World</cds-button>
<script>
const button = document.querySelector('cds-button');
button.action = 'outline';
</script>
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.
Installing Clarity Core using Angular CLI (recommended)
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>
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>`
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>
);
}
}
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 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>
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';