Getting Started
Choose your approach: CDN for quick starts, npm for production
Getting Started
Decision Matrix
Compare the three approaches to find the right fit for your project.
| Approach | Setup Time | Bundle Size | Tree-shaking | Best For |
|---|---|---|---|---|
| CDN | ~2 min | Full download | No | Prototyping and simple sites |
| npm (grouped imports) | ~15 min | Moderate | Good | Standard production apps |
| npm (individual imports) | ~30 min | Smallest | Maximum | Performance-critical apps |
Track A: CDN / No Build Tools
The fastest way to start using UMD components -- no build tools, no package manager, just HTML.
Step 1 -- Add the Components CDN Script
This single script auto-registers every <umd-element-*> web component.
<script src="https://unpkg.com/@universityofmaryland/web-components-library/dist/cdn.js"></script>Step 2 -- Add the Static CSS Stylesheet
A pre-compiled CSS file that provides typography, layout utilities, spacing classes, and design tokens as CSS custom properties. This replaces the older JavaScript-based style injection approach.
<link rel="stylesheet" href="https://unpkg.com/@universityofmaryland/web-styles-library/dist/css/styles.min.css">Step 3 -- Write HTML
Use <umd-element-*> custom element tags and UMD CSS utility classes in your markup.
<umd-element-hero data-display="overlay" class="umd-layout-space-vertical-landing">
<h1 slot="headline">Hello, Terps!</h1>
<div slot="text"><p>Welcome to the University of Maryland.</p></div>
</umd-element-hero>
<section class="umd-layout-space-vertical-landing">
<div class="umd-layout-space-horizontal-normal">
<div class="umd-grid-gap-three">
<umd-element-card>
<h2 slot="headline"><a href="#">Card Title</a></h2>
<div slot="text"><p>Card content goes here.</p></div>
</umd-element-card>
</div>
</div>
</section>Full Working Example
A complete, self-contained HTML document you can copy, save, and open in any browser.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My UMD Project</title>
<!-- Load UMD Static CSS (typography, layout, tokens) -->
<link rel="stylesheet" href="https://unpkg.com/@universityofmaryland/web-styles-library/dist/css/styles.min.css">
<!-- Load UMD Components (auto-registers all web components) -->
<script src="https://unpkg.com/@universityofmaryland/web-components-library/dist/cdn.js"></script>
</head>
<body>
<umd-element-hero data-display="overlay" class="umd-layout-space-vertical-landing">
<img src="https://playground.designsystem.umd.edu/static/media/umd-smiling-graduates.69846e70.webp"
alt="UMD graduates celebrating" slot="image">
<p slot="eyebrow">Welcome</p>
<h1 slot="headline">University of Maryland</h1>
<div slot="text">
<p>Fearless ideas start here. Join our community of innovators and leaders.</p>
</div>
<div slot="actions">
<umd-element-call-to-action data-display="primary">
<a href="https://designsystem.umd.edu/components/overlay-hero">Component Documentation</a>
</umd-element-call-to-action>
</div>
</umd-element-hero>
<section class="umd-layout-space-vertical-landing">
<div class="umd-layout-space-horizontal-normal">
<div class="umd-grid-gap-three">
<umd-element-card>
<a slot="image" href="#">
<img src="https://playground.designsystem.umd.edu/static/media/thurgood-marshall-hall.9f02ee31.webp"
alt="Thurgood Marshall Hall">
</a>
<h2 slot="headline"><a href="#">Academic Excellence</a></h2>
<div slot="text">
<p>Discover our world-class programs and renowned faculty across 12 schools and colleges.</p>
</div>
<umd-element-call-to-action slot="actions" data-display="secondary">
<a href="#">Explore Programs</a>
</umd-element-call-to-action>
</umd-element-card>
<umd-element-card>
<a slot="image" href="#">
<img src="https://playground.designsystem.umd.edu/static/media/thurgood-marshall-hall.9f02ee31.webp"
alt="Campus Life">
</a>
<h2 slot="headline">Campus Life</h2>
<div slot="text">
<p>Experience a vibrant campus community with over 800 student organizations and endless opportunities.</p>
</div>
<umd-element-call-to-action slot="actions" data-display="secondary">
<a href="#">Student Life</a>
</umd-element-call-to-action>
</umd-element-card>
<umd-element-card>
<a slot="image" href="#">
<img src="https://playground.designsystem.umd.edu/static/media/thurgood-marshall-hall.9f02ee31.webp"
alt="Research">
</a>
<h2 slot="headline"><a href="#">Research Impact</a></h2>
<div slot="text">
<p>Join researchers tackling grand challenges from climate change to cybersecurity.</p>
</div>
<umd-element-call-to-action slot="actions" data-display="secondary">
<a href="#">Research Areas</a>
</umd-element-call-to-action>
</umd-element-card>
</div>
</div>
</section>
</body>
</html>Opens in a new window
Production CDN usage
Pin to a specific version to avoid unexpected breaking changes: @universityofmaryland/web-components-library@1.17.14 and @universityofmaryland/web-styles-library@1.7.2. Note that the CDN loads all components in a single bundle — if you need smaller bundles and tree-shaking, use the npm approach below.
Track B: npm / Build Tools
For production applications where bundle size and tree-shaking matter.
Step 1 -- Install Packages
npm install @universityofmaryland/web-components-library
npm install @universityofmaryland/web-styles-libraryStep 2 -- Import and Initialize Components
Use grouped imports to register only the component categories your application needs.
// Grouped imports (recommended)
import { LoadStructuralComponents } from '@universityofmaryland/web-components-library/structural';
import { LoadContentComponents } from '@universityofmaryland/web-components-library/content';
LoadStructuralComponents();
LoadContentComponents();Step 3 -- Import Static CSS
Import pre-compiled CSS directly into your build pipeline. Choose the full bundle or pick individual modules for the smallest possible output.
// Full bundle -- everything in one import
import '@universityofmaryland/web-styles-library/css/styles.min.css';// Or selective imports for smaller bundles
import '@universityofmaryland/web-styles-library/css/tokens.min.css';
import '@universityofmaryland/web-styles-library/css/font-faces.min.css';
import '@universityofmaryland/web-styles-library/css/base.min.css';
import '@universityofmaryland/web-styles-library/css/typography.min.css';
import '@universityofmaryland/web-styles-library/css/layout.min.css';Minimal Vite Example
A complete entry point for a Vite-based application.
// main.js
import '@universityofmaryland/web-styles-library/css/styles.min.css';
import { LoadStructuralComponents } from '@universityofmaryland/web-components-library/structural';
import { LoadContentComponents } from '@universityofmaryland/web-components-library/content';
LoadStructuralComponents();
LoadContentComponents();Then use <umd-element-*> tags in your HTML just as you would with the CDN approach.
Going further
See the Advanced Bundling guide for individual component loading, lazy loading, and per-route code splitting. See the Static CSS guide for a full breakdown of every CSS module available.
What to Explore Next
CDN Track
Component HTML Usage
Slot-based markup patterns for every component.
Static CSS Reference
All available utility classes and tokens.
Feeds Use Cases
Dynamic content feeds via CDN.
npm Track
Advanced Bundling
Code splitting and lazy loading patterns.
Tailwind Integration
Using UMD tokens with Tailwind CSS.
Architecture Overview
Understand the package dependency graph.