NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #3984 most downloaded on npm
A simple low level base class for creating fast, lightweight web components
Latest stable
2.1.2
Last release 11 months ago
23 Dec 2025
Ships unpredictably
gaps range from 2 weeks to 1.2 years
Nearly every release is documented
notes for 31 of 31 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
42 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
### Patch Changes - #4340 `18305b43` - Update dependency version range on graduated package to ^1.0.0 so this package can receive updates.
#5044 0d0170e87b06edd8295a31893c820162d0f16a23 Thanks @ava-cassiopeia! - Make ClassInfo mutable
#4999 6c174c8d0ed0230ba765d699591d933d7ab5d4bb - Fix a bug in change detection with decorated standard private accessors.
Updated dependencies [5057feeac96cc6eb3c5e5c1cb6c42bc01ac6aab1, ad23f26ae908a160d30ed2a939b322fe9cc2ee83]:
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Updated dependencies \[`3ac01aee`]:
### Minor Changes - #4901 `c9160405` Thanks @maxpatiiuk! - Dev mode warnings are now emitted on the next microtask after package import, allowing for
#4901 c9160405 Thanks @maxpatiiuk! - Dev mode warnings are now emitted on the next microtask after package import, allowing for a wider opportunity to suppress the warnings by consumers.
#4934 4824c4ce - Adds property option for useDefault. When set, the initial default value is not considered a change and does not reflect when reflect is set. In addition, when the attribute is removed, the default value is restored.
5a60fbc6 Thanks @rivajunior! - export Options interface### Patch Changes - #4782 `99703a03` - Revert the Terser plugin for Rollup to rollup-plugin-terser from @rollup/plugin-terser due to a bug that preven
57b00630 - Add "browser" export condition entrypoints to any package.json files with "node"
export conditions. This fixes Node test runners emulating browser environments that were incorrectly loading the
"node" entrypoints instead of the browser code.e901c582]:
3cf98cd8 Thanks @Westbrook! - Fixes #3904 "Clipping parents include ancestors of position: fixed element"Updated dependencies \[`feccc1ba`]:
#4591 045b6f15 Thanks @a11delavar! - Do not initialize observers to prevent failing in SSR environment.
Updated dependencies [feccc1ba]:
dc1d323f - Revert custom children type added in #4142 and instead use our copy of PropsWithoutRef type so that preact/compat typing will work.
Preact users facing type errors using wrapped components should configure "paths" in their tsconfig.json so that react types will instead resolve to preact/compat as described in Preact's TypeScript documentation.
Going with preact/compat also solves compatibility issues arising from TypeScript >= 5.1 changing JSX tag type check.#3909 feded34b Thanks @chrispaterson! - Refactored and refurbished ScrollerController attach/detach code in effort to reduce potential memory leaks due to held instance references.
#3892 f5b2013d - Changed accessor and iterator code to support ES5 compilation.
#3929 c3672fca - Added new support utilities for dealing with ResizeObserver loop limit exceeded errors.
### Patch Changes - #4387 `bf551b5b` - Ensure renderRoot exists before first update (#4268) - #4282 `c7922a0c` Thanks @MaxArt2501! - Fix a bug where a
#4387 bf551b5b - Ensure renderRoot exists before first update (#4268)
#4282 c7922a0c Thanks @MaxArt2501! - Fix a bug where accessing a @query decorated field with the cache flag set before the first update would result in null being cached permanently. null will no longer be cached before the first update and in DEV_MODE now raises a warning.
#4388 839ca0f8 - Fixes bug where adding or removing controllers during a reactive controller lifecycle would affect the execution of other controllers (#4266). Controllers can now be added/removed during lifecycle without affecting others.
### Patch Changes - #4284 `89a5b088` - Allow null to be in the type of @query() decorated fields - #4306 `c28ebba1` - Update dependency version to ref
### Major Changes - #3850 `7e8491d4` - Remove transform for deprecated usage of queryAssignedNodes. - #4141 `6b515e43` - Update TypeScript to ~5.2.0,
#4146 0f6878dc - Generated accessor for reactive properties now wrap user accessors and automatically call this.requestUpdate() in the setter. As in previous versions, users can still specify noAccessor: true, in which case they should call this.requestUpdate() themselves in the setter if they want to trigger a reactive update.
#4254 1040f758 - Change the type of ReactiveElement.renderRoot and return type of ReactiveElement.createRenderRoot() to be HTMLElement | DocumentFragment to match each other and lit-html's render() method.
#3850 7e8491d4 - Delete deprecated queryAssignedNodes behavior and arguments.
Migrate deprecated usage with a selector argument to use
@queryAssignedElements. E.g.: @queryAssignedNodes('list', true, '.item') to
@queryAssignedElements({slot: '', flatten: false, selector: '.item'}).
#4027 c28cb6ed - - [BREAKING] Removed deprecated call signature for createComponent() taking multiple arguments. A single option object must be passed in instead.
Example:
- createComponent(React, 'my-element', MyElement, {onfoo: 'foo'})
+ createComponent({
+ react: React,
+ tagName: 'my-element',
+ elementClass: MyElement,
+ events: {onfoo: 'foo'},
+ })
forwardRef rather than creating a class component. This removes an extra React component of the same name showing up in the component tree.LitElement, ReactiveElement, and lit-html). See the Migration Guide for more details.### Major Changes - #4141 `6b515e43` - Update TypeScript to ~5.2.0
#4146 0f6878dc - Generated accessor for reactive properties now wrap user accessors and automatically call this.requestUpdate() in the setter. As in previous versions, users can still specify noAccessor: true, in which case they should call this.requestUpdate() themselves in the setter if they want to trigger a reactive update.
#4183 6470807f - Make the decorators work with the accessor keyword when experimentalDecorators is true.
### Major Changes - #3850 `7e8491d4` - Remove transform for deprecated usage of queryAssignedNodes. - #3814 `23326c6b` - Update to TypeScript 5.0, whi
#3850 7e8491d4 - Delete deprecated queryAssignedNodes behavior and arguments.
Migrate deprecated usage with a selector argument to use
@queryAssignedElements. E.g.: @queryAssignedNodes('list', true, '.item') to
@queryAssignedElements({slot: '', flatten: false, selector: '.item'}).
### Patch Changes - #4031 `8057c78d` - Rename ReactiveElement.\_initialize to \_\_initialize, make it private, and remove the @internal annotation. Th
### Patch Changes - #3917 `f6387e35` - Allow decorators to accept ReactiveElement class from a different source.
### Patch Changes - #3561 `e5c254e9` - Fix built-in shimming of HTMLElement for Node build of reactive-element to respect existing HTMLElement in glob
### Minor Changes - #4893 `6c051d517bd92761787897b2c8c060ed419126e2` Thanks @kyubisation! - Implement ShadowRoot and document in event path - #4894 `b
#4893 6c051d517bd92761787897b2c8c060ed419126e2 Thanks @kyubisation! - Implement ShadowRoot and document in event path
#4894 baa780d2b78a4b792cf61b220b8e3e186739d48c Thanks @kyubisation! - Add DOM shim implementation for MutationObserver, ResizeObserver and IntersectionObserver
#5240 b9de4295489b0caf91069bfe21f640f3ab5e12bb Thanks @kyubisation! - Register CSSStyleSheet polyfill in global scope when using Node.js hook for importing CSS files
#5330 077a4b727d0d30540f1813bbbe66477790c9805e Thanks @cecilyhunt! - fix(ssr-dom-shim): Add stubs for TS 6.0.3 compatibility
#3522 72fcf0d7 - When running in Node, Lit now automatically includes minimal DOM shims which are
sufficient for most SSR (Server Side Rendering) use-cases, removing the need to
import the global DOM shim from @lit-labs/ssr.
The new @lit-labs/ssr-dom-shim package has been introduced, which exports an HTMLElement, CustomElementRegistry, and default customElements singleton.
The existing @lit-labs/ssr global DOM shim can still be used, and is compatible with the new package, because @lit-labs/ssr imports from @lit-labs/ssr-dom-shim. Importing the global DOM shim adds more APIs to the global object, such as a global HTMLElement, TreeWalker, fetch, and other APIs. It is recommended that users try to remove usage of the @lit-labs/ssr DOM shim, and instead rely on the more minimal, automatic shimming that @lit/reactive-element now provides automatically.
72fcf0d7]:
### Minor Changes - #3507 `b152db29` - lit-html and reactive-element now include development Node builds with unminified code and dev warnings.
### Patch Changes - #3374 `bb098950` - Initializers added to subclasses are no longer improperly added to superclass.
### Patch Changes - #3222 `486739ec` - Fix CSSStyleSheet is not defined error that would occur when importing a Lit component in Node when both static
### Minor Changes - #4987 `3ac01aee` - Implement the full CustomElementRegistry type for the ssr shim. Improves fidelity and compilability.
ae6f6808 - Lit and its underlying libraries can now be imported directly from Node without crashing, without the need to load the @lit-labs/ssr dom-shim library. Note that actually rendering from a Node context still requires the @lit-labs/ssr dom-shim, and the appropriate integration between @lit-labs/ssr and your framework/tool.Nothing published for this version
Nothing published for this version
### Patch Changes - #3132 `2fe2053f` - Added "types" entry to package exports. This tells newer versions of TypeScript where to look for typings for e
### Patch Changes - #2978 `634d4560` - Changed the caching behavior of the css`` template literal tag so that same-text styles do not share a CSSStyle
### Patch Changes - #2688 `ef178ef6` - Add explicit types to the jsdoc code samples for query, queryAll, and queryAsync.
### Patch Changes - #2635 `ae358703` - Make the event debug logger lazier, doing even less work (with no side effects) even in dev mode unless the pag
### Minor Changes - #4755 `25962bf5` Thanks @kyubisation! - Implement SSR event handling and an optional flag globalThis.litSsrCallConnectedCallback t
25962bf5 Thanks @kyubisation! - Implement SSR event handling and an optional flag globalThis.litSsrCallConnectedCallback to call connectedCallback during SSR, if set to true.### Patch Changes - #2518 `bbbf21d4` - Fix breaking change in the PropertyValues type. Make PropertyValues compatible with Map and other Map types. -
#2518 bbbf21d4 - Fix breaking change in the PropertyValues type. Make PropertyValues<any> compatible with Map<string, string> and other Map types.
#2526 a50d188a - Export PropertyValueMap such that JavaScript generated by Google Closure Compiler can reference this type. Do not directly import the PropertyValueMap interface.
### Patch Changes - #2482 `6ea3d6c4` - Update the definition of the PropertyValues type to give better types to .get(k). .get(k) is now defined to ret
#2482 6ea3d6c4 - Update the definition of the PropertyValues type to give better types to .get(k). .get(k) is now defined to return the correct type when using PropertyValues<this> and a parameter that's a key of the element class.
#2464 df4e1a46 - Fix type signature in queryAssignedNodes JSDoc code example.
#2457 48d69184 - Add JSDoc to the willUpdate lifecycle callback. Expand the docs for firstUpdated, and attributeChangedCallback. Minor code sample fixes.
### Patch Changes - #4553 `65bc240c` Thanks @kyubisation! - Implement Element.localName and Element.tagName. Fixes 3375.
65bc240c Thanks @kyubisation! - Implement Element.localName and Element.tagName. Fixes 3375.### Minor Changes - #4493 `e901c582` - Add toggleAttribute to the Element shim.
#3885 7932f7dd - @lit-labs/ssr-react and @lit-labs/react now coordinate prop handling during server rendering and hydration.
@lit-labs/ssr-react will call setAttribute() with all props provided during server rendering unless they are provided in <code>_$litProps$</code> object made by @lit-labs/react. Previously, it would call setProperty() for props that were found in the element's prototype, and setAttribute() for those that weren't. If you wish to server render custom elements that take properties that can not be set as attributes (i.e. not serializeable or have different name as attribute/property), you must use @lit-labs/react to create a React wrapper component.@lit-labs/react now has a Node build and export condition to do special prop handling during server rendering. It detects the presence of React.createElement monkey patch by @lit-labs/ssr-react and provides props to be set as properties to the createElement() call.@lit-labs/ssr-react will add the defer-hydration attribute to custom elements that had properties set so that @lit-labs/react wrapped elements have a chance to set properties on the element before Lit element hydration is triggered.@lit-labs/react wrapped components will suppress hydration warnings raised by React due to server rendered attributes.### Patch Changes - #4598 `7cfb2274` Thanks @jun-sheaf! - Use target.set instead of member assignment in @consume() decorator.
7cfb2274 Thanks @jun-sheaf! - Use target.set instead of member assignment in @consume() decorator.### Patch Changes - #4903 `6a232e92` - Add Lit Labs noticed to README
Updated dependencies \[`feccc1ba`, `290a608a`]:
62df19da Thanks @autopulated! - ContextProvider can now be added to any HTML elements, not just custom elements implementing a ReactiveControllerHost.49ecf623 - Add queryAssignedElements decorator for a declarative API that calls HTMLSlotElement.assignedElements() on a specified slot. selector option allows filtering returned elements with a CSS selector.### Patch Changes - #4836 `05691ba4` Thanks @maxpatiiuk! - Improve type inference of tuples returned by the args function being used as task function
05691ba4 Thanks @maxpatiiuk! - Improve type inference of tuples returned by the args function being used as task function parameter.So far status was writable which allowed for setting status of task form outside. Doing so did cause rendering of expected template but the task was b
#4552 4050cac6 Thanks @jrencz! - Make status of Task a readonly property
So far status was writable which allowed for setting status of task form outside. Doing so did cause rendering of
expected template but the task was becoming internally incoherent.
Now attempt to assign status will end up in throwing a TypeError.
7fc72f7b Thanks @stefanpearson! - When passing a ref callback to the Component, createComponent was previously intercepting it and wrapping it in an unbound function. This change memoizes the consumer ref with useCallback, to keep the reference stable and ensure it isn't invoked repeatedly on subsequent renders.#4329 df1980fe - Remove dependency on lit package. All implementation code only uses @lit/reactive-element. lit is moved to dev dependencies as it is still used for tests.
#4286 1fb7a108 - Fix erroneous description for the JSDoc on the @provide() decorator.
#4287 4edf9bc8 - Broaden the host type of context controllers and decorators to be compatible with Lit 2
### Major Changes - #4170 `04c8d65a` - Graduate @lit-labs/task to @lit/task, its permanent location. @lit-labs/task is now just a proxy for @lit/task,
@lit/reactive-element is a new package that factors out the base class that provides the reactive update lifecycle based on property/attribute changes to LitElement (what was previously called UpdatingElement) into a separate package. LitElement now extends ReactiveElement to add lit-html rendering via the render() callback. See ReactiveElement API for more details.UpdatingElement has been renamed to ReactiveElement.updating-element package has been renamed to @lit/reactive-element.@internalProperty decorator has been renamed to @state._getUpdateComplete to getUpdateComplete.reflect: true and its toAttribute function returns undefined the attribute is now removed where previously it was left unchanged (#872).unhandledrejection event handler on window.renderRoot is now created when the element's connectedCallback is initially run.requestUpdateInternal. The requestUpdate method is now identical to this method and should be used instead.initialize method has been removed. This work is now done in the element constructor.static addInitializer for adding a function which is called with the element instance when is created. This can be used, for example, to create decorators which hook into element lifecycle by creating a reactive controller (#1663).connectedCallback, disconnectedCallback, willUpdate, update, and updated. To ensure it has access to the element lifecycle, a controller should be added in the element's constructor. To add a controller to the element, call addController(controller).removeController(controller) which can be used to remove a controller from a ReactiveElement.willUpdate(changedProperties) lifecycle method to UpdatingElement. This is called before the update method and can be used to compute derived state needed for updating. This method is intended to be called during server side rendering and should not manipulate element DOM.The /-suffixed syntax for subpath folder mapping originally used in these files is deprecated. Rather than update to the new syntax, this change repla…
#2103 15a8356d - Updates the exports field of package.json files to replace the subpath
folder
mapping
syntax with an explicit list of all exported files.
The /-suffixed syntax for subpath folder mapping originally used in these
files is deprecated. Rather than update to the new syntax, this change replaces
these mappings with individual entries for all exported files so that (a) users
must import using extensions and (b) bundlers or other tools that don't resolve
subpath folder mapping exactly as Node.js does won't break these packages'
expectations around how they're imported.
2b8dd1c7 - Adds scheduleUpdate() to control update timing. This should be implemented instead of performUpdate(); however, existing overrides of performUpdate() will continue to work.7adfbb0c - Remove unneeded matches support in @queryAssignedNodes. Update styling tests to use static bindings where needed. Fix TODOs related to doc links.61fc9452 - Throws rather than warns in dev mode when an element has a class field that shadows a reactive property. The element is in a broken state in this case.724a9aab - Ensures dev mode warnings do not spam by taking care to issue unique warnings only once.(Since 1.0.0-rc.2) Reverted change of the css tag's return to CSSResultGroup, which was a breaking change. The css tag again returns a CSSResult objec…
ff0d1556 - Fixes polyfill-support styling issues: styling should be fully applied by firstUpdated/update time; late added styles are now retained (matching Lit1 behavior)5768cc60 - Reverts the change in Lit 2 to pause ReactiveElement's update cycle while the element is disconnected. The update cycle for elements will now run while disconnected as in Lit 1, however AsyncDirectives must now check the this.isConnected flag during update to ensure that e.g. subscriptions that could lead to memory leaks are not made when AsyncDirectives update while disconnected.72877fd - Changed the caching strategy used in CSSResults returned from the css tag to cache the stylesheet rather than individual CSSResults.c8fe1d4 - For minified class fields on classes in lit libraries, added prefix to stable properties to avoid collisions with user properties.550a218 - Use a brand property instead of instanceof to identify CSSResults to make the checks compatible with multiple copies of the @lit/reactive-element package.6938995 - Changed prefix used for minifying class field names on lit libraries to stay within ASCII subset, to avoid needing to explicitly set the charset for scripts in some browsers.a791514b - Properties that must remain unminified are now compatible with build tools other than rollup/terser.#2050 8758e06 - Fix syntax highlighting in some documentation examples
(Since 1.0.0-rc.2) Reverted change of the css tag's return to CSSResultGroup, which was a breaking change. The css tag again returns a CSSResult object.
(Since 1.0.0-rc.2) Remove the CSSResultFlatArray type alias in css-tag.ts.
Changes below were based on the Keep a Changelog format. All changes above are generated automatically by Changesets.
(Since 1.0.0-rc.1) [Breaking] Change the type name Warnings to WarningKind #1854.
Warnings to WarningKind #1854.(Since 1.0.0-pre.3) A controller's hostConnected is called only once if an element is upgraded to a custom element #1731.
hostConnected is called only once if an element is upgraded to a custom element #1731.(Since 1.0.0-pre.2) The createRenderRoot method is now called only once #1679.
createRenderRoot method is now called only once #1679.(Since 1.0.0-pre.1) Adds static addInitializer for adding a function which is called with the element instance when is created. This can be used, for
static addInitializer for adding a function which is called with the element instance when is created. This can be used, for example, to create decorators which hook into element lifecycle by creating a reactive controller (#1663).removeController(controller) which can be used to remove a controller from a ReactiveElement.(Since 1.0.0-pre.1) A controller's hostUpdated method is now called before the host's firstUpdated method (#1650).
(Since 1.0.0-pre.1) Fixed @query decorator when cache flag is used and code is compiled with Babel (#1591).
(Since 1.0.0-pre.1) Renamed all decorator modules to use kebab-case filename convention rather than camelCase.
(Since 1.0.0-pre.1) ReactiveController callbacks all now begin with host, for example hostConnected, hostDisconnected, hostUpdate, hostUpdated.
(Since 1.0.0-pre.1) If a Controller is added after a host element is connected, its connected will be called.
(Since 1.0.0-pre.1) Removed willUpdate from ReactiveController.
(Since 1.0.0-pre.1) Renamed Controller's dis/connectedCallback methods.
(Since 1.0.0-pre.1) Renamed Controller to ReactiveController.
Made JSCompiler_renameProperty block scoped so that it's inlined in the Terser prod build. Closure should compile from the development build, or after a custom TypeScript compilation.
[Breaking] (since 3.0.0-pre1) UpdatingElement has been renamed to ReactiveElement.
[Breaking] (since 3.0.0-pre1) UpdatingElement has been renamed to ReactiveElement.
[Breaking] (since 3.0.0-pre1) The updating-element package has been renamed to @lit/reactive-element.
[Breaking] (since 3.0.0-pre1) The @internalProperty decorator has been renamed to @state.
[Breaking] For consistency, renamed _getUpdateComplete to getUpdateComplete.
[Breaking] When a property declaration is reflect: true and its toAttribute function returns undefined the attribute is now removed where previously it was left unchanged (#872).
Errors that occur during the update cycle were previously squelched to allow subsequent updates to proceed normally. Now errors are re-fired asynchronously so they can be detected. Errors can be observed via an unhandledrejection event handler on window.
UpdatingElement's renderRoot is now created when the element's connectedCallback is initially run.
[Breaking] Update callbacks will only be called when the element is connected to the document. If an element is disconnected while an update is pending, or if an update is requested while the element is disconnected, update callbacks will be called if/when the element is re-connected.
Console warnings added for removed API and other element problems in developer mode. Some warnings are errors and are always issued while others are optional. Optional warnings can be configured per class via MyElement.enable/disableWarning. Making changes in update warns by default and can be toggled via MyElement.disableWarning('change-in-update); migration warnings are off by default and can be toggled via MyElement.enableWarning('migration').
Added ability to add a controller to an element. A controller can implement callbacks that tie into element lifecycle, including connectedCallback, disconnectedCallback, willUpdate, update, and updated. To ensure it has access to the element lifecycle, a controller should be added in the element's constructor. To add a controller to the element, call addController(controller).
Added willUpdate(changedProperties) lifecycle method to UpdatingElement. This is called before the update method and can be used to compute derived state needed for updating. This method is intended to be called during server side rendering and should not manipulate element DOM.
UpdatingElement moved from lit-element package to updating-element package.
requestUpdateInternal. The requestUpdate method is now identical to this method and should be used instead.initialize method has been removed. This work is now done in the element constructor.queryAssignedNodes when applying a selector on a slot that included text nodes on older browsers not supporting Element.matches #1088.One column per quarter.