Elements Use Cases

1. When to Use Elements

The Elements package is designed for scenarios where you need programmatic control over DOM creation rather than declarative web components.

• Imperative DOM creation -- When you need to build UI elements directly in JavaScript rather than through custom HTML tags.
• Framework wrappers -- When building React, Vue, or Angular components that wrap UMD design system elements.
• Custom compositions -- When you need to combine multiple elements into bespoke layouts not covered by existing web components.
• Lifecycle control -- When you need the update() and destroy() methods to manage element state and cleanup.

Elements vs. Components

If you simply need to drop a UMD component into an HTML page, use the Components package (web components). Elements are for developers who need lower-level programmatic control.

2. The ElementModel Pattern

Every element creation function returns an ElementModel object with a consistent interface:

interface ElementModel {
  element: HTMLElement | DocumentFragment;
  styles: string;
  update?: (props: Record<string, unknown>) => void;
  destroy?: () => void;
}

Usage follows a two-step pattern -- create the element, then inject it and its styles into the DOM:

import { Composite } from '@universityofmaryland/web-elements-library/composite';

// Create element
const card = Composite.card.standard({
  headline: 'Research Impact',
  text: 'Join researchers tackling grand challenges.',
  image: { src: 'research.jpg', alt: 'Research lab' },
  isThemeDark: false,
});

// Step 1: Add to DOM
document.querySelector('#container').appendChild(card.element);

// Step 2: Inject styles (once per element type)
const style = document.createElement('style');
style.textContent = card.styles;
document.head.appendChild(style);

3. Atomic Elements

Atomic elements are simple, single-purpose building blocks. They represent the smallest visual units in the design system.

import { Atomic } from '@universityofmaryland/web-elements-library/atomic';

// Text lockups
const lockup = Atomic.textLockup.small({ headline: 'Title', text: 'Description' });

// Actions / CTAs
const cta = Atomic.actions.primary({ label: 'Learn More', url: '/learn' });

// Assets (images, video)
const image = Atomic.assets.image({ src: 'photo.jpg', alt: 'Campus' });

Available Atomic Categories

4. Composite Elements

Composite elements combine multiple atomic elements into complex, multi-part UI structures.

import { Composite } from '@universityofmaryland/web-elements-library/composite';

// Cards
const card = Composite.card.standard({ /* props */ });
const overlayCard = Composite.card.overlay({ /* props */ });

// Heroes
const hero = Composite.hero.base({ /* props */ });

// Navigation, Person, Quote, Footer, etc.

Available Composite Categories