Changelog

Everything new in Open Components, from new guidelines to new components, and what each one means for you and your agents.

Components

The Combobox

Comboboxes let people type to narrow a long list, like countries, and pick from what's left. The Combobox page walks you through building one on the APG's editable combobox with list autocomplete, which never picks an option people didn't choose, with the Select's panel, options, tags and tokens, so one class restyles both.

New

  • The Combobox is an <input role="combobox"> with aria-autocomplete="list" and the Select's listbox panel, which filters on any part of a label, ignoring case and accents, and announces the count once typing pauses.
  • It picks one value or several, as tags, and shows an icon beside each option where you give one, the way the Select does.
  • It keeps text that isn't an option only with allowCustomValue, or adds it as a new option with creatable, and the page says what each one submits.
  • A hidden <select> submits, validates and resets with its form, for picked and typed values alike, and the panel fits the room the on-screen keyboard leaves.
  • It comes with its own contract, live examples and a tested reference implementation.

Improved

  • tokens/component-scope now says that parts a component shares with another component read that component's variables, so the Combobox reads the Select's for its panel, options and tags. Its ID is the same.
  • Contracts can list those variables under a new tokens.shared field, apart from their own variables.
  • The Select's panel, options, tags and styles are now in files of their own, which the Select page shows, so you can copy them for both components. The Select itself hasn't changed.
  • The Roadmap, the Field, the Input, the Select, the Checkbox, the Checkbox Group and the Popover now link to the Combobox.
Read the Combobox page
Components

The Tag Group

Tags rarely come alone: an issue has its labels, a post its topics and a search its filters. The Tag Group page walks you through laying them out as a named list of Tags, and through what happens when one is removed, so keyboard and screen reader users never lose their place.

New

  • A tag group is a <ul> named like "Labels", with an <li> and the shipped Tag per tag, so screen readers say what the tags are and how many there are.
  • Every link and remove button keeps its own stop in the tab order, with no arrow keys, and the page explains why we chose that over React Aria's grid.
  • Once a tag has gone, focus moves to the next remove button, then to an element you name, then to the previous one, and the group announces "Bug removed". With no tags left, it shows an empty state that focus can land on.
  • Rows sit far enough apart that a tag's hit area never covers the tag below it, on touch screens too.
  • It comes with five sizes, its own contract, live examples and a tested reference implementation.

Improved

  • The Tag's UX, DX and AX pages now link to the Tag Group where they said it would come next, and the Roadmap ticks it.
Read the Tag Group page
Components

The Tag

Tags label what something is about, like a post's topics or an issue's labels, and people can remove them or follow them to a page about them. The Tag page walks you through building one that takes its look from the Select's tags, with a remove button every screen reader and voice control user can name.

New

  • A plain tag is text, with no role and no place in the tab order. A link tag holds a real <a href>, or your router's link, and a removable one adds a native <button> named after it, like "Remove Bug".
  • It fires remove and keeps no state of its own, so the page that owns the tags removes them, moves focus and announces what went.
  • It draws the line between a tag, which says what something is about, and a badge, which marks a status or a count, and leaves selectable tags to toggle buttons and the Checkbox Group.
  • It comes with five sizes that match the Select's tags, its own contract, live examples and a tested reference implementation.

Improved

  • The Roadmap and the Select now link to the Tag.
Read the Tag page
Components

The Select

Selects let people pick one option, or several, out of a list that's too long to lay out on the page. The Select page walks you through building one you can restyle part by part, on the APG's select-only combobox, without giving up what a native <select> does for free.

New

  • The Select is a <button role="combobox"> with a listbox panel, so the Field names it with the same <label for> it gives an Input, and it follows the APG's keyboard model, typing to search included.
  • It picks one value or several, with removable tags you can reach by keyboard, shows an icon beside each option where you give one, and each of its parts restyles through tokens and slots.
  • A native <select> is always in the page, so it submits under its name, validates and resets with its form, and the nativeOnTouch prop shows it where the primary pointer is coarse, with no layout shift or hydration mismatch.
  • It comes with its own contract, live examples and a tested reference implementation.

Improved

  • The Roadmap, the Field, the Input, the Checkbox, the Checkbox Group, the Radio Group and the Popover now link to the Select.
Read the Select page
Components

The Field

A form control is only as good as the label, hint and error message around it, and those are elements of their own, linked by ID, which is where they come apart. The Field page walks you through putting them together, from a label that focuses its control when you click it, to an error that screen readers read with its control and a failed submit that takes people straight to it.

New

  • The Field renders the label, hint and error around any form control, and links them with its id, aria-describedby and aria-invalid, without changing the control.
  • It works with the Input, the Textarea, the Checkbox, the Switch, the Checkbox Group and the Radio Group, and puts the label where each one needs it.
  • Its IDs come from the id or name you pass, never from a generator, so the label works in the server's markup before any script runs.
  • Its checklist covers how forms use it too, like marking the optional fields in words, checking values when people leave a control and moving focus to the first error on a failed submit.
  • It comes with its own contract, live examples and a tested reference implementation.

Improved

  • The Input, the Textarea, the Checkbox, the Switch, the Checkbox Group and the Radio Group now link to the Field, which their pages promised.
Read the Field page
Components

Every component, a page per layer

The Button's page was the first to get a page per layer, and the other ten components now follow it, so you can read one layer of any component at a time. Each one is an Overview, with the playground where it has one, the facts at a glance, the reference implementation and the sources, and a page for each layer, all under the component's name in the sidebar.

Improved

  • The Card, Checkbox, Checkbox Group, Dialog, Input, Radio Group, Spinner, Switch, Textarea and Tooltip each have a page for their User Interface, User Experience, Developer Experience and Agentic Experience, with the layer's rules and, where it has any, the questions it answers.
  • Links between the components' pages now go straight to the section on its new page, and links from before the split, like one to the Input's sizes, still take you to the right section.
  • In the sidebar, a component's name now opens and closes the list of its pages, the Overview and its layers, rather than taking you to its Overview, so you choose the page you want.
  • Agents still read each component as one page, as before: /raw/docs/components/<component>.md, its contract and the MCP server serve it whole.
Components

The Popover

Popovers show more next to the button that opened them, like a set of filters or a hint with a link, without blocking the page. The Popover page walks you through building one on the popover attribute, from the Button with popovertarget that opens it, before any script loads, to the Escape that closes it without closing the Dialog behind it.

New

  • The Popover is a non-modal role="dialog", named by its title, which the browser puts in the top layer and closes on Escape and on a press outside.
  • Focus moves in when it opens and goes back to its trigger when it closes from inside, and close says why it closed, like escape or outside.
  • Escape closes only the layer on top, so a Tooltip inside a Popover, and a Popover inside a Dialog, each close on their own.
  • It opens beside its trigger, with the Tooltip's placement names, flips when there's no room and stays inside the screen, down to 320px wide and at 400% zoom.
  • It comes with its own contract, live examples and a tested reference implementation.

Improved

  • The Dialog, the Tooltip and the Button now link to the Popover, and the Button's Filters example sets aria-haspopup="dialog", while the Popover sets aria-expanded.
Read the Popover page
Components

The Button, a page per layer

The Button's page had grown to about 35,000 tokens, so finding your way back to one section meant a long scroll. It's now an Overview, with the playground, the facts at a glance, the reference implementation and the sources, and a page for each layer, all under Button in the sidebar.

Improved

  • The User Interface, User Experience, Developer Experience and Agentic Experience sections each have a page of their own, with the layer's rules and, where it has any, the questions it answers, and the Overview's introduction links each one from a card.
  • In the sidebar, Button links to its Overview, and the arrow beside it opens and closes the list of its pages, the Overview and its layers, which stays open while you read them.
  • Links to the Button's sections from before the split, like one to its loading state, still take you to the right section on its new page.
  • Agents still read the Button as one page, as before: /raw/docs/components/button.md, its contract and the MCP server serve it whole.
Read the Button page
Components

The Radio Group

Radio groups let people pick one answer out of a few, and they're easy to get subtly wrong, like a question screen readers never read, or a red border that only sighted people notice. The Radio Group page walks you through building one the right way, from the legend that asks the question to the error message that says what to do.

New

  • The Radio Group is built on native radios in a <fieldset>, named by its <legend>, so the browser handles the keyboard: one Tab stop per group, and arrow keys that move, check and wrap round.
  • Its radios have the Input's heights, so a radio lines up with an input beside it, and their labels are part of what people press, so every radio is at least 24 × 24px.
  • Its radios stack, one per line, apart from two short options, like "Yes" and "No", which can sit side by side with orientation="horizontal".
  • Its invalid look comes from aria-invalid on the group, which takes the radiogroup role so screen readers can announce it, and its error message sits above the radios, where people read it before they choose again.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Radio Group page
Components

The Checkbox Group

Checkbox groups let people pick any number of options from a short list, and most of what goes wrong with them is what holds the boxes together. The Checkbox Group page walks you through building one the right way, from a <fieldset> that its question names to a select-all box that turns mixed when some options are checked, and checks them all with one press.

New

  • The Checkbox Group is a <fieldset> of Checkboxes, named by its <legend> and described by its hint and error message, so screen readers announce the question along with its options.
  • Its value is a list, sent with one shared name, and its options run in a column by default, so they're quick to scan and fit on any screen.
  • Its select-all box is worked out from the options every time they change, and checks every option, or clears them all, as the APG asks.
  • Its checklist covers how forms use it too, like saying "Pick at least one" when people have to, and checking it in your own code, since HTML's required doesn't fit a group.
  • It comes with its own contract, live examples and a tested reference implementation, built out of the Checkbox's.
Read the Checkbox Group page
Components

The Textarea

Textareas are where people write more than a line, and they're often built as an input that's a few lines taller. The Textarea page walks you through building one the right way, from a height that fits what people are about to write to a limit that never cuts off what they paste.

New

  • The Textarea has the Input's sizes, padding and states, so the two line up in a form, and a textarea of one row is exactly as tall as an input.
  • Its height starts at rows and never goes below it. People resize it on the block axis, or it grows with its text, up to maxRows.
  • Its count lets people type and paste past a limit, says by how much, and is announced to screen readers once they pause, rather than on every keystroke.
  • Enter always starts a new line, and its checklist covers how forms use it too, like stating a limit in the hint and never making Enter send a message.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Textarea page
Components

The Checkbox

Checkboxes let people say yes or no to one thing, and the browser has had one built in for as long as there have been forms. Its box is hard to style, though, so many teams rebuild it, and that's where it goes wrong. The Checkbox page walks you through building one the right way, from a label that toggles the box to a "Select all" that screen readers announce as mixed.

New

  • The Checkbox wraps its own label around the box, so the text names it and a press on the text toggles it, and the box sits in a hit area of at least 24 × 24px at every size.
  • It takes the Button's and the Input's sizes, and shows checked, indeterminate, disabled, read-only and invalid with a look of their own, each read from the <input>, so what people see always matches what screen readers announce.
  • Its checklist covers how forms use it too, like keeping labels positive, saying why a required box needs checking, and remembering that an unchecked box sends nothing.
  • It comes with its own contract, live examples and a tested reference implementation, ready for the Checkbox Group that's next on our Roadmap.
Read the Checkbox page
Components

The Tooltip

Tooltips are small and everywhere, which is why they so often only work for a mouse. The Tooltip page walks you through building one that opens for the keyboard too, stays open while people read it and closes with Escape. The other overlays on our Roadmap, like the Popover and the Dialog, will follow its rules for the top layer and Escape.

New

  • A tooltip either shows an icon-only button's own label, hidden from screen readers so they don't hear it twice, or describes its trigger with aria-describedby.
  • It opens in the top layer and finds its place with CSS anchor positioning, flipping when there's no room, with a short script for browsers that don't have it yet. An arrow, on by default, points at its trigger from whichever side it opens on.
  • Its checklist covers WCAG's rules for content on hover or focus, and the rules for the screens that use it, like never putting anything people need only in a tooltip, since a tap never opens one.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Tooltip page
Components

The Card

Cards group what people need to know about one thing, like a project or a product, and they're easy to build so that only a mouse can use them. The Card page walks you through building one the right way, from a heading that people can find it by to a link that covers the whole card without swallowing its text.

New

  • A card that takes people somewhere has one link, in its heading, stretched over the card, so the link is named by the heading alone, and its actions, like Save, stay Buttons of their own.
  • It has a header, a body, actions and a footer, with no borders between them, so a card reads as one block, and a separator adds a line only where a page needs one.
  • Its heading comes first in the DOM, at the level you give it, while its image and eyebrow are shown above it, so people who move from heading to heading land at the start of the card.
  • Its checklist covers how pages use it too, like putting cards in a list, describing their images and writing headings that say where the link goes.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Card page
Components

The Dialog

Dialogs ask for someone's full attention, and most of what they do happens out of sight, in focus and in the accessibility tree, which is why they're so often broken for keyboard and screen reader users. The Dialog page walks you through building one the right way, from moving focus in when it opens to giving it back to the button that opened it when it closes.

New

  • The Dialog is a native <dialog>, opened with showModal(), so the page behind it is inert and Tab never wanders off into it.
  • It's named by its title and described by its description, and alert dialogs, for confirmations, have no close button and ignore a stray click outside.
  • It asks, rather than closing itself. Escape, the close button, the backdrop and a <form method="dialog"> each fire close with the reason, so you can keep it open when people would lose what they've typed, and when a browser closes it anyway, close fires with closed, so your code can follow.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Dialog page
Components

The Switch

Switches turn a setting on or off, and they're so familiar that it's easy to forget what makes them work. The Switch page walks you through building one the right way, from a label that names the setting and never changes to a change that applies as soon as people flip it.

New

  • The Switch is a native checkbox with the switch role, so Space, its label and its form work before any script loads, and screen readers announce it as on or off.
  • On and off differ by more than colour, its track and thumb have 3:1 against what's next to them, and it takes the Input's sizes and states, read-only included, with a hit area of at least 24 × 24px.
  • Its checklist covers how screens use it too, like applying a setting right away rather than waiting for a Save button, saying when the change is saved and moving the switch back if it fails.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Switch page
Getting Started

The agent plugin

Our MCP server gives your agents the standard as tools, but they still need to know when to reach for it, and its prompts only run when you start them. Our agent plugin brings the two together: skills that your agent picks up on its own whenever it builds or reviews a component, and the MCP server they read the standard from.

New

  • Install it in VS Code, GitHub Copilot, Cursor, Codex, Claude Code and any other client that supports Agent Plugins, the open format for packaging skills and MCP servers.
  • Its skills build a component in your framework, review one or how a screen uses it, reporting every rule by its ID, and move your CSS variables to token paths.
  • Where your client doesn't connect MCP servers, the skills read the same contracts and pages from this site.
Install the agent plugin
Components

The Input

Inputs are where people tell you things, and they look so simple that they're often built in a hurry. The Input page walks you through building one the right way, from a label that doesn't disappear as people type to an error message that says how to fix what's wrong.

New

  • The Input has the Button's sizes, so the two line up in a row, and slots for icons, prefixes and suffixes, and for buttons like Show password.
  • Its border has 3:1 against the page, so people can always see where to type, and its invalid look comes from aria-invalid, so it always matches what screen readers announce.
  • Its checklist covers how forms use it too, like giving every input a label and an autocomplete value, checking values when people leave an input rather than while they type, and never blocking paste.
  • It comes with its own contract, live examples and a tested reference implementation.
Read the Input page
Components

The Spinner

A spinner is one of the simplest components there is, and still easy to get wrong. The Spinner page walks you through showing that something is busy, and making sure everyone hears what's loading and how it went, since the spinner itself stays silent.

New

  • The Spinner takes its size and colour from the text around it, stays hidden from screen readers and stops turning when someone prefers reduced motion.
  • Its checklist covers how screens use it too, like showing one spinner per wait, saying what's loading in a status message and leaving focus where it was.
  • It walks you through every state of the wait it shows, from busy to done or failed, and what to say when it's taking longer than expected.
  • It comes with its own contract, live examples, a tested reference implementation and a browser test that checks what screen readers and agents find while the page waits.

Improved

  • The Button shows the Spinner while it's loading, so changing your spinner once changes it everywhere.
Read the Spinner page
Getting Started

The MCP server

Agents do their best work with just what a task needs, but a component page holds far more than that: the Button's alone is about 35,000 tokens. Our MCP server, at https://mcp.opencomponents.dev/mcp, gives your agents the standard as tools instead, so they read a component's contract first, then only the sections and rules their task needs.

New

  • Connect it to Claude, Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Grok, Hermes Agent or any other client that supports remote MCP servers. It's free, with no sign-in.
  • Its tools read a contract, list the rules that apply to your task, read a page a section at a time in your framework, search the whole standard and return the reference implementation.
  • Its prompts build a component, review one or how a screen uses it, reporting every rule by its ID, and move your CSS variables to token paths.
Connect the MCP server
Contracts

A schema for contracts

Contracts give agents every requirement for a component in one YAML file, so a field that's missing or misspelled leads them astray without a word. They now all follow one published JSON Schema, which catches those mistakes before anyone relies on the contract.

New

  • Every contract names the schema on its first line, so editors that use the YAML language server check it as you type.
  • The schema covers components and conventions alike, so you can validate the contracts you write for your own components too.
  • We validate every contract on this site against it on every change, so the ones we publish always pass.
Read about contracts
Components

Where each rule comes from

Most of our rules rest on WCAG, but some go further, and some are our own. Every checklist now has a Basis column that tells them apart, so you know when a rule is something WCAG asks for at level AA, and when it's a call we've made.

New

  • Every rule in the Button and Design Tokens checklists names its basis: the WCAG 2.2 success criteria behind it and their level, HTML, WAI-ARIA or the APG, or Open Components for our own rules.
  • Contracts include each rule's basis too, so your agents can tell the rules apart as well.

Improved

  • button/focus-visible asks for an outline at least 2px thick, rather than exactly 2px, and the Button page says what we recommend for the details you can change and still meet the standard, like the ring's offset or the opacity of the state layers.

Fixed

  • button/keep-focus now covers a button that can be disabled while it has focus, like Next on the last page, which stays focusable. Before, it said a focused button is never natively disabled, which no Button could promise on its own.
  • button/focus-not-obscured now cites WCAG 2.4.12 as well as 2.4.11, since it asks that a focused button isn't covered at all.
Read the Button's checklist
Components

The Button

Buttons are the most common interactive component in any interface, and also the one we most often get wrong. Our first component page walks you through building one the right way, and every component page after it will follow the same structure.

New

  • It covers how a button looks, how it behaves for every person and every input, how developers work with it and how agents can read and verify it.
  • Every example is live, and its code comes in React, Vue, Svelte, Angular, Solid, Astro and Vanilla.
  • A checklist, a contract for agents and a tested reference implementation help you hold your own buttons to the standard.
Read the Button page
Foundations

Design Tokens and token paths

Every component reads its colours, sizes and spacing from CSS variables, and their names are all that people, tools and agents have to go on. Our first Foundations page shows you how to name them, so that everyone reads them the same way.

New

  • Token paths, like --color--primary, give every token a name that can only be read one way.
  • Every component reads the same theme tokens, so a new brand or a dark mode never means editing every component.
  • A Stylelint rule and a checklist let you and your agents check your tokens automatically.
Read the Design Tokens page
Copyright © 2026