Progressive Enhancement in Modern Web Apps

Why building layers of capability remains essential for resilient, fast, and inclusive interfaces in 2025

Progressive Enhancement is a design philosophy that starts with a usable, accessible core experience and adds layers of enhancements on top. The core is HTML. The next layer is CSS for presentation. Then JavaScript adds behavior and orchestration. Each layer must be optional: the app should still work if CSS or JavaScript fails to load, is delayed, or is blocked.

I did not always appreciate this. Early in my career I shipped single‑page apps that relied entirely on JavaScript. When a user on a throttled 2G connection opened the page, they saw a blank screen and a spinner. Accessibility was brittle because screen readers could not meaningfully navigate a shadow DOM of divs. That changed when I rebuilt a checkout flow for an e‑commerce site with progressive enhancement as the rule. The baseline was a standard HTML form that posted to a server. The enhanced version used JavaScript for instant validation, address autocomplete, and subtle animation. We saw a 30% drop in mobile checkout abandonments on poor networks, and support tickets about “blank pages” disappeared.

Today, with more edge computing, faster phones, and more conservative battery profiles, the same patterns matter again. The edge gives us fast static hosting, but it does not guarantee that every request includes JavaScript, especially on corporate networks that strip scripts for security. Browsers increasingly expose performance and privacy constraints that can delay or block scripts. Progressive Enhancement aligns with that reality and helps teams ship interfaces that feel robust rather than fragile.

In this post, we will walk through why Progressive Enhancement fits modern web apps, what it looks like in practice, how to structure projects for it, and where the tradeoffs show up. We will use TypeScript with a minimal server and vanilla client code to show layered enhancement. The ideas are language‑agnostic; the code simply makes them concrete.

Context and where Progressive Enhancement fits today

Progressive Enhancement complements modern frameworks. It is not anti‑framework. It is a way of using frameworks that prioritizes a working core. In real‑world teams, this often means:

• Building server‑rendered HTML as the primary output (for speed, SEO, and resilience).
• Adding a client‑side app shell only where it improves perceived performance or interactivity.
• Treating JavaScript as an enhancement layer, not a requirement.

Who uses it? Mature product teams with accessibility requirements and global audiences. E‑commerce sites that must convert on spotty networks. Content platforms with large search footprints. Internal tools where devices and browsers vary. Design systems increasingly encode progressive enhancement into components by default.

Compared to alternatives:

• CSR‑only SPAs can offer rich transitions and state, but they are brittle when JavaScript fails or is slow. They can be faster on subsequent loads if bundled and cached well, but the initial experience is often worse.
• SSR frameworks (Next.js, Remix, SvelteKit) are well‑positioned because they generate HTML first. Progressive Enhancement is the discipline of making that HTML truly functional without JavaScript and only layering on interactivity where it helps.
• Static site generators produce robust, fast HTML, but apps need more than content. Progressive Enhancement tells you how to add interactivity safely to static foundations.

The web platform has caught up to this model. HTML forms are powerful. CSS has view transitions, container queries, and layered styles. JavaScript has streaming rendering, dynamic imports, and smarter caching. Progressive Enhancement uses these to build resilient experiences, not brittle ones.

Core concepts and practical patterns

Progressive Enhancement is built on layers and fallbacks. Let’s break down the main ideas with examples that mirror real product code.

The HTML baseline

Start with semantic HTML that works without JavaScript. Forms submit, links navigate, and content is readable. This baseline should pass WCAG 2.2 for structure and readability. Use correct landmarks, labels, and input types.

A simple product filter form could look like this:

<form action="/products" method="GET" class="filter-form">
  <fieldset>
    <legend>Filter products</legend>

    <label for="category">Category</label>
    <select id="category" name="category">
      <option value="">All</option>
      <option value="electronics">Electronics</option>
      <option value="books">Books</option>
    </select>

    <label for="minPrice">Min price</label>
    <input type="number" id="minPrice" name="minPrice" min="0" step="1" />

    <label for="maxPrice">Max price</label>
    <input type="number" id="maxPrice" name="maxPrice" min="0" step="1" />

    <button type="submit">Apply filters</button>
  </fieldset>
</form>

<!-- Results are server-rendered in the initial HTML -->
<section aria-live="polite" aria-label="Product results">
  <!-- Server renders items server-side here -->
</section>

This form works everywhere. It submits with a GET request, so results are shareable and bookmarkable. The aria-live region will announce changes when enhanced with JavaScript, but it doesn’t depend on JavaScript to display results.

CSS as a capability layer

CSS is an enhancement layer that must not break the baseline. If CSS fails, content should still be readable. Avoid using CSS to convey meaning. Use progressive features like container queries with fallbacks. Keep layout simple for no‑CSS scenarios.

Example of layered CSS using a feature query as an enhancement:

/* Base layout for no-CSS or limited CSS environments */
.filter-form {
  display: block;
}

/* Enhanced layout for browsers supporting CSS Grid */
@supports (display: grid) {
  .filter-form {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 1rem;
  }
}

/* Container queries for responsive cards (enhancement) */
.product-card {
  container-type: inline-size;
}

@container (min-width: 24rem) {
  .product-card {
    display: grid;
    grid-template-columns: 120px 1fr;
    gap: 0.75rem;
  }
}

/* If container queries are unsupported, the card stays readable */

CSS is also a performance layer. Small, scoped styles load fast and don’t block rendering. Using design tokens and utility classes can reduce layout thrash, especially during hydration.

JavaScript as a behavior layer

JavaScript should add optional behavior, not required functionality. A common pattern: attach event listeners only if the element exists. If a script fails or is blocked, the baseline still works.

Here’s an enhanced version of the filter form that progressively enhances into a live, client‑filtered experience. It works even if the script fails because the server always renders results.

// client/enhance-filters.ts

function enhanceFilters() {
  const form = document.querySelector<HTMLFormElement>('.filter-form');
  const resultsRegion = document.querySelector<HTMLElement>('[aria-live="polite"]');

  if (!form || !resultsRegion) return; // Baseline only

  // Progressive enhancement: Add client-side filtering if possible
  form.addEventListener('submit', async (e) => {
    e.preventDefault();

    const formData = new FormData(form);
    const params = new URLSearchParams(formData as any);

    // Fetch a server-rendered HTML fragment for the results
    try {
      const res = await fetch(`/products?${params.toString()}`, {
        headers: { 'X-Client-Enhanced': 'true' }, // Signal enhancement for server optimizations
      });

      if (!res.ok) throw new Error('Network response was not ok');

      // We prefer HTML fragments for progressive enhancement, not JSON
      const html = await res.text();
      resultsRegion.innerHTML = html;

      // Announce changes for screen readers
      resultsRegion.setAttribute('aria-busy', 'false');
    } catch (err) {
      // Graceful fallback: revert to a normal form submission
      console.error(err);
      form.submit();
    }
  }, { passive: false });
}

// Safe to call unconditionally: if the DOM is missing, nothing happens
enhanceFilters();

Key decisions:

• We fetch HTML fragments instead of JSON to keep rendering on the server and reduce client code.
• We add a header to let the server know we’re enhanced; the server can send lighter HTML if it chooses.
• If anything fails, we revert to the baseline form submission.

Graceful failure and fallbacks

Failures happen: scripts timeout, network is unreliable, CSP blocks third‑party code. Progressive Enhancement handles failure by design.

// client/load-extra-features.ts

async function loadExtraFeatures() {
  // Dynamic import: only if the user needs it and the network can afford it
  if (!('IntersectionObserver' in window)) {
    // Polyfill or degrade gracefully
    return;
  }

  try {
    const { initImageLazyLoader } = await import('./image-lazy-loader.js');
    initImageLazyLoader();
  } catch (e) {
    // If the chunk fails to load, images still render; we just lose lazy-loading
    console.warn('Failed to load enhanced image loader', e);
  }
}

// This function can be called after the core UI is ready
document.addEventListener('DOMContentLoaded', loadExtraFeatures, { once: true });

This approach aligns with the “islands architecture” concept popularized by frameworks like Astro: only enhance the interactive parts and keep the rest static. If an island fails to hydrate, the static content remains.

Server collaboration

In a progressive enhancement setup, the server is a first‑class citizen. It renders HTML and can offer lighter HTML when it detects a client that can hydrate.

Here is a minimal Node/Express server showing how to return HTML fragments for enhanced requests:

// server/index.ts
import express from 'express';
import path from 'path';

const app = express();
app.use(express.static(path.join(__dirname, '../public')));

// Route for HTML results (baseline and enhanced)
app.get('/products', (req, res) => {
  const category = req.query.category as string;
  const minPrice = Number(req.query.minPrice || 0);
  const maxPrice = Number(req.query.maxPrice || Number.MAX_SAFE_INTEGER);

  // Determine whether to return full page or fragment
  const isEnhanced = req.headers['x-client-enhanced'] === 'true';
  const products = [
    { id: '1', name: 'Wireless Mouse', category: 'electronics', price: 25 },
    { id: '2', name: 'Noise-Canceling Headphones', category: 'electronics', price: 120 },
    { id: '3', name: 'Design Patterns Book', category: 'books', price: 40 },
  ];

  const filtered = products.filter(
    (p) =>
      (!category || p.category === category) &&
      p.price >= minPrice &&
      p.price <= maxPrice
  );

  const resultHtml = filtered
    .map(
      (p) => `<article class="product-card"><h3>${p.name}</h3><p>$${p.price}</p></article>`
    )
    .join('');

  // If enhanced, send a fragment. If not, send full HTML.
  if (isEnhanced) {
    res.set('Content-Type', 'text/html');
    return res.send(resultHtml);
  }

  // Baseline: full HTML page
  const fullPage = `
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>Products</title>
      </head>
      <body>
        <main>
          <h1>Products</h1>
          <form action="/products" method="GET" class="filter-form">
            <!-- Same form as client baseline -->
          </form>
          <section aria-live="polite" aria-label="Product results">
            ${resultHtml}
          </section>
        </main>
      </body>
    </html>
  `;
  res.send(fullPage);
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

The server renders HTML for the initial load and returns HTML fragments for enhanced requests. This pattern reduces JavaScript while keeping the app feel fast.

Project structure for progressive enhancement

A realistic project places the baseline assets in a public folder and enhancements in a client directory. Build tooling can be minimal; you don’t need a heavy framework to practice this pattern.

project/
├─ public/
│  ├─ index.html         # Baseline HTML entry
│  ├─ styles.css         # Base styles
│  └─ app.js             # Optional enhancement
├─ client/
│  ├─ enhance-filters.ts
│  ├─ image-lazy-loader.ts
│  ├─ load-extra-features.ts
│  └─ types.ts
├─ server/
│  ├─ index.ts
│  └─ package.json
├─ package.json
└─ tsconfig.json

Keep the baseline lightweight. The server and public folder host the essential experience. The client folder contains enhancements that can be bundled if needed. You can use a bundler like Vite or esbuild for the client code, but keep the output small and dynamic import heavy.

Real-world code scenario: progressive search

Search is a common feature where progressive enhancement shines. The baseline is a simple form that GETs results. The enhancement is a type‑ahead that fetches HTML fragments and updates an aria-live region.

Baseline HTML

<!-- public/index.html -->
<form action="/search" method="GET" role="search">
  <label for="q">Search</label>
  <input id="q" name="q" type="search" autocomplete="off" />
  <button type="submit">Search</button>
</form>

<section aria-live="polite" aria-label="Search results" id="results"></section>

Enhanced client behavior

// client/enhance-search.ts
function enhanceSearch() {
  const form = document.querySelector<HTMLFormElement>('form[role="search"]');
  const input = document.querySelector<HTMLInputElement>('#q');
  const results = document.querySelector<HTMLElement>('#results');

  if (!form || !input || !results) return;

  let controller: AbortController | null = null;

  input.addEventListener('input', async () => {
    controller?.abort();
    controller = new AbortController();

    const q = input.value.trim();
    if (!q) {
      results.innerHTML = '';
      return;
    }

    const url = `/search?q=${encodeURIComponent(q)}`;

    try {
      const res = await fetch(url, {
        signal: controller.signal,
        headers: { 'X-Client-Enhanced': 'true' },
      });

      if (!res.ok) throw new Error('Fetch failed');
      const html = await res.text();
      results.innerHTML = html;
      results.setAttribute('aria-busy', 'false');
    } catch (e) {
      if ((e as Error).name === 'AbortError') return;
      console.warn('Enhanced search failed, user can submit form', e);
    }
  });
}

document.addEventListener('DOMContentLoaded', enhanceSearch);

Server route for search

// server/index.ts (continued)
app.get('/search', (req, res) => {
  const q = (req.query.q as string || '').trim();
  const isEnhanced = req.headers['x-client-enhanced'] === 'true';

  // Example data source; real projects would query a database
  const items = [
    { title: 'Wireless Mouse', url: '/products/1' },
    { title: 'Design Patterns', url: '/products/2' },
    { title: 'Noise-canceling Headphones', url: '/products/3' },
  ];

  const filtered = items.filter((i) =>
    q.length > 0 ? i.title.toLowerCase().includes(q.toLowerCase()) : []
  );

  const html = filtered
    .map((i) => `<article><a href="${i.url}">${i.title}</a></article>`)
    .join('');

  if (isEnhanced) {
    res.set('Content-Type', 'text/html');
    return res.send(html || '<p>No results</p>');
  }

  // Baseline: full page with results
  const fullPage = `
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8">
        <title>Search</title>
      </head>
      <body>
        <main>
          <form action="/search" method="GET" role="search">
            <label for="q">Search</label>
            <input id="q" name="q" type="search" />
            <button type="submit">Search</button>
          </form>
          <section aria-live="polite" aria-label="Search results">
            ${html || '<p>No results</p>'}
          </section>
        </main>
      </body>
    </html>
  `;
  res.send(fullPage);
});

This pattern keeps the baseline functional and enhances it with live updates. The same code can run on low‑end devices; the enhancement just makes it faster and more interactive.

Honest evaluation: strengths, weaknesses, and tradeoffs

Progressive Enhancement is not a silver bullet. It brings strengths and tradeoffs that teams should consider.

Strengths:

• Resilience: Apps survive network hiccups and script failures.
• Performance: HTML is the fastest thing to render; enhancements load on demand.
• Accessibility: Semantic HTML and robust forms make screen readers happy.
• Maintainability: Code is simpler; layers are decoupled and easier to test.
• SEO: Server‑rendered HTML remains the gold standard for discoverability.

Weaknesses and tradeoffs:

• Complexity of layered state: If you rely on client state for rich interactions, you must keep server and client in sync. This is manageable but requires discipline.
• Team mindset: Teams used to SPAs may find this approach slower to build initially because baseline behavior must be solid before enhancements.
• Testing: You need tests for both baseline and enhanced flows, which doubles some test cases but improves reliability.
• Design constraints: You cannot rely on complex client‑only animations or transitions to convey state changes. You need graceful fallbacks.

When it might not be the best fit:

• Highly interactive dashboards with real‑time graphs and complex filtering might be better served by a full client app with server APIs. Even then, you can still start with a baseline that renders a static table and progressively add interactivity.
• Internal tools with controlled environments and strong performance guarantees may skip some baseline concerns, though accessibility still matters.
• Prototypes meant to test UI concepts quickly may prioritize speed of iteration over resilience. Use progressive enhancement once the concept is validated.

In short, Progressive Enhancement is a default stance, not a strict rule. You can still ship a heavy client for specific features; the baseline ensures users always get something usable.

Personal experience: learning curves and common mistakes

In one project, we built a “compare products” tool with side‑by‑side charts. The first version relied on a JavaScript charting library and a complex JSON state manager. It failed on old Android phones and within certain corporate browsers that blocked third‑party scripts. Support tickets spiked. We redesigned it using Progressive Enhancement:

• The baseline rendered a static comparison table with key specs.
• The enhanced version replaced the table with charts and dynamic toggles when JavaScript loaded and IntersectionObserver was available.
• The server handled filtering and sorting and returned HTML fragments for enhanced mode.

The learning curve was in separating concerns: designers had to design both the table and the chart. Developers had to ensure the server could render both. QA needed to test two modes. But the outcome was worth it. Users on slow devices still got a working table. Power users got charts. The codebase shrank because we removed fragile client‑only state logic.

Common mistakes I see:

• Using JavaScript to render critical text content that should be in HTML. Always prefer server‑rendered HTML for content.
• Relying on CSS to hide essential content. If CSS fails, hidden content should still be available or the page should still make sense.
• Treating progressive enhancement as “progressive disclosure” only. It’s not just UI toggles; it’s about resilience across the stack.
• Skipping accessibility on the baseline. The baseline must be accessible because it is the only thing some users will experience.

A small moment that stuck with me: testing with a simulated 3G network and disabling JavaScript in the browser. Watching the product page still render and the form still submit made me realize how much we rely on the network for things that should be local to HTML. Since then, I start with HTML and only add JavaScript where it meaningfully improves the experience.

Getting started: setup, tooling, and workflow

You do not need a heavy setup to practice Progressive Enhancement. A minimal server and a small client bundle are enough. Focus on the mental model: baseline first, enhancements after.

Tooling recommendations

• Server: Node + Express or a lightweight alternative. If you prefer Go, Rust, or PHP, the pattern is the same: render HTML first.
• Bundling: Use esbuild or Vite for client code. They are fast and support dynamic imports.
• Type checking: TypeScript helps catch enhancement logic errors, especially around DOM querying and API shapes.
• Testing: Use Playwright or Cypress for end‑to‑end tests. Test with JavaScript disabled and with network throttling. Add unit tests for server rendering logic.

Mental model

1. Define the baseline: what must work with no JavaScript and limited CSS?
2. Design the enhancement: what gets faster, smoother, or richer when JavaScript is available?
3. Implement the server: ensure it can render both full pages and fragments.
4. Add client code only where it improves the experience. Use dynamic imports and feature detection.
5. Test failure modes: disable scripts, block network requests, and throttle CPU.

Minimal build configuration

Here is a minimal package.json and TypeScript config to scaffold the client and server. Keep it simple.

// package.json
{
  "name": "progressive-enhancement-demo",
  "version": "1.0.0",
  "scripts": {
    "dev": "npm run build:client && npm run server:dev",
    "server:dev": "tsx watch server/index.ts",
    "build:client": "esbuild client/*.ts --outdir=public --format=esm --bundle --splitting --chunk-names=chunks/[name]-[hash]"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@types/express": "^4.17.17",
    "@types/node": "^20.10.0",
    "esbuild": "^0.19.0",
    "tsx": "^4.7.0",
    "typescript": "^5.3.0"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "dist",
    "rootDir": "."
  },
  "include": ["server/**/*", "client/**/*"]
}

Folder structure reminder:

project/
├─ public/          # Baseline assets served directly
├─ client/          # Enhancement code, bundled to public/
├─ server/          # Node server
└─ package.json

Workflow:

• Write baseline HTML and CSS in public.
• Build client enhancements to public via esbuild.
• Start server with tsx watch for development.
• Open the app, then disable JavaScript to verify baseline behavior.
• Throttle network and test dynamic imports to ensure graceful degradation.

Distinguishing features and developer experience

What makes Progressive Enhancement stand out in practice:

• Developer empathy: You feel the product on slow networks and with assistive tech, which shapes better decisions.
• Clear boundaries: HTML is content and structure, CSS is presentation, JS is behavior. This separation reduces bugs.
• Smaller bundles: Enhancements are often small and dynamically imported, leading to faster TTI.
• Safer refactors: Changes to the client layer rarely break the baseline.
• Better test coverage: You test two modes, which catches edge cases early.

Compare this to a purely client‑driven SPA where the baseline is often a spinner. The spinner cannot be enhanced; it’s a hard dependency. With Progressive Enhancement, the baseline is real content and interactions. The spinner might appear briefly during an enhanced interaction, but the user is never blocked from completing the task.

Free learning resources

• MDN: Progressive Enhancement — A clear overview of the philosophy and practical patterns. https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement
• Web.dev: Responsive Web Design Basics — Covers mobile‑first and resilient layout approaches. https://web.dev/learn/design/
• A11y Project: Checklist — Practical accessibility checklist for baseline experiences. https://www.a11yproject.com/checklist/
• CSS-Tricks: The Quest for Robust CSS — Ideas on building resilient styles that degrade gracefully. https://css-tricks.com/robust-css-when-the-css-fails/
• State of JS Survey — Insights into framework usage and how teams structure client vs server code. https://stateofjs.com/

These resources reflect current best practices and how teams integrate Progressive Enhancement with modern stacks.

Conclusion: who should use it and who might skip it

Use Progressive Enhancement if:

• You build customer‑facing products with diverse users and devices.
• SEO, accessibility, and resilience are priorities.
• Your app includes forms, search, or content consumption where baseline HTML is effective.
• You want to reduce long‑term maintenance risk and avoid brittle client‑only dependencies.

Consider skipping or limiting it if:

• You are prototyping purely for design exploration and speed of iteration.
• The app is entirely internal with strong device/browser guarantees and heavy real‑time needs, though accessibility should still be respected.
• Your team does not have the bandwidth to test and maintain baseline and enhanced paths.

The takeaway is simple: start with HTML that works. Then add CSS and JavaScript to make it delightful. This approach aligns with how the web platform actually behaves and how users actually experience it. It leads to apps that feel solid even when the network is not. In 2025, with more edge infrastructure but also more performance and privacy constraints, that feeling of solidity is what users remember.