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.

All that said, for the purposes of this article, I’m a front-end web developer who has spent their 7 year career building a product for testing accessibility of mobile apps. I’d like to give you — a front-end web developer, who may not have mobile experience — a quick run-through to the mobile apps built with web technologies landscape.

What is a hybrid mobile app?

As a front-end web developer, we’re used to our HTML content being rendered in the browser whether it’s being generated by a framework like React or Vue, or being served from an HTML file.

The mobile app world is a quite different story where the rendered content doesn’t follow agreed upon and maintained guidance, like web standards. For example, Apple and Google completely govern their own native tech stacks for building iOS and Android apps respectively. Those tech stacks create elements on the screen called Views. Then there’s the 3rd party cross-platform frameworks such as React Native, .NET MAUI (previously Xamarin), Flutter. These all allow you to build both an Android and iOS app, and sometimes a web and/or desktop app, from a single code base, but they each do that process a bit differently to each other.

React Native and .NET MAUI generate Views that mimic or are very similar to native mobile Views. They are designed to use technologies familiar to React and .NET developers: TypeScript/JavaScript with CSS and C# with XAML. Flutter is in it’s own league because it uses Dart to build Widgets that are rendered by it’s own graphics engine, bypassing the concept of native Views entirely.

While all these frameworks are often referred to in discussions of hybrid mobile apps, I prefer to distinguish them as cross-platform or code-once frameworks and reserve hybrid to specifically describe the subset of apps which present a blend of web and mobile content.

We’ll define a hybrid mobile app as follows: “A mobile app which primarily features HTML content rendered in WebViews alongside some native mobile content or functionality”

A WebView is a native mobile View which acts as an embedded web browser component to render HTML content inside of it instead of native controls like sliders or buttons. The mobile browser apps such as Safari and Chrome utilize a WebView as the main component with the addition of peripherals like the URL bar and back button. That’s a route to web developers to feel empowered rather than hindered.

The cross-platform framework names I haven’t mentioned yet are by this definition, hybrid app development frameworks: Ionic, Capacitor, Cordova/PhoneGap. It’s a bit complicated to untangle what each framework is and does, so we’ll dive into that in the next section.

Hybrid App Development Frameworks

Let’s start by talking about Apache Cordova/Adobe PhoneGap, since it’s the original hybrid framework, created back in 2009. Here’s the overview statement on the Cordova documentation site:

Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies - HTML5, CSS3, and JavaScript for cross-platform development. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's capabilities such as sensors, data, network status, etc.

There’s some history with the project being acquired by Adobe, including in an offering called PhoneGap, but that was discontinued in 2020. Cordova is still alive and actively maintained, but you may see references to PhoneGap while looking for hybrid app development topics.

Cordova isn’t a UI framework, but rather a runtime environment for your web app on a mobile device. This means you could take an existing web app that you built with your favorite front-end tools and package it up to render inside a WebView in both an iOS and Android app. Now there’s quite a lot of reasons why you wouldn’t want to to that, but let’s cover the other runtime frameworks first.

Capacitor is a newer option for a hybrid framework to ship your web content wrapped in a mobile app, developed in 2018 as a modern alternative to Cordova/PhoneGap. The intro on the Capacitor docs site reads:

Capacitor is a cross-platform native runtime that makes it easy to build performant mobile applications that run natively on iOS, Android, and more using modern web tooling. Representing the next evolution of Hybrid apps, Capacitor creates Web Native apps, providing a modern native container approach for teams who want to build web-first without sacrificing full access to native SDKs when they need it.

What separates Capacitor from Cordova is that it’s built and maintained by the Ionic framework team. While the former are both native runtime frameworks, Ionic is actually a front-end UI framework for hybrid apps. Ionic can be used with both Cordova and Capacitor, but Capacitor is designed specifically to work in conjunction with Ionic. Here’s the introduction on the Ionic docs site:

Ionic is an open source UI toolkit for building performant, high-quality mobile apps using web technologies — HTML, CSS, and JavaScript — with integrations for popular frameworks like Angular, React, and Vue.

Now we’re finally in the front-end developer’s domain! Before we dig into it too much, let’s go over some important design concepts for hybrid apps.

Designing a Hybrid App

Like I said earlier, you can use either Capacitor or Cordova, to wrap your existing web front-end into a WebView inside a mobile app, but there are some considerations to make since content built for the web is structured quite differently than content built for mobile.

For example, a common pattern in web apps is a single page with lot of content that can be scrolled to or jumped to with links/landmarks. Whereas, in a mobile app, content is often better presented in small chunks with navigation through a flow of multiple screens. Mobile app user experience is built around the fact that the content is displayed in a small viewport, but the web was originally built for desktop and adapted to suite mobile devices as their browser became more and more capable.

I’ve spoke with folks in the industry that claim most users can’t tell whether an app is presenting native content or a WebView, but I find that hard to believe. Maybe I’m biased because I know too much about both, but it says a lot if a user downloads your app instead of visiting your website since there’s a much higher barrier to entry. They likely took the extra effort to open the App Store or Play Store and remember or find their account password to install your app because they want a native mobile experience. One thing I can confidently say is that a screen reader user will definitely know the difference since it will literally announce WebView when they hit one, and the landmarks are different, like the fact that Android only has 1 level of heading compared to the 6 levels in HTML <h1>-<h6>.

So all that said, how do you build a stellar hybrid app user experience? By using the concepts of responsive and mobile-first web design of course!

Figma has a wonderful article which covers the topic focusing on websites, but can be applied to hybrid apps as well:

“Mobile-first website design flips the traditional Web development approach. Instead of starting with a desktop layout and scaling down, you begin with a mobile website design. This approach prioritizes smaller screens, slower Internet connections, and the needs of on-the-go users.”

Another layer to mobile-first design is that Android and iOS each have a look and feel uniquely branded to Google and Apple. We’ve established that the web and mobile ecosystems are very different, but iOS and Android are almost just as different too. So you’re faced with some choices: design 2 experiences, pick iOS or Android and ship it to the other platform anyways, or roll your own that ideally caters to both. Trust me, I’ve seen it all, and my least favorite is an Android styled app shipped to iOS

While companies/brands love the idea of a consistent experience across platforms, users prefer your app to look behave like the rest on their device do. A lot of factors go into choosing a design pattern for an app such as target audience, development resource capacity, etc, so let’s set that aside and finally dig into building the bits

Building a Hybrid app Front-end

I want to bring us back to Ionic because its UI component library allowing front-end developers to build seamless experiences for both iOS and Android from a single codebase using technologies you know and love. It’s full of mobile-first components which render on iOS matching Apple’s aesthetics and on Android matching Material Design, Google’s open-source design system. These components are available in Angular, React, Vue, and plain ole JavaScript with beautiful interactive demos on the documentation site.

Let’s take a closer look at a Toggle component which is commonly used in the settings of a mobile app. In React, you import the IonToggle from Ionic’s library and use it just like you would any component for a web-first app.

import React from 'react';
import { IonToggle } from '@ionic/react';

function Example() {
  return (
    <>
      <IonToggle>Default Toggle</IonToggle>
      <IonToggle checked={true}>Checked Toggle</IonToggle>
      <IonToggle disabled={true}>Disabled Toggle</IonToggle>
      <IonToggle checked={true} disabled={true}>
        Disabled Checked Toggle
      </IonToggle>
    </>
  );
}
export default Example;

On iOS, you’ll get 4 toggles in Apple’s well known style.

For Android, the recognisable material design elements are used.

All of the Ionic components can be styled with CSS custom properties and standard CSS, so you can achieve that consistent experience across platforms by modifying the iOS and Android styles slightly or make them match exactly.

Accessibility

As digital accessibility advocate, I can’t write an article without touching on the topic. I think of accessibility in 2 realms: compliance and user experience.

The realm of compliance focuses on building digital content that adheres to the Web Content Accessibility Guidelines (WCAG). These are the guidelines which legislature around the world reference, and large enterprises strive to meet. There isn’t a similar de facto standard for mobile app accessibility despite the immense difference in how content is rendered, but instead, there’s only adaptations and interpretations of WCAG for mobile.

On the other hand, Apple and Google put emphasis on accessibility through the user experience of the iOS and Android ecosystems. There’s Apple’s Human Interface Guidelines with a foundations section dedicated to accessibility, and the Android Developer guide on accessibility.

There’s no straightforward way to make a perfectly accessible app today, but that’s ok! Just as with most things in life, it’s about finding the right balance. On the compliance side, that WebView inside a mobile app is rendering HTML, so WCAG criteria can be directly applied, so there’s certainly advantages for hybrid apps in that regard. However, accessibility compliance doesn’t always equate to a high quality user experience, which is where the advice from Apple and Google come into play.

Wrapping up

While the world of mobile apps can be intimidating to a front-end web developer, it’s certainly worth exploring, even to be aware of the landscape for if you find yourself in a project in the future.

With that in mind, I hope this article is a useful introduction and shows that you don’t have to step completely out of your comfort zone thanks to the concept of hybrid mobile apps, providing a very familiar experience. It makes them a useful jumping off point!