DEV Community

Rizwan Saleem
Rizwan Saleem

Posted on

Building Accessible, Performant Web Components: A Practical Frontend Pattern Guide

#frontend #webdev #react

Building Accessible, Performant Web Components: A Practical Frontend Pattern Guide

Building Accessible, Performant Web Components: A Practical Frontend Pattern Guide

In this tutorial, you’ll learn a concrete pattern for creating reusable, accessible, and high-performance web components that work across frameworks or vanilla HTML. We’ll walk through a real-world example: a customizable user profile card component with accessible keyboard navigation, responsive styling, and solid performance practices. You’ll get code patterns, tests, and deployment tips you can adapt to many frontend projects.

Overview and goals

  • Build a self-contained, reusable web component (custom element) that exposes a clean API.
  • Ensure accessibility (ARIA, keyboard navigation, proper focus management).
  • Optimize for performance (shadow DOM boundaries, lazy rendering, minimal reflows).
  • Provide theming and responsiveness without coupling to a specific framework.
  • Include tests and a small build/dev setup to run locally.

Key outcomes

  • A drop-in profile-card web component you can ship in multiple apps.
  • Clear separation between component logic, styling, and data.

  • A guide to extending the component with additional slots, props, or micro-interactions.

    Tech stack (minimal and framework-agnostic)

  • Vanilla JavaScript (Web Components API)

  • Shadow DOM for encapsulation

  • CSS variables for theming

  • ARIA semantics for accessibility

  • Optional: unit tests with Vitest or Jest, and a lightweight bundler (esbuild)

    Step 1: Create the Web Component skeleton

Code pattern: a self-contained custom element with observed attributes and a simple API surface.

  • Expose data via attributes and a JSON-like data attribute for richer content.
  • Use the shadow DOM to isolate styles.
  • Provide a public API method to update content imperatively.

Code (src/ProfileCard.js):

class ProfileCard extends HTMLElement {
  static get observedAttributes() {
    return ['name', 'title', 'avatar', 'bio', 'location'];
  }

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._name = '';
    this._title = '';
    this._avatar = '';
    this._bio = '';
    this._location = '';
    this._render();
  }

  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal === newVal) return;
    switch (name) {
      case 'name': this._name = newVal; break;
      case 'title': this._title = newVal; break;
      case 'avatar': this._avatar = newVal; break;
      case 'bio': this._bio = newVal; break;
      case 'location': this._location = newVal; break;
    }
    this._render();
  }

  setProfile(data) {
    // data shape: { name, title, avatar, bio, location }
    this._name = data?.name ?? this._name;
    this._title = data?.title ?? this._title;
    this._avatar = data?.avatar ?? this._avatar;
    this._bio = data?.bio ?? this._bio;
    this._location = data?.location ?? this._location;
    this._render();
  }

  _render() {
    const name = this._name || 'Unknown';
    const title = this._title || '';
    const avatar = this._avatar;

    // Basic fallback image if none provided
    const avatarEl = avatar
      ? `<img src="${escapeAttr(avatar)}" alt="" class="avatar" referrerpolicy="no-referrer"/>`
      : `<div class="avatar placeholder" aria-label="No avatar"></div>`;

    const bio = this._bio ? `<p class="bio">${escapeHtml(this._bio)}</p>` : '';

    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: block;
          font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial;
          color: var(fw-text, #111);
        }
        .card {
          display: grid;
          grid-template-columns: 72px 1fr;
          gap: 12px;
          align-items: center;
          padding: 12px;
          border-radius: 12px;
          background: var(fw-surface, #fff);
          box-shadow: 0 1px 3px rgba(0,0,0,.08);
          transition: transform .2s ease;
        }
        .card:hover { transform: translateY(-1px); }
        .avatar, .placeholder {
          width: 72px; height: 72px; border-radius: 50%;
          overflow: hidden; display: block;
          background: #ddd;
        }
        .avatar { object-fit: cover; }
        .content { display: grid; gap: 6px; }
        .name { font-weight: 700; font-size: 1.05rem; margin: 0; }
        .title { font-size: .9rem; color: #555; margin: 0; }
        .bio { margin: 0; color: #444; font-size: .9rem; }
        @media (max-width: 520px) {
          .card { grid-template-columns: 60px 1fr; padding: 10px; }
          .avatar { width: 60px; height: 60px; }
        }
      </style>
      <section class="card" role="region" aria-label="Profile card">
        <div class="avatar-wrap" aria-label="Avatar">
          ${avatarEl}
        </div>
        <div class="content">
          <p class="name" aria-label="Name">${escapeHtml(name)}</p>
          ${title ? `<p class="title" aria-label="Title">${escapeHtml(title)}</p>` : ''}
          ${bio}
          ${this._location ? `<p class="location" aria-label="Location" style="margin:0;color:#666;font-size:.85rem;">${escapeHtml(this._location)}</p>` : ''}
        </div>
      </section>
    `;
  }
}

function escapeHtml(str) {
  return String(str)
    .replaceAll('&', '&amp;')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;');
}
function escapeAttr(str) {
  return String(str).replaceAll('"', '&quot;').replaceAll('?', '');
}

customElements.define('profile-card', ProfileCard);
Enter fullscreen mode Exit fullscreen mode

Usage (HTML):

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <title>Profile Card Demo</title>
  </head>
  <body>
    <profile-card id="pc"></profile-card>

    <script type="module">
      import './src/ProfileCard.js';
      const pc = document.getElementById('pc');
      pc.setProfile({
        name: 'Alex Rivera',
        title: 'Frontend Engineer',
        avatar: 'https://example.com/alex.jpg',
        bio: 'Loves accessible design and tiny perf wins.',
        location: 'Carlisle, England'
      });
    </script>
  </body>
</html>
Enter fullscreen mode Exit fullscreen mode

Notes

  • The component uses a shadow DOM to encapsulate styles and prevent leakage.
  • The API is intentionally simple: attribute-based data plus a setProfile method for richer data.

  • Escaping is essential to avoid injection; the helper functions handle it.

    Step 2: Accessibility basics

  • Use aria-labels on interactive parts and meaningful text in the content.

  • If the component becomes actionable, ensure keyboard support (Tab navigation, Enter/Space to trigger).

  • Manage focus when content changes to avoid confusing users.

Enhancement: make the card focusable and provide a details toggle.

Code snippet (augment _render and add a details button):

_render() {
  // ... existing setup
  const detailsId = 'details-' + Math.random().toString(36).slice(2, 7);
  this.shadowRoot.innerHTML = `
    <style> ... </style>
    <section class="card" role="region" aria-label="Profile card" tabindex="0" aria-describedby="${detailsId}">
      ...
      ${bio}
      ${this._location ? `<p id="${detailsId}" class="location" ...>${escapeHtml(this._location)}</p>` : ''}
      <button class="details-btn" aria-controls="profile-details" aria-expanded="false" type="button">More</button>
      <div id="profile-details" hidden>
        <p>Additional details or social links could go here.</p>
      </div>
    </section>
  `;
  // add keyboard/interaction
  const card = this.shadowRoot.querySelector('.card');
  const btn = this.shadowRoot.querySelector('.details-btn');
  const details = this.shadowRoot.querySelector('#profile-details');
  btn.addEventListener('click', () => {
    const expanded = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', String(!expanded));
    details.hidden = expanded;
  });
  card.addEventListener('keydown', (e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      btn.click();
      e.preventDefault();
    }
  });
}
Enter fullscreen mode Exit fullscreen mode

This approach provides a keyboard-accessible toggle and keeps the card navigable with the keyboard.

Step 3: Theming and design tokens

Support CSS variables for theming so the consumer can adapt the look without touching JS.

  • fw-surface: card background
  • fw-text: main text color
  • fw-muted: secondary text color
  • radius: corner radius
  • shadow: shadow

Usage in HTML:

<profile-card id="pc" style="fw-surface: #fff; fw-text: #111; radius: 14px;"></profile-card>
Enter fullscreen mode Exit fullscreen mode

Or provide a simple theming API:

setTheme({ surface: '#fff', text: '#111', muted: '#555' }) {
  this.style.setProperty('fw-surface', surface);
  this.style.setProperty('fw-text', text);
  this.style.setProperty('fw-muted', muted);
}
Enter fullscreen mode Exit fullscreen mode

Step 4: Data handling patterns

  • Prefer a single, immutable data object for complex content.
  • Accept a JSON string attribute as a compact payload for SSR or markup-driven apps.

Example: accept a data-profile attribute containing JSON.

Attribute parsing in constructor/observed:

attributeChangedCallback(name, oldVal, newVal) {
  if (name === 'data-profile') {
    try {
      const data = JSON.parse(newVal);
      this.setProfile(data);
      return;
    } catch { /* ignore if invalid */ }
  }
  // existing
}
Enter fullscreen mode Exit fullscreen mode

Usage:

<profile-card id="pc" data-profile='{"name":"Alex","title":"Frontend Engineer","avatar":"https://...","bio":"..." ,"location":"Carlisle"}'></profile-card>
Enter fullscreen mode Exit fullscreen mode

Step 5: Performance considerations

  • Shadow DOM boundaries help isolate styles; avoid large DOM trees inside the shadow root.
  • Use lazy loading for images when optional or heavy; add loading="lazy" on avatar images.
  • Minimize re-renders: debounce or batch attribute changes if you call setProfile frequently.
  • Prefer immutable updates: replace innerHTML entirely only when necessary to avoid partial paints.

Code tip: only re-render on meaningful data changes; track a dirty flag if you plan to update in response to rapid sequences.

Step 6: Testing the component

  • Unit tests: verify rendering output given different data, attribute changes, and public API calls.
  • Accessibility tests: ensure aria-labels exist, the toggle is keyboard-accessible, and the DOM structure remains sane.

Example (Vitest/Jest-like pseudo):

import { expect, test, beforeEach } from 'vitest';
import '../src/ProfileCard.js';

beforeEach(() => {
  document.body.innerHTML = `<profile-card id="pc"></profile-card>`;
});

test('renders name and title from attributes', () => {
  const el = document.getElementById('pc');
  el.setAttribute('name', 'Alex');
  el.setAttribute('title', 'Engineer');
  const shadow = el.shadowRoot;
  expect(shadow.querySelector('.name').textContent).toBe('Alex');
  expect(shadow.querySelector('.title').textContent).toBe('Engineer');
});

test('aria-expanded toggles on details button', () => {
  const el = document.getElementById('pc');
  el.setProfile({ name: 'Alex' });
  const btn = el.shadowRoot.querySelector('.details-btn');
  btn.click();
  expect(btn.getAttribute('aria-expanded')).toBe('true');
});
Enter fullscreen mode Exit fullscreen mode

If you’re using a bundler, wire up esbuild/vite with a test script to run these tests in Node environments.

Step 7: How to ship and re-use

  • Publish as a small npm package if you want to share across apps. Pack the component as a library with a nice build step that outputs an ES module and a UMD build for older environments.
  • Document the API clearly: how to instantiate, how to update data, and how to theme.
  • Provide a minimal example app in the repo to showcase usage in vanilla HTML, React, Vue, and Svelte (via a lightweight wrapper or simply using the web component in the template).

Example package.json scripts (minimal):

{
  "name": "profile-card-wc",
  "type": "module",
  "version": "0.1.0",
  "scripts": {
    "build": "esbuild src/ProfileCard.js bundle outfile=dist/profile-card.js format=esm",
    "test": "vitest run"
  },
  "devDependencies": {
    "esbuild": "^0.17.0",
    "vitest": "^0.34.0",
    "happy-dom": "^7.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Note: If you don’t want to publish, you can keep it in a monorepo or a private module and consume via local paths.

Step 8: Extending the component

  • Slots for additional content (e.g., social links)
  • Props for more data (email, website, badges)
  • List-based variants (compact, verbose) controlled via an attribute like variant="compact"

Slot example (HTML in the shadow DOM):

<div class="content">
  <slot name="bio"></slot>
  <slot name="social"></slot>
</div>
Enter fullscreen mode Exit fullscreen mode

Consumer usage:

<profile-card id="pc" name="Alex" title="Engineer">
  <span slot="bio">Custom bio here.</span>
  <span slot="social">Twitter: @alex</span>
</profile-card>
Enter fullscreen mode Exit fullscreen mode

Step 9: Deployment checklist

  • Accessibility: all content reachable by keyboard, landmarks provided, aria attributes in place.
  • Performance: assets lazy-loaded, minimal paint, no layout thrashing.
  • Security: sanitize any data rendered into the DOM; escape attributes and text properly.
  • Documentation: API surface, customization options, and example usage.
  • Testing: unit tests for core behavior and accessibility checks. ### Real-world example: extended usage

Let’s create a profile-card with a responsive variant and an external data source.

HTML (page.html):

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Profile Card Demo</title>
    <script type="module" src="./src/ProfileCard.js"></script>
  </head>
  <body>
    <profile-card id="dev1" variant="compact" data-profile='{"name":"Mira Chen","title":"Frontend Dev","avatar":"https://example.org/mira.jpg","bio":"Accessible by design.","location":"Carlisle"}'></profile-card>

    <script>
      // Optional: rehydrate from an API
      fetch('/api/profile/42')
        .then(r => r.json())
        .then(data => {
          const el = document.getElementById('dev1');
          el.setProfile(data);
        });
    </script>
  </body>
</html>
Enter fullscreen mode Exit fullscreen mode

CSS-variable hydration for theme:

<profile-card id="dev1" style="fw-surface:#f9f9fb; fw-text:#1f2937; radius:16px;"></profile-card>
Enter fullscreen mode Exit fullscreen mode

Quick-start checklist

  • [x] Create a self-contained web component with a clean API
  • [x] Encapsulate styles with Shadow DOM and use CSS variables for theming
  • [x] Implement accessible features: ARIA attributes, keyboard support
  • [x] Provide a simple data API (attributes + setProfile)
  • [x] Add basic unit tests for rendering and interactions
  • [x] Document usage and extension points
  • [x] Add a minimal example app to demonstrate usage If you’d like, I can tailor this pattern to a specific project stack you’re using (e.g., React, Svelte, or a pure static site) and provide a ready-to-run repo structure with a small test suite. Do you want the component to expose a slot-based API for additional content or keep it strictly data-driven with a simple public API?

-

Rizwan Saleem | https://rizwansaleem.co

Sources

Top comments (0)