Getting Started with Vanilla Components

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";
Copy code

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.

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;
Copy code

4. 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);
});
Copy code

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.

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';
Copy code

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>
Copy code

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.

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);
});
Copy code

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.

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;
Copy code

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

declare var DDS: any
Copy code

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>
Copy code

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

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

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

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>
  );
}
Copy code

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>
  );
}
Copy code

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);
  }
}
Copy code

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>
Copy code

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";
Copy code

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;
Copy code

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;
Copy code

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
Copy 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>
Copy code

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.