Component Usage Guide

Learn how to implement UMD Web Components

Home Components

Usage Guide

Getting Started

Where This Package Fits: Components sits at the top of the Application layer. It depends on all lower packages and provides ready-to-use web components. See full architecture.

For installation and initial setup instructions, see the Getting Started Guide. This page focuses on HTML usage patterns for UMD Web Components.

Basic Usage Examples

Hero Component

Create engaging hero sections with built-in responsive behavior:

<umd-element-hero data-theme="dark" data-display="overlay">
  <img slot="image" src="hero.jpg" alt="Campus view">
  <p slot="eyebrow">Welcome to Maryland</p>
  <h1 slot="headline">Fearless Ideas Start Here</h1>
  <div slot="text">
    <p>Join our community of innovators and changemakers.</p>
  </div>
  <div slot="actions">
    <umd-element-call-to-action data-display="primary">
      <a href="/apply">Apply Now</a>
    </umd-element-call-to-action>
  </div>
</umd-element-hero>

Hero Slot Reference

Slot Name	Required	Allowed Elements	Description
`image`	No	`img`	Background image
`eyebrow`	No	`p`, `span`	Small text above headline
`headline`	Yes	`h1`–`h6`	Main heading
`text`	No	`div`	Supporting copy
`actions`	No	`div`	CTA buttons

Card Component

Display content in flexible card layouts:

<umd-element-card data-theme="light">
  <a slot="image" href="/article">
    <img src="news.jpg" alt="News image">
  </a>
  <p slot="eyebrow">Research</p>
  <h3 slot="headline">
    <a href="/article">Breakthrough Discovery in Climate Science</a>
  </h3>
  <p slot="text">
    UMD researchers have made a significant breakthrough that could
    revolutionize our understanding of climate patterns.
  </p>
    <umd-element-call-to-action data-display="primary" slot="actions">
      <a href="/apply">Apply Now</a>
    </umd-element-call-to-action>
</umd-element-card>

Card Slot Reference

Slot Name	Required	Allowed Elements	Description
`image`	No	`a > img`	Card image (wrap in link for click)
`eyebrow`	No	`p`, `span`	Category label
`headline`	Yes	`h1`–`h6` (with optional `a`)	Card title
`text`	No	`p`, `div`	Card body text
`actions`	No	`umd-element-call-to-action`	Action buttons

Navigation Component

Implement accessible navigation with mobile support:

<umd-element-navigation-primary>
  <div slot="logo">
    <a href="/">
      <img src="umd-logo.svg" alt="University of Maryland">
    </a>
  </div>
  <nav slot="primary">
    <ul>
      <li><a href="/about">About</a></li>
      <li><a href="/academics">Academics</a></li>
      <li><a href="/research">Research</a></li>
      <li><a href="/campus-life">Campus Life</a></li>
    </ul>
  </nav>
  <div slot="utility">
    <a href="/search">Search</a>
  </div>
</umd-element-navigation-primary>

Navigation Slot Reference

Slot Name	Required	Allowed Elements	Description
`logo`	Yes	`div > a > img`	Site logo
`primary`	Yes	`nav > ul > li > a`	Main navigation links
`utility`	No	`div`	Utility links (search, etc.)

Styles Integration

Components work seamlessly with the UMD Styles package for consistent spacing, grids, and utilities. You can load styles via static CSS files or through npm imports.

Option A: Static CSS (Simplest)

Load pre-compiled CSS directly via CDN or a local copy:

<!-- Static CSS via CDN -->
<link rel="stylesheet" href="https://unpkg.com/@universityofmaryland/web-styles-library/dist/css/styles.min.css">

Option B: npm Import

Import CSS in your JavaScript entry file when using a bundler:

import '@universityofmaryland/web-styles-library/css/styles.min.css';

Using CSS Utility Classes

Once styles are loaded, use CSS utility classes in your HTML alongside web components:

<!-- Apply consistent vertical spacing between sections -->
<div class="umd-layout-space-vertical-landing">
  <umd-element-hero>...</umd-element-hero>
</div>

<div class="umd-layout-space-vertical-landing">
  <h2 class="umd-sans-larger">Featured Programs</h2>
  <!-- Card grid below -->
</div>

Common Implementation Patterns

Landing Page Hero Section

<!-- Full-width hero with overlay text -->
<section class="umd-layout-space-vertical-landing">
  <umd-element-hero data-display="overlay" data-theme="dark">
    <img slot="image" src="campus-aerial.jpg" alt="Aerial view of campus">
    <h1 slot="headline">Do Good at Maryland</h1>
    <div slot="text">
      <p class="umd-text-large">
        From the classroom to the lab, we're doing good in Maryland and beyond.
      </p>
    </div>
    <div slot="actions">
      <umd-element-call-to-action data-display="primary">
        <a href="/impact">See Our Impact</a>
      </umd-element-call-to-action>
      <umd-element-call-to-action data-display="secondary">
        <a href="/tour">Visit Campus</a>
      </umd-element-call-to-action>
    </div>
  </umd-element-hero>
</section>

News Grid Section

<section class="umd-layout-space-vertical-landing">
  <div class="umd-layout-space-horizontal-normal">
    <h2 class="umd-sans-larger">Latest News</h2>

    <div class="umd-grid-gap-three">
      <umd-element-card data-display="article">
        <a slot="image" href="/news/article-1">
          <img src="news1.jpg" alt="Research lab">
        </a>
        <p slot="eyebrow">Research • Nov 15, 2024</p>
        <h3 slot="headline">
          <a href="/news/article-1">
            New AI Research Center Opens on Campus
          </a>
        </h3>
        <p slot="text">
          The center will advance machine learning research and
          foster collaboration across disciplines.
        </p>
      </umd-element-card>

      <!-- Additional cards... -->
    </div>
  </div>
</section>

Accordion FAQ Section

<section class="umd-layout-space-vertical">
  <div class="umd-layout-space-horizontal-small">
    <h2 class="umd-sans-larger">
      Frequently Asked Questions
    </h2>

    <div>
      <umd-element-accordion-item>
        <h3 slot="headline">How do I apply to Maryland?</h3>
        <div slot="text">
          <p>
            Apply through the Common Application or Coalition Application.
            The priority deadline is November 1 for spring admission and
            January 20 for fall admission.
          </p>
        </div>
      </umd-element-accordion-item>

      <umd-element-accordion-item>
        <h3 slot="headline">What majors are offered?</h3>
        <div slot="text">
          <p>
            We offer over 100 undergraduate majors across 12 colleges
            and schools, from engineering to the arts.
          </p>
          <p>
            <a href="/academics/majors">Explore All Majors</a>
          </p>
        </div>
      </umd-element-accordion-item>
    </div>
  </div>
</section>

Best Practices

Always use semantic HTML within slots
Include descriptive alt text for images
Test keyboard navigation for interactive components
Use the Styles package for consistent spacing
Load only the components you need for better performance
Follow the slot requirements for each component

For Content Managers — See visual examples and component configuration at designsystem.umd.edu.

Related Resources

Components API Reference

Complete API documentation for all component exports.

View API

Advanced Usage

TypeScript, framework integration, testing, and custom component development.

Advanced Guide

Advanced Bundling

Code splitting, lazy loading, and bundle optimization.

Bundling Guide