Caveats: Browser Compatibility & Polyfill Requirements

Espalier uses modern browser APIs and CSS. Your application must load any polyfills needed by its browser matrix. Read browser support for minimum versions, then use this guide for feature-specific setup and limits.

Temporal API

What It Is

The Temporal API provides immutable date and time types. Espalier uses its calendar types for date parsing, arithmetic, and validation.

Where Espalier Uses It

Espalier relies on the global Temporal namespace in two components:

• <esp-date-picker> — All date parsing, calendar grid generation, range selection, min/max validation, and display formatting use Temporal.PlainDate, Temporal.PlainYearMonth, and related types.
• <esp-input input-type="date"> — Date validation (min, max, format parsing) uses Temporal.PlainDate.

What Happens Without It

<esp-date-picker> performs a runtime check for window.Temporal. If the namespace is missing, the component renders an inline error message instead of the calendar UI:

Temporal API not found. Load the polyfill in <head> before using <esp-date-picker>.

<esp-input input-type="date"> will fail to validate date constraints if Temporal is unavailable.

What You Need To Do

Load the @js-temporal/polyfill (or any spec-compliant polyfill) before your application code runs. The recommended approach is a <script> tag in your document <head>:

<head>
  <script src="https://cdn.jsdelivr.net/npm/@js-temporal/polyfill/dist/index.umd.js"></script>
  <script>
    globalThis.Temporal ??= temporal.Temporal;
  </script>
</head>

If you use a bundler, install it as a production dependency of your application:

npm install @js-temporal/polyfill

In a module entry point, assign the namespace and then load Espalier with a dynamic import so the order is explicit:

import { Temporal } from "@js-temporal/polyfill";
globalThis.Temporal ??= Temporal;

await import("@taprootio/espalier");

When You Can Remove It

Remove the polyfill when every browser you support provides globalThis.Temporal. Check that feature in your browser matrix rather than assuming support from a browser name or a proposal stage.

OKLCH Color Notation

What It Is

OKLCH is the perceptually uniform color model that Espalier uses for all internal color logic. The oklch() CSS function is supported in all major browsers since 2023.

Relative Color Syntax

Espalier also uses Relative Color Syntax — the oklch(from ...) form — to derive hover states, active states, and theme variants mathematically from a base color:

background: oklch(from var(--esp-color-primary) calc(l + 0.05) c h);

Browser Support

Relative Color Syntax became Baseline in December 2024. If you must support browsers older than those listed above (particularly Firefox 127 or earlier), you will see incorrect or missing colors.

What You Need To Do

There is no JavaScript polyfill for CSS color functions. Ensure your supported browser matrix includes the versions listed above. For enterprise deployments with managed browser policies, this typically means:

• Chrome/Edge 119+ (released October 2023)
• Firefox 128+ (released July 2024)
• Safari 18+ (released September 2024)

Custom Elements and Shadow DOM

Espalier uses the standard Custom Elements v1 and Shadow DOM v1 APIs. These are supported in all modern browsers and do not require polyfills.

If you need to support legacy browsers that lack custom element support (IE11, older Edge), the webcomponentsjs polyfills can be loaded. However, Espalier does not test against polyfilled environments and cannot guarantee full functionality.

ElementInternals and Form Association

Espalier form controls (<esp-input>, <esp-pick-one>, <esp-checkbox>, etc.) use ElementInternals for native form participation — setting form values, managing validity, and participating in form submission and reset.

ElementInternals is supported in Chrome 77+, Firefox 98+, and Safari 16.4+. No polyfill is required for any browser released after April 2023.

CSS Features

Beyond OKLCH, Espalier uses several modern CSS features:

All of these are Baseline features with broad support. If your deployment environment restricts browser versions, the highest bar is CSS Nesting (Chrome 120+, December 2023).

HLS Video Streaming

<esp-video> plays an HLS playlist natively wherever canPlayType reports support: Safari, iOS, and current Chrome. Other browsers, notably Firefox, play HLS only through Media Source Extensions and a streaming library, and Espalier bundles none and attaches none: the element has no runtime dependencies. Set fallback-src to an MP4, or serve MP4 (type="video/mp4") in the first place. Without either, those browsers show the element's error state when a visitor presses play.

Summary of Consumer Responsibilities

Polyfill ownership

Keep polyfills in the consuming application so you can remove them when your supported browsers no longer need them. Espalier does not bundle polyfills or transpile modern CSS.