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 newCopy link to this section
Copy link to this section
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 CDNCopy link to this section
Copy link to this section
Consider the following when choosing between installation methods:
| Installation method | Considerations |
|---|---|
| npm | This 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. |
| CDN | CDNs 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 npmCopy link to this section
Copy link to this section
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/
Copy codeNote 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";
Copy codeReboot: 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 dozens of utility classes for showing, hiding, aligning, and spacing content.
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:
- Visit Storybook and navigate to the component you’d like to use.
- In Storybook, copy the component’s HTML.
- 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- 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 codeNote: 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';
Copy codeInstallation via CDNCopy link to this section
Copy link to this section
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.25.1/css/dds-reboot.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.25.1/css/dds-fonts.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.25.1/css/dds-icons.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.25.1/css/dds-helpers.min.css" />
<link rel="stylesheet" crossorigin href="https://dds.dell.com/components/2.25.1/css/dds-main.min.css" />
<script src="https://dds.dell.com/components/2.25.1/js/index.min.js"></script>
Copy codeReboot: 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 dozens of utility classes for showing, hiding, aligning, and spacing content.
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:
- Visit Storybook and navigate to the component you’d like to use.
- In Storybook, copy the component’s HTML.
- 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 codeNote: 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;
Copy codeFor Angular, place the following code snippet before the component line and after the import lines:
declare var DDS: any
Copy codeResourcesCopy link to this section
Copy link to this section