When to use the id attribute

Associate a button with a form

A form's submit button doesn't need to be nested inside the form element if the form element is assigned a unique id and the button has a form attribute with the same value.

<form id="nameForm">
  <input name="name" />
  <input name="surname" />
</form>

...

<button type="submit" form="nameForm">
  Submit the form
</button>

Associate a label with an input

Every input element needs a companion label input. It's not enough to just render text near the input though, the label must be properly associated with the input so that browsers know they're associated. This doesn't just help screen readers, the label text is part of the focus area for the input so users expect to be able to click on the label text to focus on the input. This UX is provided for free as the input is rendered inside the label or if the input has a unique id and the label has a for attribute with the same value.

<label for="givenNameField">
  Given name
</label>
<input id="givenNameField" type="text" />

Indicate an element should be the accessible name of another

Using aria-labeledby on an element allows you to indicate that another element's contents should be considered the accessible name for the element. Screen readers use this when announcing an element to the user. This is similar to aria-label but aria-labeledby takes the highest precedence and should be preferred over aria-label so long as the appropriate text is rendered somewhere on the page.

The value of aria-labeledby can be a space-delimited list of IDs, so it's possible for the label to be comprised of multiple elements.

<h2 id="formTitle">Favorite color</h2>

<form aria-labeledby="formTitle">
  ...
</form>

Indicate an element should be the accessible description of another

Using aria-describedby on an element allows you to indicate that another element's contents describe the element. While it sounds similar to aria-labeledby, aria-describedby is intended to be used for longer descriptions. This is similar to aria-description but aria-describedby takes the highest precedence and should be preferred over aria-label so long as the appropriate text is rendered somewhere on the page.

The value of aria-describedby can be a space-delimited list of IDs, so the description can be comprised of multiple elements.

<p id="formDescription">
  Let us know what your favorite color is so we can send you some sweet swag!
</p>

<form aria-describedby="formDescription">
  ...
</form>

Indicate an element contains detailed information about another

Using aria-details on an element allows you to indicate that another element's contents contain additional details about it. This is very similar to aria-describedby the difference being that aria-details is intended to be used when the describing element contains more complex and structured content, such as lists, images, links, etc., and aria-describedby is intended to be used with a text-only description.

The value of aria-details can be a space-delimited list of IDs, so the detailed description can be comprised of multiple elements.

<button type="submit" aria-details="finePrint">
  Purchase
</button>

<div id="finePrint">
  <p>Purchasing this means that lorem ipsum whatever...</p>
  <h3>Known side effects</h3>
  <ul>
    <li>...</li>
    <li>...</li>
  </ul>
  <nav aria-label="More information">
    <ul>
      <li><a>...</a></li>
      <li><a>...</a></li>
      <li><a>...</a></li>
    </ul>
  </nav>
</div>

Indicate that interacting with an element affects another

In dynamic web pages, it's common to have buttons with cause-and-effect behavior that affects another element on the page. Clicking a button may make the content change somewhere else on the page, or maybe it makes a dialog appear. You can formalize this relationship by using aria-controls on the trigger element so that screen readers are able to relay this intent to the end user.

<button type="button" aria-controls="infoDialog" onclick="openDialog">
  Open dialog
</button>

<dialog id="infoDialog">
  ...
</dialog>

Indicate that an element contains an error message related to an input

Most custom form designs don't rely on the browser's native error handling. Instead, input error messages are rendered somewhere (hopefully near) the input it's related to. aria-errormessage should be used on the associated input element so that screen readers can properly relay this information to the user. Typically this should be used alongside aria-invalid.

<label for="nameInput">Name</label>
<input
  type="text"
  id="nameInput"
  aria-invalid="true"
  aria-errormessage="nameError"
/>
<p id="nameError">
  Sorry! We don't support names with emoji characters 😭
</p>

Suggest an alternative navigation flow through the page

Sometimes content on the page isn't in sequential order. Sometimes there is no real sequential order and multiple sections on the page could be viewed in any order. You can suggest an alternative flow through a page by using aria-flowto on an element to suggest one or more other elements that could be viewed next. Screen readers that support this won't force the flow onto the user, instead, they will suggest an alternative flow to the user and let the user decide. Support for aria-flowto isn't great as of right now, but it can be worth the minor effort of providing a great user experience.

<h1 aria-flowto="description details reviews">
  Super awesome product
</h1>

<section id="description">
  <h2>Description</h2>
  ...
</section>

<section id="details">
  <h2>More details</h2>
  ...
</section>

<section id="Reviews">
  <h2>Reviews</h2>
  ...
</section>

Indicate that an element should be treated as the parent of another

A parent-child relationship is an important part of the DOM hierarchy. Special design considerations and sometimes limited having limited control of the final DOM hierarchy can mean that you can't always render an element within the element where it should be placed. If this is the case and you need to modify the accessibility tree of a page you can override the interpreted hierarchy by setting aria-owns on the parent element to indicate that another element should be viewed as a direct child of that element. This should only be used when you don't have access to modify the DOM structure as it's preferred you just restructure the DOM if possible.

<dl aria-owns="additionalTerm additionalDescription">
  <dt>Term</dt>
  <dd>Value</dd>
</dl>

<dt id="additionalTerm">Another term</dt>
<dd id="additionalDescription">Another value</dd>

This example is the equivalent accessibly to:

<dl>
  <dt>Term</dt>
  <dd>Value</dd>
  <dt>Another term</dt>
  <dd>Another value</dd>
</dl>

Allow users to navigate to a specific place on a page

Anchor links allow you to link to a specific location within a page. This can be done by setting the fragment identifier in the URL to match the id of the element you want to link to. Since the fragment identifier is exposed to the end user through the URL, it's a good idea to ensure the target element's id is readable and intuitive. This can be useful in building a table of contents and allowing users to share a specific part of the page.

When not to use the id attribute

With so many good use cases for the id attribute, it's a good idea to avoid using it if doesn't solve one of the use cases listed above to avoid confusing other engineers and potentially creating a worse experience for the user.

Avoid using id as a CSS selector

The id can also be used as a CSS selector, like so:

#header {
  background: rebeccapurple;
}

While this is valid, it can create some issues down the road that should be considered.

High Specificity

It turns out that the "C" for "cascading" in CSS isn't the final decider regarding what rules apply to what elements. Specificity is also taken into account, and as it turns out id selectors have the highest specificity. This means that any rules declared using an id selector will have a higher priority over rules declared with other selectors, even if those rules are declared later on.

Low reusability

Since an id must be unique to each page; any style rules applied using an id selector can only apply to a single element (and its children) at a time. This doesn't promote reusability as those styles are limited to a single use case.

What to use instead

Prefer using class names or data attributes as CSS selectors.

Avoid using id as a JavaScript selector

It's possible to select an element in JavaScript by referencing the element's id like so:

document.getElementById('elementId')

While this is valid, it discourages reusability as the JavaScript code is forced to be tightly coupled to the DOM structure and it's not possible to re-use the code on multiple elements at the same time if necessary.

What to use instead

Prefer using unique data attributes as JavaScript selectors instead. This provides more flexibility and improves code readability as the data attribute can have a clear and descriptive name.

document.querySelectorAll('[data-vue-app]')
document.querySelector('[data-vue-app="myAppName"]')

Avoid using id as a selector in tests

Quality tests should avoid being tightly coupled to the HTML and DOM structure of the page; they should instead focus on testing the experience from the eyes of the user. It's possible for someone to come along, see an id on an element, and not see any accessibility advantage to having the id and remove it. This could break tests they didn't know about despite not making a change that affects the end-user experience.

What to use instead

Most testing frameworks have support for some type of "test id" such as data-testid. Refer to your testing library's best practices, but use a unique data attribute as a selector to improve code readability.

The anatomy of a URL

URL stands for Uniform Resource Locator, which is a standard way to identify the location of a resource on the web.

A URL consists of five distinct parts:

1. Protocol

2. Authority

3. Path

4. Query

5. Fragment

Check out this writeup on MDN docs if you're interested in learning about these parts in depth, but for state management purposes we primarily care about path, query, and fragment.

Path

The path is a forward slash "/" delimited address of where a resource resides.

An example of a path is

/blog/2023/01/01/name-of-article.html

Having a well-organized structure for managing paths can provide users with a better experience as it allows them to understand where they're located and potentially help them see where else they're able to go. It also makes it easier during development to generate links to other resources.

Every part of a path should be accessible

The structure of the URL path is a hint to the user of not just what resource they're currently viewing, but what resources are also available. A user should be able to access each part or layer of the path and be able to view that part of the resource.

With the /blog/2023/01/01/name-of-article.html example, a user would expect to be able to read the article. The path also exposes information to the user that they should be able to access other articles published on a particular day, month, or year. If the /name-of-article.html is removed and the user navigates to /blog/2023/01/01 then the user would expect to see a list of all articles published on that day, navigating to /blog/2023/01 would be expected to show a list of all articles published that month and visiting /blog would be expected to show a list of all articles published.

If you have a path like /users/12345/settings , you should also make sure you appropriately render content for /users and /users/12345 in addition to /users/12345/settings.

Paths should be consistent and predictable

If every part of a path is accessible, then it's important to ensure that every path is organized consistently and is predictable.

If /users/12345/settings displays the settings for user 12345, and /users/12345 displays a summary of user 12345, and /users displays a list of all users; then a user might be confused if they were to see /11111/product/inventory.

A good structure to follow is:

/<resource-name>/<resource-id>/<feature-or-association>/<association-id>

Some examples:

/products/1234/variants/5678
/products/1234
/products/1234/variants
/products

Query Parameters

While the path generally represents information related to what resource is meant to be displayed, the query represents how the resource should be displayed. The query is where resource modifiers and application state should be stored. This includes things like filters, search terms, and pagination info but can also include meta information used for analytics purposes. By default, HTML forms will also add form values to the query after a user submits a form.

Query parameters begin with a question mark (?) and consist of a key/value pair with an equal sign (=) separating the key and the value, and an ampersand "?" in between each pair.

For example:

/resources?pageNumber=4&searchTerm=books&maxPrice=10000

Store as much application state in the query as possible

There are a lot of benefits to the user when application state lives in the URL, for example, they can refresh the page without losing state, they can bookmark the page and access it later, or share it with someone else and make sure the other person sees the same thing they do. Any state that modifies the resource defined in the path should be stored in the URL as a query parameter.

A good rule of thumb is that if the user has access to modify the state, and that state is not persisted to the server via an API request, then it should be stored in the URL as a query parameter.

Fragment

A fragment appears at the end of the URL and is prefixed with a hashtag (#). This is used in what is referred to as "anchor links" or "jump links", and is used to focus on a particular element on the page. If the page has an element with an id matching the fragment in the URL, then the page is rendered with that element at the top of the screen. This is particularly useful for things like blogs or pages with lots of information as users can be directed to the most relevant place within a page instead of forcing them to find it on their own.

This page assigns an id to each section title, meaning you can navigate to https://webdev.tips/what-state-should-be-stored-in-the-url#fragment and the page will render with this section at the very top.

Use human-readable IDs for fragments that are exposed to users

Fragments should be readable and understandable to the average user, seeing a link like https://webdev.tips/what-state-should-be-stored-in-the-url#sdfsd2342342fsdaf23423 doesn't promote confidence as it doesn't tell the user where they'll navigate to if they were to click on it.

Ensure fragments work as expected

The browser typically handles navigating to fragments automatically, but if you're using a frontend framework then there's a chance your setup doesn't support fragments. Make sure to check that they work as expected.

Key Takeaways

1. The path should include the "what" that's rendered.

2. Query parameters should include all user-defined modifications of the "what" that's rendered.

3. The fragment should allow users to jump to specific places within the page.

const numbers = [10, 25, 2, 4, 1, 100, 6]

numbers.sort()

You would probably assume that since the values are numbers, it would sort them from smallest to biggest, right? Unfortunately, that's not the case and you end up with:

console.log(numbers)

// expected: [1, 2, 4, 6, 10, 25, 100]
// actual: [1, 10, 100, 2, 25, 4, 6]

The sort method's default comparison function converts values to strings before comparing them. So it converts the numbers to strings and then compares them alphabetically.

Since the default sort comparison converts values to strings and then compares them, you'd assume that it's safe to rely on it when sorting an array of strings, right? Unfortunately, that's not the case here either:

const letters = ['a', 'A', 'b', 'B']

letters.sort()
// expected: ['a', 'A', 'b', 'B']
// actual: ['A', 'B', 'a', 'b']

The default compare function sorts strings based on their UTF-16 values. This means that all uppercase characters are sorted before lowercase characters, and characters with accents are also sorted after characters without accents.

Customizing how an array is sorted

Since the default way arrays are sorted probably isn't what you want in practice, let's see how we can customize it so that it works the way you'd expect.

The .sort() method accepts a single parameter, which is called a compare function. This compare function should expect to be passed two values from the array and should return a number that indicates how those two items should be sorted. The .sort() method then calls this compare function to compare each item in the array to properly sort it.

If you were to define a type for the compare function, it would look like this:

interface SortCompareFunction<ArrayItemType> {
  (firstItem: ArrayItemType, secondItem: ArrayItemType): number
}

The way that the items are sorted depends on the number that the compare function returns and is based on if it's 0, positive, or negative.

How to sort numbers

Since the compare function is expected to return a number, you can just subtract one number from the other and return the difference. If the values are the same then it'll return 0, if the first is bigger, it will return a positive number, otherwise, it will return a negative number.

function compareNumbersInAscendingOrder(firstNumber: number, secondNumber: number) {
  return firstNumber - secondNumber
}

function compareNumbersInDescendingOrder(firstNumber: number, secondNumber: number) {
  return secondNumber - firstNumber
}

numbers.sort(compareNumbersInAscendingOrder)
// output: [1, 2, 4, 6, 10, 25, 100]

numbers.sort(compareNumbersInDescendingOrder)
// output: [100, 25, 10, 6, 4, 2, 1]

How to sort strings

Strings come with their own localeCompare method which can be used to sort strings how you might expect. It's based on the Int.Collator constructor and accepts all the same options so that you can further customize how strings are compared.

function compareStringsInAscendingOrder(firstString: string, secondString: string) {
  // Set the locale based on the string's locale, otherwise set to undefined to use the browser's locale.
  return firstString.localeCompare(secondString, 'en', { caseFirst: 'upper' })
}

function compareStringsInDescendingOrder(firstString: string, secondString: string) {
  return secondString.localeCompare(firstString, 'en', { caseFirst: 'upper' })
}

letters.sort(compareStringsInAscendingOrder)
// output: ["A", "a", "B", "b"] 

letters.sort(compareStringsInDescendingOrder)
// output: ["b", "B", "a", "A"]

Depending on how often you're sorting and how big the array is that you're sorting, you may run into some performance issues since each time the localeCompare is called a new instance of the Intl.Collator is created. You can resolve this by creating your own instance of the Intl.Collator once and then just referencing it.

const enCollator = new Intl.Collator('en', { caseFirst: 'upper' })

hugeListOfWordsThatNeedSorting.sort(enCollator.compare)

Reusing compare functions

While the examples above declare the compare functions on their own, it's more common to see the compare function declared directly inside the .sort() method as an anonymous function like so:

numbers.sort((firstNumber, secondNumber) => {
  return firstNumber - secondNumber
})

This can be good for one-off and shorter compare functions, but if you're doing a lot of sorting it can be beneficial to share compare functions from a common location so they can be re-used throughout your app since there's a good chance that many of them can be highly reusable.

import { byNumberAsc } from '~/utils/sort'

numbers.sort(byNumberAsc)

Eslint rule

If you use ESLint with typescript-eslint, there's actually a rule called require-array-sort-compare you can enable to help make sure you never forget to provide a compare function when sorting. It can be easy to forget and have your app work locally when testing with trivial data only to find out things don't sort properly for real users with real data.

<form>
  <input name="name" />
  <input name="surname" />

  <button type="submit">
    Submit the form
  </button>
</form>

Unfortunately, it's not always possible to render the submit button inside the form element. This is especially true if you don't have complete control over the DOM structure, like when using a component library. So you may end up with something like:

<form>
  <input name="name" />
  <input name="surname" />
</form>

...

<button type="submit">
  Submit the form
</button>

And then quickly see that neither clicking the submit button nor pressing the enter key submit the form.

form attribute

No worries! While submit buttons automatically associate with an ancestor form, it's possible to explicitly link a submit button with another form using the form attribute. There are just two requirements:

1. a unique id must be assigned to the form element

2. a form attribute must be added to the button with the value of the form's id.

<form id="nameForm">
  <input name="name" />
  <input name="surname" />
</form>

...

<button type="submit" form="nameForm">
  Submit the form
</button>

But wait!

The form will now submit when pressing the submit button, but pressing the enter key still won't work. This is because the browser still requires a submit button or input to be rendered somewhere inside the form for it to automatically handle form submission when the user presses the enter key. The easiest way to fix this is to render another submit button inside the form and then hide it visually with CSS.

<form id="nameForm">
  <input name="name" />
  <input name="surname" />
  <button type="submit" style="display: none;" />
</form>

...

<button type="submit" form="nameForm">
  Submit the form
</button>

Now the form is accessible and you should be able to render that real submit button wherever you need to.

If you stumbled upon some code like this, how would you know what color it would render as?

<div class="Component is-blue is-red">
  ...
</div>

You would have to render it or go to the source to determine for yourself to determine that it would be blue.

.Component.is-red {
  background: red;
}

.Component.is-blue {
  background: blue;
}

Specificity of modifier classes is not typically something that is considered when maintaining a design system and many times the final CSS is generated automatically which means that a minor rearranging of code could cause the final styles to reverse order and you might wake up having the component render as red instead of blue.

While this problem may seem contrived, this is a problem that occurs due to tech debt in real-world applications. As business requirements change, styling requirements can change, and it's very easy for multiple modifier classes of the same "type" to be mistakenly left in or conditionally added. Over time this can make code harder to read as it's non-deterministic; without a deep understanding of the CSS, an engineer can't determine what color the component would be without actually rendering it.

Attribute selectors to the rescue

Using attributes instead of classes to manage modifiers helps eliminate this problem and makes the code easier to understand. We can change the styles like so:

.Component[data-color="red"] {
  background: red;
}

.Component[data-color="blue"] {
  background: blue;
}

This then means the HTML we stumble upon would look like so:

<div class="Component" data-color="blue">
  ...
</div>

While it's still technically possible to have multiple data-color attributes on a single element, it's not considered valid according to the HTML5 standard and many linting tools can be configured to catch this type of error.

Benefits of this approach include:

1. Only a single modifier of each type can be declared

2. Promotes better accessibility as non-data attributes like title and aria-* attributes can be used

Performance considerations

According to performance benchmarks, class selectors are more performant than attribute selectors, but not by much. I would argue that for the average web application on modern browsers, any performance issues would go unnoticed and be far outweighed by the benefits of having an easier-to-read and easier-to-maintain codebase.

Need to build a UI? There's a package for that.

Need to format time? There's a package for that.

Need to add authentication? There's a package for that.

Nowadays there's open-sourced code that does practically everything. Just npm install it and you're on your way. Simple enough, right?

But what happens when that package you installed stops being maintained or you find out has a security vulnerability? What do you do when a newer, faster, and smaller package is released?

It's easy to allow 3rd party code to weave and integrate itself into your app, and it's only until you need to replace or remove it that you realize it's become more of a weed than a benefit.

Refactoring and changing libraries is eventually inevitable in practically any long-term project. So what can you do to make the migration process easier?

Reducing Dependency

To reduce dependency on a 3rd party library, you can create a single entry point where the 3rd party library is accessed. Then, throughout the app, you can access the local entry point instead of accessing the package directly. The day you decide to migrate, all you have to do is migrate the entry point instead of every instance the package was used.

Wrapping 3rd party libraries in this manner also makes it easier for you to add or modify functionality if something needs to be adjusted.

If the newer library has a different API, or if you just aren't a fan of the API, to begin with, this allows you to create your own custom API while reaping all the rewards of using an existing library.

An Example

Let's say there's a package we want to add called text-upper that capitalizes text.

Instead of accessing the package directly, first, we create an entry point in say utils/caseChanger. Usually, it's better to name it something generic or descriptive instead of just naming the entry point the same as the package.

Inside the entry point can be something as simple as:

import TextUpper from 'text-upper'

export default TextUpper

Then anytime we need to upper case text we just access the library through our entry point like so:

import caseChanger from './utils/caseChanger'

upperCase.makeUpperCase('hello world')

Later on, we find an even better package called textMcChanger that not only makes text uppercase but also makes text lowercase too. We definitely want that.

So now all we have to do is modify our entry point to use this new package. And even though the new package has a slightly different API for capitalizing text, we only have to modify our entry point to ensure everywhere we're already capitalizing text doesn't also need to be refactored.

Our migration in the utils/caseChanger might end up looking something like this:

import betterPackage from 'textMcChanger'

// Modify API for backwards compatibility
betterPackage.makeUpperCase = text => betterPackage.upper(text, true)

// Modify API for consistency with old API
betterPackage.makeLowerCase = text => betterPackage.lower(text, true)

export default betterPackage

Easy enough, right? All we had to do was change this one file and our app instantly reaps the benefits of the new package without all the extra refactoring.

Conclusion

It won't make sense to wrap every package like this. It would be silly to try to add a wrapper for React as your UI library and then later try to transform Vue to work like React. But I guess you could!

For most other things though, it's a good practice to follow, and you'll thank yourself later once you find the perfect replacement and you don't have to dread the migration.