University of Maryland Web Components Library

High-level web components built on the UMD Elements Library, providing feature-rich, accessible, and brand-compliant UI components for University of Maryland digital experiences.

Overview

The UMD Web Components Library is the primary interface for developers building UMD websites and applications. It provides a comprehensive collection of web components that implement UMD design patterns, ensuring consistency, accessibility, and brand compliance across all digital properties. These components are built on top of the Elements Library and styled using the Styles Library, creating a complete design system solution.

Installation

# Using npm
npm install @universityofmaryland/web-components-library

# Using yarn
yarn add @universityofmaryland/web-components-library

Peer Dependencies

For complete functionality, install the companion packages:

npm install @universityofmaryland/web-styles-library
npm install @universityofmaryland/web-elements-library

Quick Start

Load All Components

import LoadUmdComponents from '@universityofmaryland/web-components-library';

// Initialize all components
LoadUmdComponents();

Load Specific Components (Recommended)

import { Components } from '@universityofmaryland/web-components-library';

// Load only what you need
Components.card.standard();
Components.hero.base();
Components.navigation.primary();

HTML Usage

<umd-element-hero data-theme="dark" data-display="overlay">
  <img slot="image" src="hero.jpg" alt="Hero image" />
  <p slot="eyebrow">Welcome</p>
  <h1 slot="headline">University of Maryland</h1>
  <div slot="text">
    <p>Fearless ideas start here.</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>

Component Architecture

Web Components Standards

All components follow W3C Web Components standards:

• Custom Elements - Semantic HTML tags (e.g., <umd-element-card>)
• Shadow DOM - Style encapsulation and DOM isolation
• Slots - Content distribution for flexible layouts
• Attributes - Configuration and reactive updates

Naming Convention

All components use the umd-element- prefix:

• <umd-element-card>
• <umd-element-hero>
• <umd-element-navigation>

Attribute System

Components use configuration attributes with the data-* prefix:

• Set initial state: data-theme="dark"
• Configure display: data-display="overlay"

Integration with Other Packages

Styles Package Integration

The Styles Package provides utility classes for spacing, grids, and typography:

<!-- Consistent spacing -->
<div class="umd-layout-space-vertical-landing">
  <umd-element-hero><!-- content --></umd-element-hero>
</div>

<!-- Responsive grids -->
<div class="umd-grid-gap-three">
  <umd-element-card><!-- card 1 --></umd-element-card>
  <umd-element-card><!-- card 2 --></umd-element-card>
  <umd-element-card><!-- card 3 --></umd-element-card>
</div>

Learn more about Styles integration →

Elements Package Relationship

Components are built on Elements:

• Elements provide atomic building blocks
• Components compose Elements into features
• Components add interactivity and state management

Feeds Package Integration

For dynamic content, combine with Feeds:

import { Components } from '@universityofmaryland/web-components-library';
import { Feeds } from '@universityofmaryland/web-feeds-library';

// Initialize components
Components.feed.newsList();

// Component will handle feed display

Component Categories

Navigation Components

• navigation.primary - Main site navigation
• navigation.drawer - Mobile navigation drawer
• navigation.breadcrumb - Breadcrumb navigation
• navigation.utility - Utility navigation bar

Content Components

• hero.* - Hero sections (base, expand, grid, logo, minimal)
• card.* - Card layouts (standard, article, event, overlay, icon)
• carousel.* - Content carousels
• accordion.item - Expandable content sections

Layout Components

• layout.modal - Modal dialogs
• layout.stickyColumns - Sticky column layouts
• layout.scrollTop - Scroll to top functionality

Interactive Components

• tab.display - Tabbed interfaces
• slider.* - Content sliders
• actions.display - Call-to-action buttons

Media Components

• media.inline - Inline media players
• person.* - Person/profile displays
• quote.display - Quote/testimonial blocks
• stat.display - Statistics displays

Common Use Cases

Hero with Call-to-Action

<umd-element-hero data-display="overlay">
  <img slot="image" src="campus.jpg" alt="Campus view" />
  <h1 slot="headline">Discover Your Future</h1>
  <p slot="text">Join our community of innovators.</p>
  <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>

Card Grid Layout

<div class="umd-grid-gap-three">
  <umd-element-card data-theme="light">
    <a slot="image" href="/programs">
      <img src="programs.jpg" alt="Academic programs" />
    </a>
    <h3 slot="headline">
      <a href="/programs">Academic Programs</a>
    </h3>
    <p slot="text">Explore our 200+ degree programs.</p>
  </umd-element-card>
  <!-- Additional cards -->
</div>

Navigation Header

<umd-element-navigation-header>
  <div slot="logo">
    <a href="/">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>
    </ul>
  </nav>
</umd-element-navigation-header>

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  ComponentRef,
  SlotConfiguration,
  ComponentEvents,
} from '@universityofmaryland/web-components-library';

// Type-safe component usage
const card = document.querySelector<HTMLElement & ComponentEvents>(
  'umd-element-card',
);
if (card) {
  card.addEventListener('component:ready', (e) => {
    console.log('Card initialized');
  });
}

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Documentation

• Component Reference - Complete API documentation
• Usage Examples - Practical implementation guide with real-world examples
• Advanced Guide - TypeScript, testing, reactive components, and custom development
• Advanced Bundling - Bundle optimization, tree-shaking, and production build strategies
• Design System - Full design system docs

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Contributing

See the main repository for contribution guidelines.

License

University of Maryland