Fewer lines of code is always a good thing, but it’s the permission prompt that’s key here. When using the aging Geolocation JavaScript API, denying permission at any point can lock the user out with no way to recover unless they change the browser or operating system permissions manually. This can be a painful experience, especially for users that aren’t tech-savvy. Plus, as developers, we have to get the Permissions API involved.

Whereas, the <geolocation> element offers:

• Better error handling, and where applicable, recovery handholding
• User-controlled permission prompting, even if the user denied permission previously
• Auto-location if the user granted permission previously
• A styleable granted state via the :granted CSS pseudo-class

<geolocation> is better in every way except browser support (it requires Chrome 144+), so in this article, I’ll explain how to use it alongside the older current Geolocation JavaScript API so that users get the better experience, if the new element is available.

Requesting the user’s location using <geolocation>

The <geolocation> element accepts several attributes that largely correspond to the options of the getCurrentPosition() and watchPosition() methods of the aging Geolocation API.

Firstly, the accuracymode attribute accepts two values — approximate (which is the default value) and precise.

accuracymode=approximate is equivalent to the enableHighAccuracy: false option (again, the default) from the Geolocation API, whereas accuracymode=precise is equivalent to enableHighAccuracy: true, which provides a more accurate location if the device is able to get one.

The autolocate boolean attribute attempts to get the user’s location automatically, assuming that they’ve granted the website permission previously.

The watch boolean attribute is equivalent to calling the watchPosition() method instead of the getCurrentPosition() method. getCurrentPosition() fetches the user’s location once, whereas watchPosition() tracks their location over time. Like accuracymode=precise and enableHighAccuracy: true, this drains the battery faster.

The onlocation event handler attribute can be used to execute JavaScript whenever location data or error information is passed to the browser.

What the <geolocation> element doesn’t offer, though, is the ability to specify the timeout (how long the browser should wait for a response) or maximumAge (how old a cached location can be). Instead the browser handles these as it sees fit, which is actually a good thing, because choosing the right values on a case-by-case basis is a complexity that we just don’t need.

In practice, this is how you might use <geolocation>:

<!-- Precisely autolocate and follow the user -->
<geolocation accuracymode="precise" autolocate watch>
  <!-- Render this when <geolocation> is unsupported -->
  <button id="fallbackButton">Use precise location</button>
</geolocation>

That is, of course, not including the JavaScript side of <geolocation> nor the Geolocation (JavaScript) API fallback. If you just want the full code then you’re looking for the getCurrentPosition() version and watchPosition() version. Note that geolocation doesn’t work in insecure contexts, so while the logic is sound, the CodePen demos won’t actually work. They’re raw-logic templates anyway, not fully working demonstrations.

Anyway, let’s get into the JavaScript of it all, starting with the JavaScript that sits on the other side of that <geolocation> markup.

Handling the <geolocation> data with JavaScript

First, we want to make sure that <geolocation> is supported with if ("HTMLGeolocationElement" in window). If it is, then we select it with const geoElement = document.querySelector("geolocation").

Unfortunately, we then have to dive into the most complex part of <geolocation> — it’s validity — where the isValid property returns true or false and the invalidReason property returns "" (an empty string) or an enumerated value stating the reason.

These reasons mostly come down to developer oversight, so users shouldn’t encounter these ‘blockers’, but if they do, the <geolocation> button will be disabled. Here are the scenarios in which that can happen (note that the blockers are ordered by severity, and that invalidReason only returns the most severe one):

• illegal_subframe: the <geolocation> element is nested within a <fencedframe> or insecure <iframe> (the latter of which is why the CodePen demos don’t work)
• unsuccessful_registration: the page has more than three <geolocation> elements
• recently_attached: the <geolocation> element has only recently been attached to the DOM (this blocker expires fairly quickly)
• intersection_changed: the <geolocation> element is moving
• intersection_out_of_viewport_or_clipped : the <geolocation> element isn’t within the viewport fully
• intersection_occluded_or_distorted: something is obscuring the <geolocation> element
• style_invalid: the <geolocation> element is styled in a way that isn’t allowed (more on this later)

As you can see, these blockers are permanently avoidable as long as we catch and fix them. Let’s have a proper look at how invalidReason reports these blockers, though.

As the JavaScript comment below describes, isValid always returns false at first, while invalidReason returns recently_attached. This basically disables the <geolocation> button for a fraction of a second to prevent clickjacking. That is, unless a blocker of higher severity applies. We don’t actually need the line below, it’s there just to show you how <geolocation> will never be valid when the page loads.

/* At first, isValid === false and invalidReason === "recently_attached"
unless isValid === false and invalidReason === "a reason of higher severity" */
console.warn(`isValid: ${geoElement.isValid}, invalidReason: ${geoElement.invalidReason}`);

If <geolocation> then becomes invalid for a more permanent reason, isValid will obviously remain false, so we can’t use the validationstatuschange event listener here. However, we can wrap the line in setTimeout() (as below). This will either log a new blocker into the console, or log that isValid is true (in which case invalidReason will be an empty string).

/* After ~300ms, when <geolocation> is no longer ‘recently attached’ (to the DOM)
either isValid === true and invalidReason === "" (an empty string)
or isValid === false and invalidReason === "the reason with the highest severity" */
setTimeout(() => {
  console.log(`isValid: ${geoElement.isValid}, invalidReason: ${geoElement.invalidReason}`);
}, 300);

If the validation status changes later, then we can use the validationstatuschange event listener (again, as below). Note that if there are no persistent blockers, this will fire almost immediately as invalidReason switches from recently_attached to an empty string.

/* If the validity of <geolocation> changes */
geoElement.addEventListener("validationstatuschange", () => {
  if (geoElement.isValid) {
    /* <geolocation> is valid (if there aren’t any blockers,
    it will become valid after it’s no longer ‘recently attached’ */
  } else {
    console.error(`<geolocation> invalid: ${geoElement.invalidReason}`);
  }
});

Now that you know how to debug the validation status and permanently fix any persistent blockers, let’s talk about the permission status.

We’re given a few properties and events to work with:

• initialPermissionStatus: a property that returns denied, granted, or prompt (i.e., neither) based on the permission status when the page first loaded
• permissionStatus: the current permission status
• promptaction: an event that fires when the user denies or grants permission from the <geolocation> permission prompt dialog
• promptdismiss: fires when the user dismisses the dialog, in which case the permissionStatus remains unchanged

/* Determine the initial permission status */
if (geoElement.initialPermissionStatus === "denied") {
  /* The user previously denied permission */
} else if (geoElement.initialPermissionStatus === "granted") {
  /* The user previously granted permission */
} else if (geoElement.initialPermissionStatus === "prompt") {
  /* The user hasn’t made a choice */
}

/* If the user denies or grants permission */
geoElement.addEventListener("promptaction", () => {
  if (geoElement.permissionStatus === "denied") {
    /* The user denied permission */
  } else if (geoElement.permissionStatus === "granted") {
    /* The user granted permission */
  }
});

/* If the user dismisses the prompt */
geoElement.addEventListener("promptdismiss", () => {
  if (geoElement.permissionStatus === "denied") {
    /* The permission state remained denied */
  } else if (geoElement.permissionStatus === "granted") {
    /* The permission state remained granted */
  } else if (geoElement.permissionStatus === "prompt") {
    /* The permission state remained prompt */
  }
});

That being said, I honestly don’t know what we’d need any of that for. If the user previously denied permission, for example, the <geolocation> permission prompt dialog would enable the user to recover from that automatically:

This is in contrast to the older Geolocation API, which is unlikely to help users recover. In this case we need to read the permission status, manage the state of the component accordingly, and provide recovery instructions so that users can grant access manually, but <geolocation> takes care of all of that.

What you will need is the new location event, which fires whenever the browser passes location data (geoElement.position in this case) or error information (geoElement.error) to us.

Then, in the event listener callback, assuming that geoElement.position is truthy, we can access position.coords and position.timestamp, synthesizing the location data like this:

/* If the browser passes location data or error information */
geoElement.addEventListener("location", () => {
  /* If location data */
  if (geoElement.position) {
    /* Synthesize the data */
    const {
      latitude,
      longitude,
      altitude,
      accuracy,
      altitudeAccuracy,
      heading,
      speed
    } = geoElement.position.coords;

    const timestamp = geoElement.position.timestamp;
  } else if (geoElement.error) {
    /* If error information */
  }
});

However, if geoElement.error is truthy, we can access error.message (that’s for us to log into the console) and error.code, which is much more suitable for error handling.

In short, there are three possible error codes, each with an associated constant so that we don’t need to remember what each error code represents. So 1 represents PERMISSION_DENIED, 2 represents POSITION_UNAVAILABLE, and finally, 3 represents TIMEOUT, and then we just evaluate them like this:

/* If the browser passes location data or error information */
geoElement.addEventListener("location", () => {
  if (geoElement.position) {
    /* If location data */
  } else if (geoElement.error) {
    /* If error information */
    console.error(`<geolocation> error: ${geoElement.error.message}`);

    if (geoElement.error.code === geoElement.error.PERMISSION_DENIED) {
      /* No HTTPS or server misconfiguration */
    } else if (geoElement.error.code === geoElement.error.POSITION_UNAVAILABLE) {
      /* No location source (GPS satellite or nearby Wi-Fi network/cellular tower) */
    } else if (geoElement.error.code === geoElement.error.TIMEOUT) {
      /* Location source detection or hardware took too long */
    }
  }
});

PERMISSION_DENIED means that the website isn’t being served over HTTPS (the browser denied permission), or that there’s some kind of server misconfiguration (the server denied permission), but those two errors are permanently fixable and shouldn’t occur in production.

The only way to deny permission (as far as I’m aware) is to block location access from the browser settings, then click on the <geolocation> button, then choose to continue denying. In my opinion, that’s not likely to happen and doesn’t warrant an error message anyway. There isn’t a denial mechanism for OS-level blocks so as not to make the impression that the browser can enforce one. In short, I don’t think we need to do anything for PERMISSION_DENIED.

And to clarify, because <geolocation> is user-invoked, <geolocation> itself never sets the permission status to denied (again, as far as I know).

POSITION_UNAVAILABLE means that the device can’t detect a location source (nearby Wi-Fi networks and cellular towers as well as GPS satellites) to determine the location. Using a VPN or visiting the website via an in-app browser could cause this error too, so this is the trickiest error to convey to users.

TIMEOUT means that the location source detection or hardware took too long, and that users should try again.

How you communicate errors to users is totally up to you.

Falling back to the Geolocation JavaScript API

Ready for round two? Now we’re going to do the same thing but with the aging Geolocation API, which is supported in every browser, but kind of a headache.

This is where we’re at currently:

/* If <geolocation> is supported */
if ("HTMLGeolocationElement" in window) {
  /* What we covered in the previous section */
} else {
  /* What we’re focusing on now (the fallback) */
}

Within that else block, which runs when <geolocation> isn’t supported, we start off by selecting the fallback button (const fallbackButton = document.querySelector("#fallbackButton")). If you recall, this is nested within <geolocation> so that it’s ignored when <geolocation> is supported.

After that we create a function (updateState()) that manages the component state and provides recovery instructions. As arguments we supply the state as a string (‌granted, ‌prompt, or ‌denied, corresponding with the permissionStatus), and optionally, statusMessage, which’ll be used to convey status messages to the user. I don’t want to make any assumptions about your component, so how you convey the statusMessage and expand upon updateState() is up to you.

If state === "denied", we disable the button with fallbackButton.disabled = true and provide some kind of recovery instruction of which should be passed as the second argument of the function. The reason why we disable the button is that this Geolocation API isn’t user-invoked, so to protect the user from spam requests, the browser can suppress requests and send the API straight to jail without passing go, triggering PERMISSION_DENIED. Additionally, if we make the API user-invoked (as we have), users can spam the button themselves and basically shadowblock themselves, but disabling the button fixes that.

If state === "granted" or state === "prompt", we can enable the button (fallbackButton.disabled = false).

Now is a good time to mention that the earlier JavaScript code for the <geolocation> element works regardless of whether the element has the watch attribute or not. However, when using this older Geolocation API, there are two additional things that we need to take care of when trying to keep track of the user’s location continuously. The first thing is the watcher ID, which is returned by the watchPosition() method. Knowing this ID enables us to clear the watcher before registering a new one, which is a must-do for performance reasons.

So we let watcherID = null for now, and then we create the function that attempts to get the location (getLocation()), and the first thing that we do within that function, assuming that watcherID !== null (meaning that it’s been set before), is clear the watcher using navigator.geolocation.clearWatch(watcherID) and make watcherID = null again:

/* A function for getting the location */
const getLocation = () => {
  /* If a watcher has already been registered */
  if (watcherID !== null) {
    /* Unregister it */
    navigator.geolocation.clearWatch(watcherID);
    watcherID = null;
  }
}

Then we disable the button using fallbackButton.disabled = true to, again, prevent spam clicks. If you want to bake some kind of loading indicator in, feel free to, but <geolocation> doesn’t.

After that we call navigator.geolocation.watchPosition(), setting watcherID to the returned watcher ID. This method has three parameters — success, error, and options.

watcherID = navigator.geolocation.watchPosition(
  (position) => {
    /* Success */
  },
  (error) => {
    /* Error */
  },
  {
    /* Options */
  }
);

For the success callback function we synthesize the location data similarly to last time, then call updateState("granted").

For the error callback function (optional but highly recommended) we clear the watcher and, again, make watcherID = null, but otherwise run the same error handling logic that <geolocation> runs. However, there are more circumstances in which the errors can occur.

For example, because watchPosition() and getCurrentPosition() aren’t necessarily user-invoked, there are more scenarios in which users are able to deny access, triggering the PERMISSION_DENIED error. Accordingly, we should call updateState("denied", "Permission denied (try this or that)"), offering a useful status message and clear recovery instructions.

Similarly, POSITION_UNAVAILABLE can also be triggered by an OS-level block, since not all web browsers catch this during the permission prompt dialog. updateState("prompt", "Position unavailable (try this or that)") is what we’re looking for this time.

Finally, another scenario that doesn’t occur with <geolocation> but does with this Geolocation API, is that if the browser prompts the user to grant permission at the OS-level, but then the user cancels their request, that can trigger the TIMEOUT error. Either way, call updateState("prompt", "Request timed out (try this or that)”), once again tweaking it to your liking.

As you can see, the error reporting isn’t the best. Sometimes the error isn’t identified correctly, and even when it is, the error can occur for various reasons, which makes it difficult for us to convey a useful status message and clear recovery instructions. <geolocation> handles this better — the errors are identified correctly, and the nature of <geolocation> ensures that certain errors never occur to begin with. But why the error categories? Why not tell us exactly what went wrong?

Well, the reason is to make fingerprinting more difficult, and while we can totally put in the extra work to pinpoint the exact problem, simply stating what happened and what the user should do next is perfectly fine. Of course, error.message tells us more than error.code does, but the messages can be a bit vague and differ in every web browser, so we can’t read them or even output them reliably.

Anyway, the optional third parameter expects an object where we can set:

• enableHighAccuracy: true or false
• timeout: 20000 (20 seconds) is reasonable if enableHighAccuracy: true, 3000 - 5000 otherwise
• maximumAge: 0 for turn-by-turn navigation, 5000 - 10000 (5-10 seconds) for live tracking, 300000 - 600000 (5-10 minutes) for frequent updates (e.g., weather)

I’d rather that the web browser choose the timeout and maximumAge for us, especially considering the impact that they have on the TIMEOUT error and device battery, but of course, that’s exactly what <geolocation> does.

/* Attempt to get the location and store the returned ID */
watcherID = navigator.geolocation.watchPosition(
  /* If location data is passed (like before) */
  (position) => {
    /* Synthesize the data (again, like before) */
    const {
      latitude,
      longitude,
      altitude,
      accuracy,
      altitudeAccuracy,
      heading,
      speed
    } = position.coords;

    const timestamp = position.timestamp;

    /* And update the state */
    updateState("granted");
  },

  /* If error information is passed (yep, like before) */
  (error) => {
    console.error(`Geolocation error: ${error.message}`);

    /* Again, unregister the watcher (if necessary) */
    if (watcherID !== null) {
      navigator.geolocation.clearWatch(watcherID);
      watcherID = null;
    }

    if (error.code === error.PERMISSION_DENIED) {
      /* No HTTPS, server misconfiguration, or the user denied access */
      updateState("denied", "Permission denied (try this or that)");
    } else if (error.code === error.POSITION_UNAVAILABLE) {
      /* No location source (GPS satellite or nearby Wi-Fi network/cellular tower) or OS-level access */
      updateState("prompt", "Position unavailable (try this or that)");
    } else if (error.code === error.TIMEOUT) {
      /* Location source detection or hardware took too long, or the user canceled their request */
      updateState("prompt", "Request timed out (try this or that)");
    }
  },
  {
    enableHighAccuracy: true,
    timeout: 20000 /* 20 seconds because enableHighAccuracy: true */,
    maximumAge: 0 /* 0 seconds because we’re demanding high accuracy */
  }
);

After that we need to query the permission status using the Permissions API (navigator.permissions.query({ name: "geolocation" }).then((permissionStatus) => { /* ... */ })), and then execute all of the aforementioned logic based on that.

If permissionStatus.state === "granted", we call getLocation(), which is essentially what the autolocate attribute does. If you don’t want autolocation, simply delete this part. If it’s anything else, we basically determine the initial state by calling updateState(permissionStatus.state).

/* Query the permission status */
navigator.permissions.query({ name: "geolocation" }).then((permissionStatus) => {
  /* Equivalent to the autolocate attribute */
  if (permissionStatus.state === "granted") {
    getLocation();
  } else {
    /* React accordingly */
    updateState(permissionStatus.state);
  }
});

Finally, make the button respond to clicks:

/* If the user clicks the fallback button */
fallbackButton.addEventListener("click", () => {
  getLocation();
});

If we only want to get the user’s location once (rather than watch it continuously), these are the modifications that we need to make:

• Remove everything related to the watcherID
• Swap watchPosition() for getCurrentPosition()
• Provide different settings for the options parameter

Note that the change event, which could help us update the state whenever the user changes their browser-level permission status, doesn’t fire in Safari. Besides, the standard browser behavior is to ask users to refresh the page, so let’s stick with that.

One more thing — I wanted the button to say “Refresh precise location” and “Getting precise location…” at certain points, but <geolocation> doesn’t do this, so I didn’t either. That’s up to you, though.

Styling the <geolocation> element

<geolocation> has a :granted pseudo-class. If we throw :not(:granted) into the mix, we can target the prompt/denied states too:

geolocation {
  &:granted {
    /* Permission granted */
  }

  &:not(:granted) {
    /* Permission not granted */
  }
}

With the Geolocation API, we can toggle classes as needed to achieve the same effect, but honestly, I’ve never felt compeled to style such a button in this way. Personally, I’d like to be able to change the icon and text (maybe this is something that you can bake into the updateState() function), but this is one of the things that the <geolocation> element outright forbids.

Before we dive into all that, here’s a rundown of <geolocation> rules stated by Google’s explainer and Mozilla’s explainer:

• There must be sufficient color contrast
• The alpha channel must resolve to 1 (so no transparency)
• The minimum and maximum width, height, and font size must be respected
• Negative margins and outline offsets aren’t allowed either
• Distortion effects — including linear gradients — are banned

It’s also worth noting that some of these rules function like guardrails (for example, you physically can’t style the height above 50px), whereas others cause invalidReason to return style_invalid and the <geolocation> button to be disabled.

Some of the rules seem to have changed (or are currently bugged). <geolocation> doesn’t respect prefers-color-scheme either, but it’s a developing feature, so I’m not going to comment on all of that too much. I’ll just state what I do and don’t like:

• I don’t like that the button becomes disabled because of a style (guardrails are better, but I don’t really like either)
• I don’t like the forced icon and text, and I’m also not too happy about not being able to use gradients or corner-shape
• I can make peace with everything else because I’d normally design within those guardrails anyway
• The text being localized into different languages is very cool, but it’s a first for web standards and I don’t currently enjoy that it’s a thing for only these permission buttons

While I obviously support preventing web authors from tricking users into giving away their location, I think it’d be better if <geolocation> were fully styleable and the permission prompt dialog be ultra clear about what the user is about to commit to.

Even though I can style the background, color, border, border radius, and box shadow how I’d want them (as in the image below, which is most of what I’d want), this feels like a step back towards unstyleable controls. Having said that, this approach means well (extremely well), so I can’t wait to see where this goes (and frankly, to be able to throw the aging Geolocation API in the bin).

What now? What else?

When all web browsers support <geolocation>, the user experience and developer experience will improve dramatically.

But that’s not all!

What was once the <permission> element is now the <geolocation> element, <install> element (which facilitates the installation of Progressive Web Apps), <usermedia> element (which facilitates access to the user’s camera and/or microphone), and <camera> and <microphone> elements (which facilitates access to them individually).

All of these are being trialed in Chrome as part of a larger initiative to improve the process and experience of requesting permission, which is bloody great, in my opinion.

On the web, text highlights are a good way to lay emphasis on text fragments through good ol’ CSS. From ::selection for styling selected text to ::target-text which styles highlighted text from Google searches, and in my opinion, CSS’ most powerful pseudo-element for highlighting: ::highlight() which applies a custom highlight to a text fragment.

In this article, we will look into how the ::highlight() pseudo-element works, the API behind this pseudo-element, and explore a fallback feature for this technology because it relies heavily on JavaScript (JS).

See the Pen ::highlight() demo: pure text-shadows by Andy Bell (@piccalilli) on CodePen.

The CSS Custom Highlight API

Typically, a highlight or highlighted text is what you’d see during web searches or when you what to select a text fragment to copy, or even when you make a mistake in a word processor (the squiggly red underlines). In CSS, you can achieve these through the highlight pseudo-elements like::search-text, ::selection, ::spelling-error , and ::grammar-error . But, what about plain highlights like the demo above? That’s where the CSS Custom Highlight API comes in.

The CSS Custom Highlight API is an API for text highlighting on a range of text using JavaScript and CSS. It extends the pseudo-elements for highlighting (::search-text , ::selection, ::spelling-error ) and lets you customize text fragments with ::highlight() and JavaScript. ::highlight() is what will be our focus for this article, and how we can programmatically highlight text and its fragments using JavaScript and CSS.

How ::highlight() works

To create highlighted text like in the initial example, you need to know 4 total steps, which include:

1. Creating the highlight buckets by creating instances of the Highlight() class
2. Register each highlight instance into CSS.highlights
3. Create Range() objects each with different points on the text for highlighting and add Range() objects to its highlight instances
4. Style with ::highlight() pseudo-element

Before we move on with an example, let me explain something because this is where it might get tricky. What we do around here is build with progressive enhancement in mind first. So the first question you should ask before anything is “what happens when JS fails?”. Well, I’m glad you asked.

Let’s say, for our example, we want to create two highlight objects and use that to style a simple poetic text that reads “fire and ice live inside every word.” Because we care about our users, we set each text for highlight with the <mark> HTML tag setting the class attribute to either gold or ice , depending on the highlighting style we wish the text to have. This acts as a fallback highlight style in case our JavaScript fails or the browser doesn’t support custom highlighting.

We also apply an id to them in case JS is available too for our CSS Custom Highlight API. With all that in mind, our HTML would look like this:

<main>
  <h1>Two Highlights Demo</h1>
  <p id="line">
    <mark id="fire" class="gold">fire</mark> and
    <mark id="ice" class="ice">ice</mark> live inside 
    <mark id="every" class="ice">every</mark> 
    <mark id="word" class="gold">word</mark>
  </p>
</main>

Then, we proceed to query each tagged word in our JS applying the firstChild property to each of them of get the element’s first child node which we will use later:

const fireNode = document.querySelector("#fire").firstChild;
const everyNode = document.querySelector("#every").firstChild;
const iceNode = document.querySelector("#ice").firstChild;
const wordNode = document.querySelector("#word").firstChild;

Finally, we can proceed with the steps on creating a custom highlight in CSS.

Create instances of Highlight() class

In order to create a custom highlight, the first step is to create an instance of the Highlight() class which will house the highlight styling we want a text or text fragment to have. For our demo, we’ll be creating two highlight objects named using the Highlight() class. One to give a golden color representing fire and the other to give a blue color representing ice:

const goldHL = new Highlight();
const iceHL = new Highlight();

Register each highlight instance in CSS.highlights

Next, we register the created highlight instances in the HighlightRegistry via CSS.highlights set() method. We map a valid CSS identifier to the instance for CSS styling later.

CSS.highlights.set("hl-gold", goldHL);
CSS.highlights.set("hl-ice", iceHL);

Create Range() objects each with different points on the text for highlighting

In this step, we will be creating a Range() object for each text fragment we queried earlier for highlighting. We will then apply the highlight we want on each selected text. For the first word “fire”, we create a Range() object called r1 , and we set the start node to the first letter “f” using setStart on r1 . setStart() accepts two values. It accepts the node we’re targeting (in our case for “fire”, its fireNode ) and the index of the text on the node.

Now, because we want to target the whole text “fire”, we have to also set where the range will stop. And this will be set using setEnd() . setEnd() accepts two values like setStart() on the range object (r1). It accepts the node we’re targeting (fireNode ) and the index of the end text “e” (as in the “e” in “fire”) using fireNode.textContent.length - 1 which gives us the last index of the text.

Finally, we add the range object into the set instance.

const r1 = new Range();
r1.setStart(fireNode, 0);
r1.setEnd(fireNode, fireNode.textContent.length - 1);
goldHL.add(r1);

This step is repeated for everyNode, iceNode, and wordNode. Typically, you’d want to use a loop for this, but because this is really small, writing it in a specific manner will suffice, especially to help you understand how this works too.

const r2 = new Range();
r2.setStart(wordNode, 0);
r2.setEnd(wordNode, wordNode.textContent.length - 1);
goldHL.add(r2);

const r3 = new Range();
r3.setStart(iceNode, 0);
r3.setEnd(iceNode, iceNode.textContent.length - 1);
iceHL.add(r3);

const r4 = new Range();
r4.setStart(everyNode, 0);
r4.setEnd(everyNode, everyNode.textContent.length - 1);
iceHL.add(r4);

Style with ::highlight() pseudo-element

Remember how we said we should think progressive enhancement first? Well, in order to achieve that for this demo in particular, we need to style the <mark>ed highlighted text first, then, we style the ::highlight() pseudo-element. For that to work, we styled text marked with the gold class to be golden in oklch() with a glowy text shadow of similar color. We style text <mark> ed with the ice class to be blueish in oklch() with a glowy text shadow of similar color:

mark {
  background: none;
}

mark.gold {
  color: oklch(88% 0.16 75);
  text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
}

mark.ice {
  color: oklch(82% 0.1 215);
  text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
}

See the Pen ::highlight() demo: two highlights without `::highlight()` by Andy Bell (@piccalilli) on CodePen.

Viola! (or how do they say it?) It looks amazing! 🤩

Even without the styled ::highlight() , it works out pretty well. But, that’s not our only aim though. We still need to add the styling for both our highlight objects.

::highlight(hl-gold) {
  color: oklch(88% 0.16 75);
  text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
}

::highlight(hl-ice) {
  color: oklch(82% 0.1 215);
  text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
}

Done! It’s pretty much the same styling we did for our <mark> tag classes and in case JS fails or the browser doesn’t support it, we wrap the ::higlight() pseudo-elements in a @supports container:

@supports selector(::highlight(h1-gold)) {
  ::highlight(hl-gold) {
    color: oklch(88% 0.16 75);
    text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
  }

  ::highlight(hl-ice) {
    color: oklch(82% 0.1 215);
    text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
  }
}

See the Pen ::highlight() demo: two highlights with fallback by Andy Bell (@piccalilli) on CodePen.

Will you be using ::highlight()?

I know for sure I will be using this feature in my work. This article explained highlighting in CSS, the CSS Custom Highlight API, and how ::higlight() works in CSS with a fallback provision, for when JavaScript isn’t available or the browser doesn’t support it.

If you’re looking to read up more about the CSS Custom Highlight API, MDN has a good guide on the topic for you.

While it is easy for sighted people with full mental and motor abilities to click a button with a mouse to display more information, users of Assistive Technology (AT) may have a completely different experience with the same action.

The information an expandable button conveys to AT depends heavily on the context. This context also dictates which ARIA attributes should (or should not) be used. Often, the patterns are very similar in their functionality and interpretation and can be interpreted differently by me than by you.

When I conduct accessibility audits, I usually can’t avoid having to check an element that has the aria-expanded attribute. One of the challenges I faced was determining what kind of pattern this was, whether aria-expanded was appropriate here, or if it could even be replaced by a native HTML element.

This article is intended to help you more easily determine whether aria-expanded has been used correctly or not. It’s not about how to implement every pattern discussed here in a production environment! However, in each section, I’ve included additional links so you can dive deeper into the topic.

The two categories

As I understand it, collapsible widgets can be divided into two categories: collapsible sections and collapsible interactive elements.

These two categories include patterns that are sometimes very similar, but not identical. In addition, there are patterns that can also reveal and hide content, but these do not require the aria-expanded attribute.

Collapsible sections

This category contains two patterns: Accordion and disclosure widget. The former is based on the latter, so let’s take a closer look at the disclosure widget first.

Disclosure widget

<button
	aria-controls="content"
	aria-expanded="false"
	type="button"
>
	Show more
</button>
<div id="content" >
	<p>I am hidden no more!</p>
</div>

This is a basic disclosure widget that requires JavaScript to dynamically change aria-expanded from true to false and to add keyboard support.

aria-controls serves as optional support here to establish a direct link between the button and the content. For more information on implementation, see Adrian Roselli’s article Disclosure Widgets.

However, if that is all it needs to do, it is recommended to use the <details> and <summary> elements. These two native HTML elements work in all major browsers and are also recognised by AT.

Accordion

The accordion pattern is more complex because it combines multiple disclosure widgets. Here, too, aria-expanded is required to communicate the current state to assistive technologies.

There is also often the “exclusive accordion,” which only allows one disclosure widget to be open at a time and closes the others. Not only has Eric Eggert expressed legitimate doubts about this in his article Exclusive accordions exclude, but Steven Hoober also explains in Designing for Progressive Disclosure why this is a user-hostile pattern.

If you still need to build one, it’s recommended to try out Alexander Lehner’s solution in Let’s Play Accordion with the HTML details element. Alternatively, Heydon Pickering also has a suggestion on how collapsible sections could be implemented.

Collapsible interactive elements

A collapsible section can also contain interactive elements such as links, but this pattern is most often used to hide large amounts of text in order to save vertical space. You can read about why this can be user-hostile in the linked articles from the previous section.

I was able to identify four patterns for collapsible interactive elements that would require aria-expanded: menus, navigation, tree views and combo box.

Navigation

Perhaps because menus and navigation behave so similar, they are often confused with one another. That’s why, in my article Menu and Navigation: The Difference, I explain how to tell them apart. What they do have in common, however, is that when the content becomes extensive, so-called fly-out menus are used to show and hide content:

<nav aria-labelledby="main-nav">
	<span hidden id="main-nav">Main</span>
	<ul>
		<li><a href="…">Home</a></li>
		<li><a href="…">Shop</a></li>
		<li class="has-submenu">
			<a href="…" aria-expanded="false">
				Space Bears
			</a>
			<ul>
				<li><a href="…">Space Bear 6</a></li>
				<li><a href="…">Space Bear 6 Plus</a></li>
			</ul>
		</li>
		<li><a href="…">Mars Cars</a></li>
		<li><a href="…">Contact</a></li>
	</ul>
</nav>

In this slightly altered W3C example of a navigation we can see progressive enhancement in action:

• If CSS and JavaScript fail to load, this navigation would still work because semantic HTML was used and none of the list items are hidden.
• aria-expanded indicates that the submenu is currently collapsed.
• No additional ARIA is needed to describe the relationships between the list items and their respective parent lists, as this is communicated by the semantic HTML elements <ul> and <li>.

There is another element related to this pattern that requires the aria-expanded attribute: the so-called hamburger button!

Menu

It is very important here to distinguish whether this button is intended to reveal a navigation bar or a menu. If it is a navigation bar, aria-expanded is sufficient. If it is a menu, aria-haspopup is also required!

<button
  aria-controls="menu"
  aria-haspopup="true"
  aria-expanded="false"
  id="menu-button"
  type="button"
>
  Menu
</button>
<ul
  aria-activedescendant="mi1"
  aria-labelledby="menu-button"
  id="menu"
  role="menu"
  tabindex="-1"
>
  <li id="mi1" role="menuitem">Action 1</li>
  <li id="mi2" role="menuitem">Action 2</li>
  <li id="mi3" role="menuitem">Action 3</li>
  <li id="mi4" role="menuitem">Action 4</li>
</ul>

Depending on the scope of the menu, the following ARIA roles may also be necessary:

• aria-labelledby or aria-label: If a menubar has a visible label, the element with role menu or menubar needs to have one of these attributes set to a value that refers to the labelling element.
• aria-activedescendant: Indicates the relationship between the selected menu item and the parent element in which it is located.
• aria-checked: If it is possible to select multiple menu items, the corresponding value must be true or false.
• aria-controls: Establishes a programmatic relationship between the respective menu button and the contained menu items. As mentioned earlier, browser support is sparse, and this feature should be considered more of a nice-to-have.

A very good guide to creating progressively enhanced menus is Heydon’s article Menus & Menu Buttons. The APG explainer for the Menu Button Pattern is a good place to start if you want to get an overview of the necessary ARIA roles.

Tree view

APG distinguishes between two patterns here that are essentially the same but can vary greatly in complexity depending on the implementation:

• Tree view: “A tree view widget presents a hierarchical list.”
• Tree grid: “A tree grid widget presents a hierarchical data grid consisting of tabular information that is editable or interactive.”

In both cases, the aria-expanded attribute is required for the interactive element, which can show or hide additional elements. Here, too, other ARIA roles may be necessary depending on the implementation. This simplified example shows a possible HTML structure. It would also need a significant amount of CSS and JavaScript to convey visual information, as well as information communicated to AT:

<ul role="tree" aria-labelledby="tree-label">
  <span hidden id="tree-label">Menu</span>
  <li
    aria-expanded="false"
    aria-level="1"
    aria-posinset="1"
    aria-selected="false"
    aria-setsize="2"
    role="treeitem"
  >
    <ul role="group">
      <li
        aria-level="2"
        aria-posinset="1"
        aria-selected="false"
        aria-setsize="2"
        role="treeitem"
      >
        Content 1
      </li>
      <li
        aria-level="2"
        aria-posinset="2"
        aria-selected="false"
        aria-setsize="2"
        role="treeitem"
      >
        Content 2
      </li>
    </ul>
  </li>
</ul>

• aria-multiselectable: Necessary if more than one node can be selected.
• aria-selected or aria-checked: One of the two is required if more than one node can be selected.
• aria-labelledby or aria-label: The element with role tree has either a visible label referenced by aria-labelledby or a value specified for aria-label.
• aria-orientation: If the tree element is horizontally oriented, it has the value aria-orientation="horizontal".
• aria-level, aria-setsize and aria-posinset: These might be necessary, if “the complete set of available nodes is not present in the DOM due to dynamic loading as the user moves focus in or scrolls the tree”.
• tabindex: Depending on your implementation, you might need to implement a roving tabindex.

If you need a starting point for creating one of these components, check out Create an accessible tree view widget using ARIA by Pope Tech.

Combo box

The native <select> element can now be styled freely and also offers keyboard support, as well as robust accessibility support by default, so there should be no need to build this element yourself.

<label for="pet-select">Choose a pet:</label>

<select id="pet-select" name="pets">
  <option value="">Please choose an option:</option>
  <option value="dog">Dog</option>
  <option value="cat">Cat</option>
</select>

If it is necessary after all, the aria-expanded attribute is required here as well. In addition, aria-haspopup, aria-activedescendant, and aria-selected may also be necessary, depending on the implementation. Furthermore, aria-autocomplete and aria-labelledby or aria-label may also be required.

Make sure to give the specs of combobox role a good read before building it. Although, why go through all that trouble when the web platform provides an element that can already do all of this? 🤗

Similar but different

The following patterns can also reveal content at the touch of a button. However, this isn't so much a “fold-out” as it is a “pop-up”! Instead of using aria-expanded to communicate the state of an interactive element, you would rather use aria-haspopup oder aria-modal.

Dialog (Modal)

According to APG, the dialog pattern requires the aria-modal attribute, but let me stop you right there. The native <dialog> element has had solid browser support for quite some time and is supported by assistive technologies. In addition, we now have invoker commands at our disposal, which means you could implement this pattern without using any JavaScript! Use the dialog element (reasonably) to save time and frustration and to keep your users happy.

In this example, we’re using invoker commands. If you want to play it safe, you could also add a fallback using JavaScript, in case invoker commands are not supported yet in the browser of your choice.

<button command="show-modal" commandfor="my-dialog">
	Open dialog
</button>

<dialog id="my-dialog">
	<h2>Progressive enhancement</h2>
  <p>This dialog uses no JavaScript!</p>
  <button commandfor="my-dialog" command="close">
	  Close
  </button>
</dialog>

Tabbed interfaces

Unfortunately, there is no native, JavaScript-free solution for this pattern yet, so you’ll either have to build it yourself using aria-haspopup or use a ready-made solution from a third-party provider.

Personally, I prefer the first option so you know what’s going on under the hood. A good starting point for this is Tabbed Interfaces by Heydon Pickering.

Additionally (according to the APG), other ARIA roles such as aria-controls, aria-selected, aria-orientation, aria-label, or aria-labelledby may be added, depending on how you implement it.

Tooltip

This pattern is an interesting case, as there is no specific example of it in the APG. Nevertheless, Heydon has taken on the challenge here as well and explains in Tooltips & Toggletips how to create an accessible tooltip on your own.

Alternatively, you could experiment with how the Popover API and invoker commands work together with AT to implement this pattern natively and without JavaScript:

<button command="toggle-popover" commandfor="info">
  What is two-factor authentication?
</button>

<div id="info" popover="auto" role="tooltip">
  Two-factor authentication adds a second verification step (like a code
  from your phone) when you log in.
</div>

Once again, we need very little to get a lot done! Let’s break down what’s happening here:

• command="toggle-popover": The Popover API provides to show or hide a popover, aka toggling it.
• commandfor="info": Here we’re using the Popover API to target the element with id="info" in order to connect the button with this particular element.
• popover="auto": This enables the so-called “light-dismiss”, meaning that clicking outside of the tooltip or pressing ESC will close it.
• role="tooltip": Without explicitly specifying the role, it would have a role of “group”.

Wrapping up

Originally, this article was supposed to be about expandable buttons. Then I realised it would make more sense to write specifically about the ARIA role aria-expanded. After further research, I discovered that this attribute is no longer absolutely necessary for some patterns because the web platform has evolved significantly in recent years!

Thanks to native solutions like <detail>, <summary>, and <dialog>, as well as the Popover and Invoker Commands API, it’s possible to implement many of the patterns discussed here with minimal effort and even without JavaScript.

Nevertheless, it’s very important that not only these native (and in some cases very new) solutions are thoroughly tested with assistive technology, but also those you’ve created yourself.

It’s even more important to note that the APG patterns are not suitable for production use but should be understood solely as illustrations of how to use various ARIA roles. That’s why I’ve added an alternative example to each pattern presented, in which it was implemented with progressive enhancement in mind.

FYI

In this specific instance, I'm here to teach you about using the Proxy constructor and Reflect object. These are features of the language worth having in your toolbox, naturally — but just as importantly they allow us to graze up against some of JavaScript's innermost workings, and in doing so, better learn the shape of the mechanisms that power the language. That's the kind of know-how that makes a senior developer.

Now, the keen-eyed among you may notice that this article is shaped conspicuously like an excerpted lesson from said course — and yet, nowhere on the lesson listing page does it appear. "Whatever could that mean," you might ask.

Well, stay tuned.

An object is a collection of properti— hey! Don't you roll your eyes at me! Listen, I know that phrase is approaching "mitochondria is the powerhouse of the cell"-level here, but I'm going somewhere new with this, I promise.

Ahem. An object is a collection of properties, internal slots, and internal methods that allow us to interact with those properties. When you punch ({}).theProperty into your developer console, you do so expecting the following choose-your-own-adventure operation to kick off:

• Is that key somewhere along the object's prototype chain?
  • Yes.
    • Is it a data property?
      • Result in the property descriptor's value.
    • Is it an accessor property?
      • Invoke the getter method, and result in the value returned by the that method.
  • No.
    • Result in undefined.

This use of property accessor syntax doesn't itself represent all those steps — rather, dot notation is the API that kicks off an internal [[Get]] operation defined by the specification, and the steps taken by that [[Get]] operation determine the result.

We can't get in there and tinker with the specific steps taken by an object's internal methods, nor would we likely want to — that's JavaScript engine turf. What we can do is intercept those operations by way of a proxy object, and in doing so we can alter, expand, or wholesale redefine the way that an object works, at its most fundamental levels.

See? And I bet you thought this one was gonna be boring.

The Proxy constructor can be used to create an object that acts as a proxy for a target object, allowing you to intercept and redefine operations performed on the latter by using the former as an intermediary.

When invoked with new, Proxy results in an object — no surprises there. It accepts two arguments: a target object and a handler object:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {};
const theProxyObject = new Proxy( targetObject, handlerObject );

console.log( theProxyObject );

/* Result (Firefox, expanded):
Proxy { <target>: {…}, <handler>: {} }
  <target>: Object { theProperty: "A string." }
  <handler>: Object {  }
*/

/* Result (Chrome, expanded):
Proxy(Object) {theProperty: 'A string.'}
  [[Handler]]: Object
  [[Target]]: Object
  [[IsRevoked]]: false
*/

Nothing too surprising in the console, here. Our newly-minted proxy object contains a reference to our target object and a set of internal slots, using that <> or [[]] notation — depending on the browser — which makes it clear that we're not meant to interact with these slots directly, the way we would interact with a string-based property key. [[Target]] is an internal slot representing the the object we want to act on, complete with the property we defined. [[Handler]] represents the handler object that acts as an intermediary for interacting with the target object.

I bet that [[isRevoked]] in Chrome jumped out at you right away. Don't worry, we haven't hit upon some big 2010-style discrepancy in browser behavior — just a difference in how an internal slot is surfaced. We’ll get there in a bit.

If we change the value associated with the property we've defined on the target object, that change is reflected by the proxy object's reference to it:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {};
const theProxyObject = new Proxy( targetObject, handlerObject );

targetObject.theProperty = "Something else.";

console.log( theProxyObject );
/* Result (expanded):
Proxy { <target>: {…}, <handler>: {} }
  <target>: Object { theProperty: "Something else." }
  <handler>: Object {  }
*/

At a glance, this feels like some classic "by-reference" stuff — "object values are stored by reference," "objects are a collection of properties," "objects are the powerhouse of the script," et cetera. Remember, however, that we're not talking about variables or properties — in this case, the proxy object is itself a reference to the target object. That proxy object can be used in place of the target object, wholesale:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {};
const theProxyObject = new Proxy( targetObject, handlerObject );

console.log( theProxyObject.theProperty );

// Result: A string.

Accessing a property of the proxy object is effectively accessing that property on the target object, by way of the proxy object. You can't define an own property on the proxy object as usual, either — instead, that property will be defined on the target:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {};
const theProxyObject = new Proxy( targetObject, handlerObject );

theProxyObject.theOtherProperty = "Another string";

console.log( theProxyObject );

/* Result (expanded):
Proxy { <target>: {…}, <handler>: {} }
  <target>: Object { theProperty: "A string.", theOtherProperty: "Another string" }
  <handler>: Object {  }
*/

Used the way you've seen it so far here, well, we've basically just created an unusual reference value with extra steps, but that's only because we're not asking the handler object to do anything by way of our proxy object — here, the handler object is basically acting as a translator from one language to that same language. The use case becomes a little more clear when we start creating handler functions on its handler object, sometimes called traps:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {
  get() {
    return "Something else entirely.";
  }
};
const theProxyObject = new Proxy( targetObject, handlerObject );

console.log( theProxyObject.theProperty );
// Result: "Something else entirely." )

There’s a corresponding trap for every operation that can be performed on an object, all named in relatively predictable ways. That get() method defined on the handler object is a trap for the [[Get]] internal method, which is fired whenever you attempt to access the value of an object property. By making it return an explicit value this way, well, we messed up a perfectly good [[Get]] operation is what we did — we've intercepted that operation and changed what should result from it. Now no matter what we do with our targetObject, attempting to access the value of any property will result in exactly what we said it should:

const targetObject = {
  theProperty: "A string."
};
const handlerObject = {
  get() {
    return "You've just activated my trap function!";
  }
};
const theProxyObject = new Proxy( targetObject, handlerObject );

console.log( theProxyObject );

/* Result (expanded):
Proxy { <target>: {…}, <handler>: {…} }
  <target>: Object { theProperty: "A string." }
  <handler>: Object { get: get() }
*/

targetObject.newProperty = true;

console.log( theProxyObject );

/* Result (expanded):
Proxy { <target>: {…}, <handler>: {…} }
  <target>: Object { theProperty: "A string.", newProperty: true }
  <handler>: Object { get: get() }
*/

console.log( theProxyObject.newProperty );
// Result: You've just activated my trap function!

console.log( theProxyObject[ "newProperty" ] );
// Result: You've just activated my trap function!

And like any function, we can have that trap function perform whatever tasks we want:

const targetObject = {
  theProperty: true
};
const handlerObject = {
  get() {
    console.log( "Psych!" );
    return false;
  }
};
const theProxyObject = new Proxy( targetObject, handlerObject );

console.log( theProxyObject.theProperty );

/* Result:
Psych!
false
*/

Naturally, that includes manipulating the results of those operations with a little more finesse than a console.log and a string. The get() method of a handler object accepts three arguments: one representing the target object, one representing the key for the property being accessed, and one representing the "receiver," which is a little higher-concept: the receiver argument represents the value of this within the context of the getter method — a reference to the object bound to the get method at the time when that method is invoked — that might sound fraught, as this is wont to be, but in most cases that will be the target object.

Given these arguments, we're able to use our get method to access and manipulate the values of our target object's properties:

const targetObject = {
  theProperty: 10
};
const handlerObject = {
  get( target, propertyKey, receiver) {
    return target[ propertyKey ] * 2;
  }
};
const theDoubleObject = new Proxy( targetObject, handlerObject );

console.log( theDoubleObject.theProperty );
// Result: 20

const targetObject = {};
const handlerObject = {};
const revocableProxy = Proxy.revocable( targetObject, handlerObject );

const revocableProxy = Proxy.revocable({}, {});

console.log( revocableProxy );

/* Result (expanded):
Object { proxy: Proxy, revoke: () }
  proxy: Proxy { <target>: {}, <handler>: {} }
    <target>: Object {  }
    <handler>: Object {  }
  revoke: function ()
*/

/* Result (Chrome, expanded):
Object { proxy: Proxy, revoke: () }
  proxy: Proxy(Object)
    [[Handler]]: Object
    [[Target]]: Object
    [[IsRevoked]]: false
  revoke: ƒ ()
*/

const revocableProxy = Proxy.revocable({}, {});

revocableProxy.revoke();

console.log( revocableProxy );

/* Result (expanded):
Object { proxy: Proxy, revoke: () }
  proxy: Proxy { <target>: {}, <handler>: {} }
    <target>: null
    <handler>: null
  revoke: function ()
*/

/* Result (Chrome, expanded):
Object { proxy: Proxy, revoke: () }
  proxy: Proxy(Object)
    [[Handler]]: null
    [[Target]]: null
    [[IsRevoked]]: true
  revoke: ƒ ()
*/

Every one of an object's internal methods has a corresponding trap, which means that you're able to alter the basal behavior of any object, at every possible level, language-wide:

const targetObject = {
  theProperty: "Still here."
};

const handlerObject = {
  deleteProperty( target, key) {
    console.log( "No." );
    return false;
  },
  has( target, key ) {
    console.log( "None of your business." );
    return false;
  },
  getPrototypeOf( target ) {
    console.log( "Who knows?" );
    return null;
  }
};

const theImmovableObject = new Proxy( targetObject, handlerObject );

delete theImmovableObject.theProperty;
/* Result:
No.
false
*/

console.log( theImmovableObject.theProperty );
// Result: Still here.

console.log( "theProperty" in theImmovableObject );
/* Result: 
None of your business.
false
*/

console.log( Object.getPrototypeOf( theImmovableObject ) );
/* Result: 
Who knows?
null
*/

So, y'know, just make sure you do it right.

No pressure or anything.

Oh, hey, speaking-of:

Reflect

You might have noticed a few things about the code examples you've seen so far here. One, we're partying like it's 2009 — accessing properties using olde timey bracket notation.

Two, it's a little unsettling to [[Get]] a property value within the context of changing the way [[Get]]-ing a property value works, using the very syntaxes we’re changing. It works fine, but the vibes, in strict technical terms, are off.

Third, and by far most importantly: breaking with assumptions as major as "when I create a property on an object, it will happen the way I expect" will absolutely lead to issues in our code somewhere down the line, if not right away. Being able to alter the essential nature of objects themselves draws a razor-thin line between "exciting" and "terrifying," especially when it comes to future maintainability, and the idea of working on a codebase littered with objects that may or may not work like objects is the stuff of nightmares.

For that reason, the ES-262 specification helpfully outlines the following invariants for, say, [[Set]] — that is, the rules that a [[Set]] operation must follow:

• The result of [[Set]] is a Boolean value.
• Cannot change the value of a property to be different from the value of the corresponding target object property if the corresponding target object property is a non-writable, non-configurable own data property.
• Cannot set the value of a property if the corresponding target object property is a non-configurable own accessor property that has undefined as its [[Set]] attribute.

Once you start tinkering with how a [[Set]] operation works, well, following those rules is now on you. If I were to write something along the lines of the following:

const handlerObject = {
  set( target, propertyKey, value, receiver) {
    return target[ propertyKey ] = value * 2;
  }
};

const setDoubler = new Proxy( {}, handlerObject );

setDoubler.theProperty = 2;

console.log( setDoubler.theProperty );
// Result: 4

My [[Set]] operation didn't return a boolean value the way JavaScript expects, per the sacred invariant rules of [[Set]]. I mean, this snippet will still work, in that we’re outside strict mode, the returned value is coerced to a Boolean, and this one happens to be truthy. It won’t work in every context:

"use strict";
const handlerObject = {
  set( target, propertyKey, value, receiver) {
    return target[ propertyKey ] = value * 2;
  }
};

const setDoubler = new Proxy( {}, handlerObject );

setDoubler.theProperty = 0;

console.log( setDoubler.theProperty );

// Result: Uncaught TypeError: proxy set handler returned false for property '"theProperty"'

We could rewrite this to explicitly return that expected boolean value, naturally, but even dealing with this simple handler method we find ourselves in "I need to be careful to always do this in this way" territory lest we introduce fundamentally bugged objects to our codebase. Nobody needs that.

That brings us to the Reflect object: a collection of static methods, each with the same name and parameters as our proxy handler methods. Reflect gives us some guardrails to address all of the above concerns (bad vibes and all) by providing us with a set of methods for interacting with objects that all ensure we never deviate too far from how objects are meant to work.

Reflect is a namespace object — an ordinary object made up of static properties and methods, like the Math or Temporal objects:

console.log( Reflect );

/* Result (expanded):
  apply: function apply()
  construct: function construct()
  defineProperty: function defineProperty()
  deleteProperty: function deleteProperty()
  get: function get()
  getOwnPropertyDescriptor: function getOwnPropertyDescriptor()
  getPrototypeOf: function getPrototypeOf()
  has: function has()
  isExtensible: function isExtensible()
  ownKeys: function ownKeys()
  preventExtensions: function preventExtensions()
  set: function set()
  setPrototypeOf: function setPrototypeOf()
  Symbol(Symbol.toStringTag): "Reflect"
*/

Every one of those methods maps to the names of your proxy object handler methods and expects the same parameters, in the same way — their syntax matches the context we're working in much more than bracket notation. That alone works wonders for the vibes, if you ask me:

const handlerObject = {
  set( target, propertyKey, value) {
    return Reflect.set( target, propertyKey, value * 2 );
  }
};

const setDoubler = new Proxy( {}, handlerObject );

setDoubler.theProperty = 2;

console.log( setDoubler.theProperty );
// Result: 4

No fuss, no muss, and — most importantly — no poring over the ES-262 specification to ensure that we're not accidentally deviating from The Rules of Objects as They Are Played, because Reflect.set() performs the [[Set]] operation we want and returns the expected boolean value, per the specification. With Proxy we can change how objects work, and with Reflect we can make sure our changed objects still work the way objects are meant to.

Putting it together

When we put this all together, we can use proxy objects and Reflect to perform tasks like validating data:

const validationHandler = {
  set( target, propertyKey, value, receiver ) {
    if( typeof value === "string" ) {
      return Reflect.set( target, propertyKey, value );
    } else {
      console.error( "This object only accepts strings." );
      return false;
    }
  }
};
const validatedObject = new Proxy({}, validationHandler );

validatedObject.newProperty = true;
// Result: This object only accepts strings.

console.log( validatedObject );
/* Result:
Proxy { <target>: {}, <handler>: {…} }
  <target>: Object {  }
  <handler>: Object { set: set(target, propertyKey, value, receiver) }
*/

...Or setting and maintaining the internal state of an object — for example, the number of times an object's given property has been accessed:

const handlerObject = {
  accessCounter( target, accessed) {
    Reflect.set( target, "timesAccessed", accessed ? accessed + 1 : 1 );
  },
  set( target, key, value) {
    this.accessCounter( target, Reflect.get( target, "timesAccessed" ) );

    return Reflect.set( target, key, value );
  },
  get( target, key) {
    this.accessCounter( target, Reflect.get( target, "timesAccessed" ) );

    return Reflect.get( target, key );
  }
};

const stateObject = new Proxy({}, handlerObject );

console.log( stateObject );

/* Result (expanded):
Proxy { <target>: {…}, <handler>: {…} }
  <target>: Object {  }
  <handler>: Object { accessCounter: accessCounter(accessed), set: set(target, propertyKey, value, receiver), get: get(target, propertyKey, receiver) }
*/

stateObject.newProperty = true;
// Result: true

console.log( stateObject );
/* Result (expanded):
Proxy { <target>: {…}, <handler>: {…} }
  <target>: Object { timesAccessed: 1, newProperty: true }
  <handler>: Object { accessCounter: accessCounter(accessed), set: set(target, propertyKey, value, receiver), get: get(target, propertyKey, receiver) }
*/

console.log( stateObject.newProperty );
// Result: true

console.log( stateObject );
/* Result (expanded):
Proxy { <target>: {…}, <handler>: {…} }
  <target>: Object { timesAccessed: 2, newProperty: true }
  <handler>: Object { accessCounter: accessCounter(accessed), set: set(target, propertyKey, value, receiver), get: get(target, propertyKey, receiver) }
*/

Those are kind of novelties when we're acting on a single object, sure — but with the approaches and syntaxes you've already learned and a little imagination, it isn't hard to see where proxy objects could be used to create an entire state system with just a few more lines of code, and without the need for bulky frameworks or third-party tools:

function reactiveState( target) {
  const subscribed = new Map();

  return new Proxy({
    ...target,
    subscribe( key, callbackFunc) {
        // If it isn't there already, add it to `subscribed`:
        if( !subscribed.has( key ) ) {
          subscribed.set( key, [] );
        }
        // Associate the callback function with the subscribed object:
        subscribed.get( key ).push( callbackFunc );
      }
    }, {
      set( target, key, value, receiver) {
        const result = Reflect.set( target, key, value );

        // If this is the subscribed-to property...
        if( subscribed.has( key ) ) {
          // ...invoke the callback function with the explicit `this` value of the original object:
          subscribed.get( key ).forEach( callbackFunc => callbackFunc.call( receiver, key ) );
        }

        return result;
      }
    });
}

// Declare a callback function to be called when the state of an object changes:
const callbackLogger = function( key) {
  const enCardinal = new Intl.PluralRules( "en-US" );
  const counter = this[ key ];
  const pluralize = count => enCardinal.select( counter ) === "one" ? `` : `s`;

  console.info(`${this.component }.${ key } has been changed ${ counter } time${ pluralize( counter ) }.`);
};

const widget = reactiveState({ component: "widget", count: 0 });
const gizmo = reactiveState({ component: "gizmo", otherCounter: 0 });

// When the `count` property of our widget object changes, call the callbackLogger:
widget.subscribe( 'count', callbackLogger );

// When the `otherCounter` property of our gizmo object changes, call the callbackLogger:
gizmo.subscribe( 'otherCounter', callbackLogger );

widget.count++;
// Result: widget.count has been changed 1 time.

widget.count++;
// Result: widget.count has been changed 2 times.

// We're not subscribed to a `count` property for the gizmo object, so nothing happens here:
gizmo.count++;

// But we _are_ subscribed to an `otherCounter` property for the gizmo object:
gizmo.otherCounter++;
// Result: gizmo.otherCounter has been changed 1 time.

widget.count++;
// Result: widget.count has been changed 3 times.

Now, listen. I don’t want to trot out any more cliches here, but I won't deny that there's an impulse to wrap this lesson up with a call for temperance — to leave you with a warning about how proxy objects are "as powerful as they are dangerous," and "great power-slash-responsibility" and et cetera, then maybe a little bit about how there is, at least, some cold comfort to be found in Reflect. That's not coming from nowhere, that impulse — altering how the principle building blocks of a language work, at their most fundamental levels, can break stuff pretty bad. No two ways about that.

You know me, though: if I wanted to spend my cortisol on "worrying about getting things wrong," I would've gone to medical school or learned PHP. If you ask me, Proxy and Reflect are brand new, shining examples of the enduring spirit of JavaScript: use the language to change the language, and find new ways to solve problems never even imagined by the hundreds of people who've gotten a hand on the ball since 1995.

Well, "brand new" as of 2015.

The Reflect object gives you some vital future-headache-prevention guardrails, and you should use them, of course — that's what they're there for.

I won't tell you to "be careful," though. Get in there and break stuff; there's no better way to learn. Besides, nothin' reloading the page can't fix, right?

If you are wondering what 'lexicons' and 'the Atmosphere' are, don't fret. This article will explain what they mean, why you should care about Standard.site, and walk you through exactly how you can implement Standard.site using some simple JavaScript or a plugin for your favourite content management system.

What Standard.site is and why you should care

If Bluesky is the network's answer to short-form microblogging, think of Standard.site as its equivalent for blogs, newsletters, and long-form journalism.

At its core, Standard.site is an open schema that dictates how articles and essays should be formatted as data. When you publish a blog post normally, it lives on your website and relies on scrapers or RSS feeds to be shared. By adopting the Standard.site lexicon, your long-form content becomes a natively understood piece of data on the decentralised web.

One of the most overt benefits we get from defining Standard.site lexicons for our publication are enhanced rich embeds on Bluesky, like this:

We also get many other benefits. For example, I was surprised to see that the professional identity network Sifa ID displayed my posts upon my profile. It was also pleasant to see my posts naturally populate on readers like pckt, Docs.surf, potatonet, and Leaflet without any additional work on my part.

The strength of AT Protocol is that data is interoperable and can be shared, which plays into the strength of Standard.site, which is that a single set of well structured-schemas. The result is that various indexers and tools can all work with the available data in their own ways, knowing how it'll be structured. Your content can be moved between hosts without losing your data or the audience you've built, and there is no single controlling authority. To get further into this, however, we must first establish an understanding of the AT Protocol.

Understanding the AT Protocol

To implement Standard.site, you will want to understand the Authenticated Transfer Protocol (known colloquially as the 'AT Protocol' or 'atproto') at least at a surface level. The AT Protocol is a decentralised system designed to give users ownership of their data.

To explain it at its simplest, you have a Personal Data Server (PDS) which hosts user accounts. Currently, the largest PDS is provided by Bluesky, but anyone can run their own. A PDS holds lots of user accounts, and each user account can hold records, which are data.

Each user account can be identified by a globally unique DID (Decentralised Identifier) that acts as their permanent ID. A DID looks like this: did:plc:7qg6mz2xtzozxkgbcvf4pdnu. Each account also has a handle, which comes in the form of a DNS record. We can see this in that people on Bluesky's PDS who haven't configured a custom domain for their account have a handle like this: bsky.bsky.social. If you navigate to that in a browser, it'll take you to the Bluesky page: https://bsky.bsky.social.

Each account features a data repository that holds collections of JSON records. These JSON records must follow specific structures called lexicons. Lexicons are just schemas, like JSON-Schema or OpenAPI, which define how the JSON must be structured and formatted. Records are put into 'collections', which we can think of as folders. A collection is identified by a Namespace Identifier (NSID) which makes reference to a domain to identify schemas.

Let’s run through an example with Bluesky so we can really get a handle on things. When a user signs up to Bluesky, a self record is created in the app.bsky.actor.profile collection of that user's data repository with information about the account, like its name and profile description. Piccalilli's looks something like this:

{
  "uri": "at://did:plc:lyk2pixxcmyeu4jrapaq26fy/app.bsky.actor.profile/self",
  "cid": "bafyreihzo3igobmunvk6tmsaqgyatyw5gona4kiayvm2f62lymc5dzqjvu",
  "value": {
    "$type": "app.bsky.actor.profile",
    "createdAt": "2024-08-01T12:44:51.324Z",
    "description": "Level up your front-end skills. Stay for the approachable, friendly content and go away with transferable skills you can use day to day.",
    "displayName": "Piccalilli"
  }
}

Then, every time a post is made, or the Piccalilli account likes something, or blocks someone, or does anything else on Bluesky, a new record is created to represent that action. For instance, when Piccalilli reposts something, a new record is created under the app.bsky.feed.repost collection.

Almost everything is a record, inside a collection, under a user account (identified by a DID), on a PDS.

Notably, everything on ATProto is public. There is no concept of private records, which means we can go out and inspect or reference all the data on the protocol. There are a number of tools for inspecting AT Protocol data, but Taproot and PDSLs are my favourites. Search for your account handle, and you'll be greeted by your underlying records. Have a poke around to help wrap your head around the structure and how everything fits together.

The two core records

Now we've (hopefully) got at least (somewhat) of a (fledgeling) understanding of AT Protocol, we can start hooking up Standard.site. To get started with Standard.site, we need to create two specific types of records in your AT Protocol repository:

1. A Publication Record, which defines information about our publication itself.
2. Document Records, which contain information about individual articles themselves.

It is these records that Bluesky and the rest of the Atmosphere will reference. You can create them any one of a number of ways. AT Protocol is very open, and you can create records via a variety of methods, but for the purposes of this article, I'll be showing a JavaScript approach using the official @atproto/api npm package.

You will need to authenticate to create these records. The easiest way to do so is by creating an app password under Privacy and Security in Bluesky's settings. An app password gives access to your account and looks like this: fg2g-xob3-xl78-5ezy.

Publication record

The first step in support is having a publication record adhering to the site.standard.publication lexicon. You only need to create this record once per-publication.

Using the AT Protocol SDK, you can authenticate and create this underlying JSON record for your site with the script below, replacing the template values here with your publication's details.

For the purpose of illustration, this script only sets required properties.

import { AtpAgent } from "@atproto/api";

// Initialise the agent (use your specific PDS if not on Bluesky)
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function createPublicationRecord() {
  // 1. Authenticate (Always use an App Password, never your main password)
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 2. Define the Publication Record
  const publicationRecord = {
    $type: "site.standard.publication",
    url: "<https://example.com>",
    name: "My Awesome Blog",
  };

  // 3. Write the record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.publication",
      record: publicationRecord,
    });

    console.log("Publication record created!");
    console.log("Your AT-URI is:", response.data.uri);
  } catch (error) {
    console.error("Failed to create publication:", error);
  }
}

createPublicationRecord();

If this script was successful, it should output a message reading 'Publication record created!', followed by an AT-URI. Save this, because we'll need it later. In the future if we need to amend this record, we can revise the record directly.

Theming

Though the above script is great, we can take it a bit further and add some more pizazz by defining a theme. You can create a theme to lend some more style to how your content displays in readers and how Bluesky embeds it. This is done by adding theming fields to your publication record. You need to specify a background, foreground, accent, and accentForeground. If you're setting any of these values, you must set all of them.

Bluesky uses accent and accentForeground like so:

You should check that your foreground and background and accent and accent foreground all have appropriate contrast. Bluesky previously took these values directly, but now they do some contrast adjustment of their own.

You, unfortunately, cannot change the text which appears on the Bluesky embed button, which will always be 'View Publication' if you publish yourself. Some external Standard.site enabled services have their own special buttons with custom text and icons, but these are hard coded in the Bluesky client.

Verifying your publication

Next, we have the optional step of creating a file at /.well-known/site.standard.publication containing the AT-URL outputted by our record creation script. This verifies that your domain controls your publication record.

Most services, Bluesky included, don't require this verification. Indeed, some hosts might not let you write to the /.well-known path. However, if you can create a file named site.standard.publication within /.well-known and put your AT-URL within it, your publication will be more widely supported. This verification only needs to be done once.

You can check this has been created correctly by going to your URL on your site. For example, for my personal website, I can visit https://vale.rocks/.well-known/site.standard.publication in my browser and see my AT-URI:

at://did:plc:7qg6mz2xtzozxkgbcvf4pdnu/site.standard.publication/3mn2c332ulp2u

Document records

Now that your publication record exists, you need to create per-document records following the site.standard.document lexicon. Every document needs its own record.

Standard.site supports having your document's content in the record, which is the approach that Offprint, pckt, Leaflet, and some other publishing platforms use. Whether you do this is up to you.

If you do include the content, then it can be displayed natively in Standard.site reader applications, and Bluesky embeds will provide a reading time estimate. For the purpose of this script, I'll again only be including required properties.

import { AtpAgent } from "@atproto/api";
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function publishDocumentRecrd() {
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 1. Define the Document Record
  const documentRecord = {
    $type: "site.standard.document",
    site: `at://your-did/site.standard.publication/your-pub-rkey`, // Full AT-URI of your publication
    title: "My New Post",
    publishedAt: "2026-06-11T00:00:00.000Z",
  };

  // 2. Write the record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.document",
      record: documentRecord,
    });

    console.log("Success! Document record published to the Atmosphere:");
    console.log(response.data.uri);
  } catch (error) {
    console.error("Failed to publish document:", error);
  }
}

publishDocumentRecord();

If this script was successful, it should output a message reading 'Success! Document record published to the Atmosphere:', followed by an AT-URI. Save this, because we need it to verify the document.

Verifying your document

To complete the two-way verification, the HTML <head> of your live article must contain a link tag pointing back to the document record you just created:

<link rel="site.standard.document" href="at://did:plc:your-did/site.standard.document/the-record-rkey" />

Once these ends are tied together, your webpage and document record point to each other, and clients across the decentralised web can seamlessly reference the record.

Adding images

If you look through the Standard.site docs at all, you might notice references to icons and cover images. To make use of these, we must upload a blob, which is what unstructured data (like images) within a repository are called.

We need to upload the blob first, so that we can refer to it with a reference in our record. Here is an example of uploading an image as a blob and then referencing it to use it as a cover image.

import fs from "fs";
import { AtpAgent } from "@atproto/api";
const agent = new AtpAgent({ service: "<https://bsky.social>" });

async function uploadImageAndPublishDocument() {
  await agent.login({
    identifier: "your-handle.bsky.social",
    password: "your-app-password",
  });

  const did = agent.session.did;

  // 1. Read the local image file into a buffer
  const imageBuffer = fs.readFileSync("./path/to/your/cover.jpg");

  // 2. Upload the blob to your repository
  const { data: blobResponse } = await agent.com.atproto.repo.uploadBlob(
    imageBuffer,
    { encoding: "image/jpeg" }
  );

  console.log("Blob successfully uploaded!");

  // 3. Define the Document Record, attaching the returned blob reference
  const documentRecord = {
    $type: "site.standard.document",
    site: `at://your-did/site.standard.publication/your-pub-rkey`,
    title: "My New Post with a Cover Image",
    publishedAt: "2026-06-18T12:00:00.000Z",
    cover: blobResponse.blob, // This links the blob to your document
  };

  // 4. Write the document record to your repository
  try {
    const response = await agent.com.atproto.repo.createRecord({
      repo: did,
      collection: "site.standard.document",
      record: documentRecord,
    });

    console.log("Document record with cover image published:");
    console.log(response.data.uri);
  } catch (error) {
    console.error("Failed to publish document:", error);
  }
}

uploadImageAndPublishDocument();

Setting up Standard.site on CMS platforms

If writing JavaScript to push records manually sounds tedious, or you're already using a major content management system, you might prefer to have the process handled for you. How you integrate Standard.site depends very much on how your own site is built, and some platforms have ready-made integrations via plugins that handle all of the above behind the scenes:

• WordPress: Has the ATmosphere plugin and the Wireservice plugin.
• CraftCMS: Has a plugin simply called Standard.site.
• Obsidian: Has a community plugin.
• Static sites: Generators like 11ty, Hugo, Astro, and Jekyll can use a dedicated CLI tool called Sequoia.

Checking it works

Obviously, creating all these records and configuring all this Standard.site business is a bit useless if it doesn't actually work. The easiest way to test is by just plopping a link to a post on Bluesky and hoping it embeds, but if it doesn't, it can feel a tad opaque when it comes to figuring out what went wrong.

To rectify this, you can make use of Standard.site Validator by Thomas Karpiniec. Consider returning to Taproot or PDSLs to study and review your records. Both will let you know if anything fails to validate and where things went awry.

Further reading

For some further reading, Piccalilli's own Mat Marquis, creator of the JavaScript for Everyone course, has written his own posts documenting his understanding of and implementation of Standard.site on his own blog.

If you want to have multiple Standard.site publications under a single domain, then Jason Lengstorf has an in-depth guide on the Code.TV blog.