---
meta:
title: Changelog
description: Changes to each version of the project are documented here.
---
# Changelog
Shoelace follows [Semantic Versioning](https://semver.org/). Breaking changes in components with the Stable badge will not be accepted until the next major version. As such, all contributions must consider the project's roadmap and take this into consideration. Features that are deemed no longer necessary will be deprecated but not removed.
Components with the Experimental badge should not be used in production. They are made available as release candidates for development and testing purposes. As such, changes to experimental components will not be subject to semantic versioning.
New versions of Shoelace are released as-needed and generally occur when a critical mass of changes have accumulated. At any time, you can see what's coming in the next release by visiting [next.shoelace.style](https://next.shoelace.style).
## Next
- Added the Simplified Chinese translation [#1604]
- Fixed a bug [in the localize dependency](https://github.com/shoelace-style/localize/issues/20) that caused underscores in language codes to throw a `RangeError`
- Fixed a bug in the focus trapping utility used by modals that caused unexpected focus behavior. [#1583]
- Fixed a bug in `` that prevented exported tooltip parts from being styled [#1586]
- Fixed a bug in `` that caused it not to fire the `sl-select` event if you clicked an element inside of a `` [#1599]
- Improved submenu selection by implementing the [safe triangle](https://www.smashingmagazine.com/2023/08/better-context-menus-safe-triangles/) method [#1550]
- Updated `@shoelace-style/localize` to 3.1.0
- Updated `@lib-labs/react` to stable `@lit/react`
- Updated Bootstrap Icons to 1.11.1
- Updated Lit to 3.0.0
- Updated TypeScript to 5.2.2
- Updated all other dependencies to latest versions
## 2.9.0
- Added the `modal` property to `` and `` to support third-party modals [#1571]
- Fixed a bug in the autoloader causing it to register non-Shoelace elements [#1563]
- Fixed a bug in `` that resulted in improper spacing between the label and the required asterisk [#1540]
- Fixed a bug in `` that caused icons to not load when the default library used a sprite sheet [#1572]
- Removed error when a missing popup anchor is provided [#1548]
- Updated `@ctrl/tinycolor` to 4.0.1 [#1542]
- Updated Bootstrap Icons to 1.11.0
## 2.8.0
- Added `--isolatedModules` and `--verbatimModuleSyntax` to `tsconfig.json`. For anyone directly importing event types, they no longer provide a default export due to these options being enabled. For people using the `events/event.js` file directly, there is no change.
- Added support for submenus in `` [#1410]
- Added the `--submenu-offset` custom property to `` [#1410]
- Fixed an issue with focus trapping elements like `` when wrapped by other elements not checking the assigned elements of ``s. [#1537]
- Fixed type issues with the `ref` attribute in React Wrappers. [#1526]
- Fixed a regression that caused `` to render incorrectly with gaps [#1523]
- Improved expand/collapse behavior of `` to work more like users expect [#1521]
- Improved `` so labels truncate properly instead of getting chopped and overflowing
- Removed the extra `React.Component` around `@lit-labs/react` wrapper. [#1531]
- Updated `@lit-labs/react` to v2.0.1. [#1531]
## 2.7.0
- Added the experimental `` component [#1473]
- Fixed a bug in `` where pressing [[Up]] or [[Down]] when focused on the trigger wouldn't focus the first/last menu items [#1472]
- Fixed a bug that caused key presses in text fields to be hijacked when used inside `` [#1492]
- Fixed an upstream bug that caused React CodePen examples to stop working
- Improved the behavior of the clear button in `` to prevent the component's width from shifting when toggled [#1496]
- Improved `` to prevent user selection so the tooltip doesn't get highlighted when dragging selections
- Moved tag type definitions out of component files and into definition files
- Removed `sideEffects` key from `package.json`. Update React docs to use cherry-picking. [#1485]
- Updated Bootstrap Icons to 1.10.5
## 2.6.0
- Added JSDoc comments to React Wrappers for better documentation when hovering a component. [#1450]
- Added `displayName` to React Wrappers for better debugging. [#1450]
- Added non-auto-registering routes for Components to fix a number of issues around auto-registration. [#1450]
- Added a console warning if you attempt to register the same Shoelace component twice. [#1450]
- Added tests for `` [#1416]
- Added support for pressing [[Space]] to select/toggle selected `` elements [#1429]
- Added support for virtual elements in `` [#1449]
- Added the `spinner` part to `` [#1460]
- Added a `shoelace.js` and `shoelace-autoloader.js` to exportmaps. [#1450]
- Added types to events emitted by React wrapped components [#1419]
- Fixed React component treeshaking by introducing `sideEffects` key in `package.json`. [#1450]
- Fixed a bug in `` where it was auto-defining ``. [#1450]
- Fixed a bug in focus trapping of modal elements like ``. We now manually handle focus ordering as well as added `offsetParent()` check for tabbable boundaries in Safari. Test cases added for `` inside a shadowRoot [#1403]
- Fixed a bug in `valueAsDate` on `` where it would always set `type="date"` for the underlying `` element. It now falls back to the native browser implementation for the in-memory input. This may cause unexpected behavior if you're using `valueAsDate` on any input elements that aren't `type="date"`. [#1399]
- Fixed a bug in `` where the `background` attribute was never passed to the QR code [#1416]
- Fixed a bug in `` where aria attributes were incorrectly applied to the default `` causing Lighthouse errors [#1417]
- Fixed a bug in `` that caused navigation to work incorrectly in some case [#1420]
- Fixed a number of slots that incorrectly had aria- and/or role attributes directly on them [#1422]
- Fixed a bug in `` that caused focus to be stolen when removing focused tree items [#1430]
- Fixed a bug in `` and `` that caused nested modals to respond too eagerly to the [[Esc]] key [#1457]
- Improved `` to use `` internally for better semantics and to enable search to find in supportive browsers when collapsed [#1470]
- Updated ESLint and related plugins to the latest versions
- Changed the default entrypoint for jsDelivr to point to the autoloader. [#1450]
## 2.5.2
- Fixed broken source buttons in the docs [#1401]
## 2.5.1
- Fixed missing extensions from imports that broke with TypeScript 5 [#1391]
- Fixed a regression that caused slotted styles to not work in `` [#1387]
- Reimplemented the theme switcher so it supports light, dark, and system (auto) in the docs [#1395]
## 2.5.0
This release [unbundles Lit](https://github.com/shoelace-style/shoelace/issues/559) (and other dependencies) from Shoelace. There are now two distributions for the project:
1. `cdn/` – a bundled, CDN-ready distribution
2. `dist/` – an unbundled, npm-ready distribution
:::warning
If you're a CDN user, you must update your path to point to `cdn/` instead of `dist/`. You can copy and paste the latest paths from the [installation page](/getting-started/installation).
:::
- Added a `cdn/` distribution for bundled dependencies (imports for npm users remain the same) [#1369]
- Added the `checkbox` part and related exported parts to `` so you can target it with CSS [#1318]
- Added the `submenu-icon` part to `` (submenus have not been implemented yet, but this part is required to allow customizations)
- Added the ability to use Sprite Sheets when using `` via a custom resolver.
- Added tests for `` [#1343]
- Fixed a bug where changing the size of `` wouldn't update the size of child elements
- Fixed a bug in `` and `` where the `size` attribute wasn't being reflected [#1318]
- Fixed a bug in `` where `` would not get checked if `` was defined first. [#1364]
- Fixed a bug in `` that caused date pickers to look filled in even when empty in Safari [#1341]
- Fixed a bug in `` that sometimes caused dual scrollbars in containers that overflowed [#1380]
- Fixed a bug in `` not loading the English language pack automatically. [#1384]
- Improved `` so it can accept children of variable heights [#1317]
- Improved the docs to more clearly explain sizing radios and radio buttons
- Improved the performance of `` by partially rendering unseen icons [#1310]
- Improved the Portuguese translation [#1336]
- Improved the German translation [#1339]
- Improved the autoloader so it watches `` instead of `` since the latter gets replaced by some frameworks [#1338]
- Improved the Rails documentation [#1258]
- Replaced Docsify with Eleventy to generate a static HTML version of the docs
- Updated esbuild to 0.18.2
- Updated Lit to 2.7.5
- Updated TypeScript to 5.1.3
## 2.4.0
- Added the `discover()` function to the experimental autoloader's exports [#1236]
- Added the `size` attribute to `` so labels and controls will be sized consistently [#1301]
- Added tests for `` [#1246]
- Added tests for `` [#1274]
- Fixed a bug in `` that prevented long labels from wrapping [#1243]
- Fixed a bug in `` that caused labels to be misaligned when text wraps [#1244]
- Fixed an incorrect CSS property value in `` [#1272]
- Fixed a bug in `` that caused the initials to show up behind images with transparency [#1260]
- Fixed a bug in `` that prevented the divider from being focusable in some browsers [#1288]
- Fixed a bug that caused `` to affect scrolling when initializing [#1292]
- Fixed a bug in `` that allowed the hover state to show when focused [#1282]
- Fixed a bug in `` that prevented interactive elements from receiving clicks [#1262]
- Fixed a bug in `` that caused `valueAsDate` and `valueAsNumber` to not be set synchronously in some cases [#1302]
- Improved the behavior of `` when used inside a flex container [#1235]
- Improved the behavior of `` to support buttons and other interactive elements [#1234]
- Improved the performance of `` to prevent an apparent memory leak in some browsers [#1284]
- Improved the accessibility of ``, ``, and `` by ensuring slots don't have roles [#1287]
## 2.3.0
- Added an experimental autoloader
- Added the `subpath` argument to `getBasePath()` to make it easier to generate full paths to any file
- Added `custom-elements.json` to package exports
- Added `tag__base`, `tag__content`, `tag__remove-button`, `tag__remove-button__base` parts to ``
- Fixed a bug in `` that allowed the `sl-change` event to be emitted when disabled [#1220]
- Fixed a regression in `` that caused `min` and `max` to stop working when `type="date"` [#1224]
- Improved accessibility of `` [#1218]
- Improved `` so it converts non-string values to strings for convenience [#1226]
- Updated the docs to dogfood the autoloader
## 2.2.0
- Added TypeScript types to all custom events [#1183]
- Added the `svg` part to ``
- Added the `getForm()` method to all form controls [#1180]
- Added the experimental carousel component [#851]
- Fixed a bug in `` that caused the display label to render incorrectly in Chrome after form validation [#1197]
- Fixed a bug in `` that prevented users from applying their own value for `autocapitalize`, `autocomplete`, and `autocorrect` when using `type="password` [#1205]
- Fixed a bug in `` that prevented scroll controls from showing when dynamically adding tabs [#1208]
- Fixed a bug in `` that caused the calendar icon to be clipped in Firefox [#1213]
- Fixed a bug in `` that caused `sl-tab-show` to be emitted when activating the close button
- Fixed a bug in `` that caused `--track-color` to be invisible with certain colors
- Fixed a bug in `` that caused the focus color to show when selecting menu items with a mouse or touch device
- Fixed a bug in `` that caused `sl-change` and `sl-input` to be emitted too early [#1201]
- Fixed a positioning edge case that caused `` to positioned nested popups incorrectly [#1135]
- Fixed a bug in `` that caused the tree item to collapse when clicking a child item, dragging the mouse, and releasing it on the parent node [#1082]
- Updated `@shoelace-style/localize` to 3.1.0
- Updated `@floating-ui/dom` to 1.2.1
When using `` the default value for `autocapitalize`, `autocomplete`, and `autocorrect` may be affected due to the bug fixed in [#1205]restore the previous behavior.
## 2.1.0
- Added the `sl-focus` and `sl-blur` events to ``
- Added the `focus()` and `blur()` methods to ``
- Added the `sl-invalid` event to all form controls to enable custom validation logic [#1167]
- Added `validity` and `validationMessage` properties to all form controls [#1167]
- Added the `rel` attribute to `` to allow users to create button links that point to specific targets [#1200]
- Fixed a bug in `` where the play and pause buttons were transposed [#1147]
- Fixed a bug that prevented `web-types.json` from being generated [#1154]
- Fixed a bug in `` that prevented `sl-change` and `sl-input` from emitting when using the eye dropper [#1157]
- Fixed a bug in `` that prevented keyboard users from selecting menu items when using the keyboard [#1165]
- Fixed a bug in the template for `` that caused the `form-control-help-text` part to not be in the same location as other form controls [#1178]
- Fixed a bug in `` and `` that caused the browser to scroll incorrectly when focusing on a control in a container with overflow [#1169]
- Fixed a bug in `` that caused the `click` event to be emitted when the item was disabled [#1113]
- Fixed a bug in form controls that erroneously prevented validation states from being set when `novalidate` was used on the containing form [#1164]
- Fixed a bug in `` that caused the required asterisk to appear before the label in Chrome
- Fixed a bug that prevented large form control labels from having the correct font size [#1195]
- Improved the behavior of `` in Safari so keyboard interaction works the same as in other browsers [#1177]
- Improved the [icons](/components/icon) page so it's not as sluggish in Safari [#1122]
- Improved the accessibility of `` when used in forced-colors / Windows High Contrast mode [#1114]
- Improved user interaction heuristics for all form controls [#1175]
## 2.0.0
This is the first stable release of Shoelace 2, meaning breaking changes to the API will no longer be accepted for this version. Development of Shoelace 2.0 started in January 2020. The first beta was released on [July 15, 2020](https://github.com/shoelace-style/shoelace/releases/tag/v2.0.0-beta.1). Since then, Shoelace has grown quite a bit! Here are some stats from the project as of January 24, 2023:
- 55 components have been built
- [Over 2,500 commits](https://github.com/shoelace-style/shoelace/commits/next) have been made to the project
- [88 beta versions](https://github.com/shoelace-style/shoelace/tags) have been released
- [85 people](https://github.com/shoelace-style/shoelace/graphs/contributors) have contributed to the project
- [669 issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aclosed) have been filed on GitHub
- [274 pull requests](https://github.com/shoelace-style/shoelace/pulls) have been opened
- [More than 150 discussions](https://github.com/shoelace-style/shoelace/discussions) have been started on GitHub
- [Over 500 people](https://discord.com/invite/mg8f26C) have joined the Shoelace community on Discord
- [Over 300 million CDN hits](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) per month
- [Over 13,000 npm downloads](https://www.npmjs.com/package/@shoelace-style/shoelace) per week
- [73rd most popular project](https://www.jsdelivr.com/statistics) on jsDelivr
- [#2
I'd like to extend a very special thank you to every single contributor who worked to make this possible. Everyone who's filed a bug, submitted a PR, requested a feature, started a discussion, helped with testing, and advocated for the project. You are just as responsible for Shoelace's success as I am. I'd also like to thank the folks at [Font Awesome](https://fontawesome.com/) for recognizing Shoelace's potential and [believing in me](https://blog.fontawesome.com/shoelace-joins-font-awesome/) to make it happen.
Thank you! And keep building _awesome_ stuff!
Without further ado, here are the notes for this release.
- Added support for the `inert` attribute on `` to allow hidden menu items to not accept focus [#1107]
- Added the `tag` part to ``
- Added `sl-hover` event to `` [#1125]
- Added the `@documentation` tag with a link to the docs for each component
- Added the `form` attribute to all form controls to allow placing them outside of a `