Getting Started with Vanilla Components

Vanilla components are built without a framework; they are pure HTML, CSS, and JavaScript. This flexibility makes them compatible with any framework, including Angular, React, VUE, and Svelte.


What's new

These components are JavaScript with no dependencies. They can be embedded into any project because of their inherent flexibility, which is why the engineering team is prioritizing their development. Component code and developer documentation are now hosted in Storybook, an interactive UI tool that isolates components so that they can be built and run independently.

Here’s what else has changed from v1 to v2:

  • Each component has been completely rebuilt, with scalability as a fundamental consideration.
  • Members of the Accessibility, Globalization, and Design teams review each component. All published components meet WCAG 2.1 requirements.
  • Similarities to Bootstrap were removed, and the engineering team now follows BEM methodology.

Please note that because of these changes, we do not recommend combining v2 and v1 components within the same project or application.

npm versus CDN

Consider the following when choosing between installation methods:

Installation methodConsiderations
npmThis is the most popular installation method. DDS assets are included via compile time, which can reduce JS and CSS dependencies because they are selected on a per-component basis. npm allows for tree shaking, code minification, and code obfuscation.
CDNCDNs reduce bandwidth and improve website load times by operating through a network of linked servers. The CDN assets include JavaScript and CSS for each component. Use this method to make a proof of concept.

Installation via npm

All Vanilla components are available through npm, which is a package manager for JavaScript. Use the following command in your terminal to install the Dell Design System node module from Dell’s Artifactory:

npm install --save-dev @dds/components --registry=http://artifacts.dell.com/artifactory/api/npm/dx-npm-prod/

Note that the –registry option in the code snippet instructs your computer to look in Dell’s artifact library. If omitted, your computer will attempt to install components through the npm public repository, which is not synchronized with Dell’s.

You will need to add an .npmrc file to your project in the same directory where your package.json file is located (usually the root of your project).

SASS

To incorporate component styles, use the following SCSS files:

@use "@dds/components/src/scss/dds-reboot.scss";
@use "@dds/components/src/scss/dds-fonts.scss";
@use "@dds/components/src/scss/dds-icons.scss";
@use "@dds/components/src/scss/dds-helpers.scss";
@use "@dds/components/src/scss/dds-main.scss";

Reboot: Resets the browser defaults to the Dell Design System styles.
Fonts: Loads the Dell Design System font family. The file contains links for woff, woff2, eot, and ttf. All fonts are retrieved from the CDN.
Icons as fonts (optional): Loads the Dell Design System icons as a font family. The file contains links for woff, woff2, eot, and ttf. All fonts are retrieved from the CDN. This is not required if your application does not consume icons as fonts.
Helpers (optional): Provides helper classes to modify layout with CSS. They are used to change alignment, position, rotation, sizing, spacing, transition, and visibility.
Main: Contains only component styling; does not include styling for fonts or icons.

npm usage and initialization

The @dds/components package contains the classes for each individual DDS component. To use a specific component, follow these steps:

  1. Visit Storybook and navigate to the component you’d like to use.
  2. In Storybook, copy the component’s HTML.
  3. Import the component from the DDS package using the following script. You’ll need to replace with the name of the component you’re importing.
import { <Component> } from @dds/components;
  1. Initialize the component. This step is only required for certain components. Component-specific initialization instructions can be found in Storybook under the Docs tab for the respective component. Remember to replace “Component” with the name of the component you’re importing.
[].forEach.call(document.querySelectorAll('[data-dds="Component"]'), function (element) {
 new Component(element);
});

Note: Be sure to run the initialization code after the HTML is rendered and the JavaScript is validated. If you’re using Angular, initialize the component on the ngAfterViewInit directive. For React, initialize the component on componentDidMount or similarly, a useEffect.

TypeScript support via npm

If your application is using Typescript, be sure to declare the Dell Design System module. Doing so allows imported components from @dds/components to be used inside your application.

Add the following code snippet to an existing index.d.ts file in your application. Alternately, create one and make sure that the TypeScript is including that document.

declare module '@dds/components';

Installation via CDN

The runtime CDN, located on Akamai, contains the Dell Design System assets with JavaScript and CSS for each component, including fonts and icons.

CSS and JavaScript

To load the Dell Design System styles from the CDN, place the following style sheet link elements and JavaScript into your element. Make sure to insert them at the beginning, before any other style sheets and JavaScript.

<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.34.0/css/dds-reboot.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.34.0/css/dds-fonts.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.34.0/css/dds-icons.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.34.0/css/dds-helpers.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.34.0/css/dds-main.min.css" />
<script src="https://dds.dell.com/components/2.34.0/js/index.min.js"></script>

Reboot: Resets the browser defaults to the Dell Design System styles.
Fonts: Loads the Dell Design System font family. The file contains links for woff, woff2, eot, and ttf.
Icons as fonts (optional): Loads the Dell Design System icons as a font family. The file contains links for woff, woff2, eot, and ttf. This is not required if your application does not consume icons as fonts.
Helpers (optional): Provides helper classes to modify layout with CSS. They are used to change alignment, position, rotation, sizing, spacing, transition, and visibility.
Main: Contains only component styling; does not include styling for fonts or icons.
index.min.js: Loads all DDS component classes into a window variable called DDS.

CDN usage and initialization

To use a specific component, follow these steps:

  1. Visit Storybook and navigate to the component you’d like to use.
  2. In Storybook, copy the component’s HTML.
  3. Initialize the component. After you’ve installed the CDN version of Dell Design System, you will have access to a window variable called DDS which contains each component. This step is only required for certain components. Component-specific initialization instructions can be found in Storybook under the Docs tab for the respective component
[].forEach.call(document.querySelectorAll('[data-dds="Component"]'), function (element) {
    new DDS.Component(element);
});

Note: Be sure to run the initialization code after the HTML is rendered and the JavaScript is validated.

If you’re using Angular, initialize the component on the ngAfterViewInit directive. Visit GitLab to view an example project that integrates Vanilla components within an Angular application.

For React, you can define a global variable such as const DDS = window.DDS;

Alternately, you can initialize the component on componentDidMount or similarly, a useEffect. All DDS JS functions will be available under the window.DDS property.

TypeScript support via CDN

If your application is using TypeScript to pull in the JavaScript from our CDN, be sure to declare Dell Design System as “any” in your index.ts file so that the imported DDS library variable can be used inside your application.

var DDS:any;

For Angular, place the following code snippet before the component line and after the import lines:

declare var DDS: any

Storybook demo

Storybook

Storybook

View developer documentation on Dell's Storybook.

Logger

To enable or disable DDS error messages or warnings, use the function DDS.debug(true|false):

DDS.debug(true);

To customize the kinds of errors that are exposed, an array of error types can be used:

DDS.debug(true, ["error", "warn"]);

By default, all console messages are shown and all the below types are accepted:

["log", "info", "warn", "table", "error"];

Optionally, debug messages can be enabled with the use of a query string:

https://exampleUrl.dell.com?dds-debug=true

This option shows all message types, but does not accept custom options and should be only used in a development environment.

Component usage

In VanillaJS projects

Each component needs to be initialized. This is an essential step needed after the index.js is loaded on CDN installations. In most cases, the initialization code should look like the example below.

In the markup, create the required structure according to the documentation for each component. For example:

<div data-dds="component" id="unique-id">...</div>

Get the element ID and initialize the component following the specific component documentation. For example:

const element = document.getElementById("unique-id");
DDS.ComponentName(element);

The initialization code needs to run after the HTML is rendered and the JavaScript is validated.

In React projects

The node module contains all the necessary files for each component. To use a specific component, simply include the following code in your .js or .ts file.

Below is a small example of using the text area component within the ESM scenario (ES Modules), which is very common in React applications. It is started through the useEffect hook, similar to componentDidMount and componentDidUpdate.

import { TextArea } from "@dds/components";
import { useEffect } from "react";

export function MyTextArea() {
  useEffect(() => {
    const element = document.getElementById("my-text-area");
    new TextArea(element);
  }, []);

  return (
    <div id="my-text-area" className="dds__text-area__container" data-dds="text-area">
      <div className="dds__text-area__header">
        <label id="text-area-label-359524269" htmlFor="text-area-control-359524269">
          Message
        </label>
      </div>
      <div className="dds__text-area__wrapper">
        <textarea
          className="dds__text-area"
          name="text-area-control-name-359524269"
          id="text-area-control-359524269"
          data-maxlength="10"
          aria-required="true"
          aria-labelledby="text-area-label-359524269 text-area-helper-359524269"
          required=""
        ></textarea>
        <small id="text-area-helper-359524269" className="dds__input-text__helper">
          Helper Text
        </small>
        <small id="text-area-error-359524269" className="dds__invalid-feedback">
          Error Message
        </small>
      </div>
    </div>
  );
}

Some components don’t require JavaScript and therefore don’t need to be started like the text area component. A good example is the button component:

export function MyButton() {
  return (
    <button className="dds__button dds__button--primary dds__button--lg" type="button">
      Send
    </button>
  );
}

In Angular projects

Visit Getting Started with Angular to view documentation about Dell Design System Angular framework.

For Angular projects, initialize the component on the ngAfterViewInit directive. For example:

import { AfterViewInit, Component } from "@angular/core";
import { TextArea } from "@dds/components";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.scss"],
})
export class AppComponent implements AfterViewInit {
  title = "my-angular-app";

  ngAfterViewInit(): void {
    const element = document.getElementById("my-text-area");
    new TextArea(element);
  }
}

With the component initialized, you can use it in your HTML template. For example:

<div>
  <div id="my-text-area" class="dds__text-area__container" data-dds="text-area">
    <div class="dds__text-area__header">
       <label id="text-area-label-359524269" htmlFor="text-area-control-359524269">
        Message
      </label>
    </div>
    <div class="dds__text-area__wrapper">
      <textarea
        class="dds__text-area"
        name="text-area-control-name-359524269"
        id="text-area-control-359524269"
        data-maxlength="10"
        aria-required="true"
        aria-labelledby="text-area-label-359524269 text-area-helper-359524269"
        required=""
      ></textarea>
      <small id="text-area-helper-359524269" class="dds__input-text__helper">
        Helper Text
      </small>
      <small id="text-area-error-359524269" class="dds__invalid-feedback">
       Error Message
      </small>
    </div>
  </div>
</div>

With Typescript

If your application is using Typescript, be sure to declare the Dell Design System module. Doing so allows imported components from @dds/components to be used inside your application.

Add the following code snippet to an existing index.ts file in your application. Alternately, create one and make sure that the TypeScript is including that document.

declare module "@dds/components";

If your application is using Typescript to pull in the JavaScript from our CDN, be sure to declare Dell Design System as “any” in your index.js file so that the imported Dell Design System library can be used inside your application.

// Add this to projects index.js
var DDS: any;

Once you’ve declared the Dell Design System library, making it available to your application, you can import components like normal.

For Angular, place the following code snippet before the component line and after the import lines:

declare var DDS: any;

With ECMA Script Modules (ESM)

All of the DDS components can be imported as ES Modules. ESM is the official and most up-to-date module system in the JavaScript ecosystem.

One of the major advantages of importing the DDS components as ES Modules is that it allows bundlers, such as Webpack, Rollup, and ESBuild, to clean up or remove unused code. In other words, all unused code from the DDS will be removed automatically, which can drastically reduce the size of your application’s bundle and improve loading times.

For example, if the action menu is the only component that you are using in your application, only the code that is necessary for the action menu to work will be imported. The remaining code from the other components will be removed.

To leverage our ESM output via NPM, you should import components from the esm directory, as seen in the example below:

import { ActionMenu } from "@dds/components/esm";

// application code

If your package.json file contains the “type”=“module” property, your project will automatically use the ESM version over the UMD version when importing components via import { ActionMenu } from “@dds/components”;.

In order to use the DDS ESM output via CDN, a script with type=“module” must be used:

<body>
  <!-- application code -->

  <script type="module">
    import { ActionMenu } from "https://dds.dell.com/components/2.34.0/js/esm/index.min.js";
    // application code
  </script>
</body>

Keep in mind that the automatic clean up of unused code, as previously described, is not available through CDN as that automation occurs during bundling.