Lit Blog

Lightning-fast templates & Web Components: lit-html & LitElement

2019-02-05T00:00:00Z

Today we're excited to announce the first stable releases of our two next-generation web development libraries: lit-html and LitElement.

lit-html is a tiny, fast, expressive library for HTML templating. LitElement is a simple base class for creating Web Components with lit-html templates.

If you've been following the projects, you probably know what lit-html and LitElement are all about (and you can skip to the end if you like). If you're new to lit-html and LitElement, read on for an overview.

lit-html: a tiny, fast library for HTML templating

lit-html is a tiny (just over 3k bundled, minified, and gzipped) and fast JavaScript library for HTML templating. lit-html works well with functional programming approaches, letting you express your application's UI declaratively, as a function of its state.

const myTemplate = (name) => html`
  <div>
    Hi, my name is ${name}.
  </div>
`;

It's simple to render a lit-html template:

render(myTemplate('Ada'), document.body);

Re-rendering a template only updates the data that's changed:

render(myTemplate('Grace'), document.body);

lit-html is efficient, expressive, and extensible:

Efficient. lit-html is lightning fast. When data changes, lit-html doesn't need to do any diffing; instead, it remembers where you inserted expressions in your template and only updates these dynamic parts.
Expressive. lit-html gives you the full power of JavaScript, declarative UI, and functional programming patterns. The expressions in a lit-html template are just JavaScript, so you don't need to learn a custom syntax and you have all the expressiveness of the language at your disposal. lit-html supports many kinds of values natively: strings, DOM nodes, arrays and more. Templates themselves are values that can be computed, passed to and from functions, and nested.
Extensible: lit-html is also customizable and extensible—your very own template construction kit. Directives customize how values are handled, allowing for asynchronous values, efficient keyed-repeats, error boundaries, and more. lit-html includes several ready-to-use directives and makes it easy to define your own.

A number of libraries and projects have already incorporated lit-html. You can find a list of some of these libraries in the awesome-lit-html repo on GitHub.

If templating is all you need, you can get started now with the lit-html docs. If you'd like to build components to use in your app or share with your team, read on to learn more.

LitElement: a lightweight Web Component base class

LitElement is a lightweight base class that makes it easier than ever to build and share Web Components.

LitElement uses lit-html to render components and adds APIs to declare reactive properties and attributes. Elements update automatically when their properties change. And they update fast, without diffing.

Here's a simple LitElement component:

@customElement('name-tag')
class NameTag extends LitElement {
  @property()
  name = 'a secret';

  render() {
    return html`<p>Hi, my name is ${this.name}!</p>`;
  }
}

class NameTag extends LitElement {
  static properties = {
    name: {},
  };

  constructor() {
    super();
    this.name = 'a secret';
  }

  render() {
    return html`<p>Hi, my name is ${this.name}!</p>`;
  }
}
customElements.define('name-tag', NameTag);

This creates an element you can use anywhere you'd use a regular HTML element:

<name-tag name="Ida"></name-tag>

If you use Web Components already, you'll be happy to hear that they're now natively supported in Chrome, Safari and Firefox. Edge support is coming soon, and polyfills are only needed for legacy browser versions.

If you're new to Web Components, you should give them a try! Web Components let you extend HTML in a way that interoperates with other libraries, tools, and frameworks. This makes them ideal for sharing UI elements within a large organization, publishing components for use anywhere on the web, or building UI design systems like Material Design.

You can use custom elements anywhere you use HTML: in your main document, in a CMS, in Markdown, or in views built with frameworks like React and Vue. You can also mix and match LitElement components with other Web Components, whether they've been written using vanilla web technologies or made with the help of tools like Salesforce Lightning Web Components, Ionic's Stencil, SkateJS or the Polymer library.

Get started

Want to try lit-html and LitElement? A good starting point is the LitElement tutorial:

Try LitElement

If you're interested in using lit-html by itself, or integrating lit-html templating into another project, see the lit-html docs:

lit-html docs

As always, let us know what you think. You can reach us on Discord or Twitter. Our projects are open source (of course!) and you can report bugs, file feature requests or suggest improvements on GitHub:

LitElement 3.0 & lit-html 2.0: Early Preview Release

2020-09-22T00:00:00Z

Today we’re publishing the first preview releases of the next major versions of our flagship libraries, LitElement and lit-html.

These releases include most of the breaking changes we intend to make, and most of the functionality we want to carry over from the previous versions. They are not yet feature complete or fully API stable. Notably, they don’t yet support legacy browsers like IE11, or browsers requiring the web components polyfill.

Motivation

We’ve been very happy with the current versions of our libraries—they’re fast, small, and stable (yay!)—and in some ways we don’t have very many pressing needs to make breaking changes. We don’t make breaking changes lightly. But there are some compelling reasons for changes that we think will improve the user-experience of components and applications built with LitElement.

Performance

We have found that some of our browser-bug workaround code and customization abstractions prevent optimizations that we would like to do.
Size

That same code, and our extensive public API, costs bytes. We always want to find ways to make the libraries smaller.
Features & API cleanup

Some features are difficult to add in a cost-effective way with the current architecture, or can’t really be improved without breaking changes.
Server-side-rendering

lit-html has an extremely flexible and customizable API, and in some ways is more of a template-system construction kit than a single template-system. But this flexibility complicates SSR, which needs to make assumptions about how the server-rendered HTML maps to templates. SSR would only work well with the default, uncustomized lit-html, so limiting customization makes SSR more reliable. Very few developers used the customization APIs anyway.

We also want to make the directive API SSR compatible by limiting access to the DOM.

What’s changed

These are new major versions, so there are some breaking changes, but we want to minimize disruption to our users as much as possible. We’ve limited the breaking changes so that they don’t affect most users, or only require a mechanical change (like changing an import).

Please see the READMEs (LitElement, lit-html) and CHANGELOGs (LitElement, lit-html) for the most detailed list of changes.

The most important changes:

Customizing the syntax of lit-html is no longer directly supported. The templateFactory and TemplateProcessor APIs have been removed.
The public API has been minimized in order to facilitate better minification and future evolution.
The lit-html directive API has changed to be class-based and to persist directive instances. Directives should be easier to write and easier to make SSR compatible.
The LitElement decorators are no longer exported from the main module—they have to be imported individually or from a new lit-element/decorators.js module. This means smaller app sizes for non-decorator-users and opens the door to new decorators implementing the current TC39 JavaScript proposal when those arrive.
lit-html no longer uses instanceof or module-level WeakMaps to detect special objects like template results and directives, which should improve the compatibility of multiple copies of lit-html in a single app. We still recommend de-duping npm packages, but more cases will work now.
Safari 12 has a critical template literal bug, which is no longer worked around in lit-html. If you support Safari 12 you will have to compile template literals to their ES5 equivalent. Note that babel-preset-env already does this for the broken versions of Safari.

There are smaller changes listed in the change logs. Overall we hope these versions are drop in replacements for most users, or only require updating decorator imports.

Installation

Run:

npm i lit-element@next-major

And/or:

npm i lit-html@next-major

Submitting feedback

We’re in the process of moving the next versions of LitElement and lit-html into a mono-repo. Please file issues on the current lit-html repo, using a prefix of [lit-html] or [lit-element]. We expect that, as with any pre-release, there will be common issues we will have to fix. Please search for your issue first. Issues for the next major versions will have the label lit-next.

What’s next

For the next preview release we will be focusing on browser and polyfill support, especially IE11.

Lit 2.0: Meet Lit, all over again!

2021-04-21T00:00:00Z

Today, we’re excited to announce the first release candidate of Lit 2.0!

As we shared last summer, we have been hard at work on our first major update since shipping production-ready versions of lit-html and LitElement in early 2019. We’re calling this update Lit 2.0.

The API has been stable for a few months, and we’ve gotten great feedback from prerelease users, so late last night we cut our first release candidate. All that stands between us and an official release is a bit more time for developers to put the software through its paces and identify any final issues.

What’s in the new version?

Our major goals for Lit 2.0 were to reduce size, add powerful new features, improve performance and make some key changes under the hood to facilitate server-side rendering (SSR) — all while minimizing breaking changes. Easy, right?

Happily, we might have actually done it! To paraphrase a popular dance track from the early days of the Web, Lit 2.0 is:

Smaller. Lit 2.0’s templating system weighs in at 2.8k (minified and compressed), 10% smaller than the previous version, and its complete component base class (including templating) is just 5.2k, 20% smaller than before.
Better. Meanwhile, we’ve added a raft of new features, including several templating enhancements; a clean, new, class-based API for directive authors; and reactive controllers, a powerful new primitive for sharing stateful logic between components.
Faster. Efficient rendering has always been one of our core values, and Lit 2.0 is speedier than ever before: up to 20% faster on initial render, and up to 15% faster on updates.
Server. Lit 2.0 includes the foundation for fast, streaming SSR and flexible client-side hydration, unlocking a full range of use cases — from integration with popular frameworks (e.g., Next.js) and static site generators (e.g., eleventy) to apps built entirely with Lit and other web components.

And all of these improvements come with minimal changes to the existing API: the vast majority of existing Lit code will run with little to no modification. If you’re updating from a previous version, check out our helpful upgrade guide.

What else is new?

As we hinted above, the big news doesn’t end with the Lit 2.0 update — we’ve also made some major improvements beyond the software itself.

Most importantly, we’ve simplified our packaging, docs and presence. Whereas lit-html and LitElement have historically been separate packages with separate sites and docs, we’ve now combined them into a single product with a clear, simple identity — Lit — and a distinctive new logo.

Users have casually referred to our offerings as “Lit” for some time. By formalizing this name and simplifying the way we deliver the software, we aim to make Lit even easier to understand and use.

So, what does this mean in practice?

A new npm package: Installing Lit is now as simple as typing npm i lit. Since this is really our second major release, we chose to release the initial version of the new package as 2.0.
A new website: lit.dev is a brand new, one-stop shop for all things Lit, with a complete set of unified docs, a no-install interactive tutorial, a playground for exploring and creating sample code, and a dedicated Lit blog.
A new home on GitHub: We’ve moved our source code and issue tracker to the new Lit org on GitHub. Most of the code lives in the new lit mono-repo, which simplifies testing and releasing and makes the project more approachable for external contributors.
A new Twitter handle: We’ll be tweeting about Lit from @buildWithLit — follow this account to stay on top of all the latest news.

Simple. Fast. Web Components.

There’s actually a whole lot more to share, so we encourage you to explore lit.dev, watch today’s launch event (live or after the fact), and keep your eye on Twitter and the blog for more details in the coming weeks.

But despite all the news, Lit fundamentally remains what it has always been: a simple library for building fast, lightweight web components. Because it embraces the browser’s native component model, Lit is perfectly suited for building shareable components or design systems, and it can also help you build highly maintainable, future-ready sites and apps.

We can’t wait to see what you build with Lit 2.0!

Announcing Lit 2 stable release

2021-09-21T00:00:00Z

Today we're announcing the stable release of Lit 2. Lit 2 is a major update: it's smaller, faster and better than before, it lays the foundation for server-side rendering, and it's all wrapped up in the new lit package on npm.

Lit has come a long way since April when we announced the first release candidate for Lit 2. Since then, many partners have tested the release candidates on big applications and reported easy upgrades, better performance, and smaller bundles. In addition, some partners and community members have been exploring new features like reactive controllers and experimental server-side rendering support.

Meanwhile, at Google, we've extensively tested Lit 2 by upgrading thousands of Google's internal components to the new version.

Today we're happy to announce that Lit 2 is ready to go.

Correction: The lit-analyzer CLI and VS Code Lit plugin are being updated to work with Lit 2. The original version of this post incorrectly stated that these had already been released.

What’s in Lit 2?

Lit 2 adds a number of new features and enhancements while maintaining backward compatibility; in most cases, Lit 2 should be a drop-in replacement for previous versions. Significant new features in Lit 2 include:

New directive API. Lit 2 introduces a new class-based API for writing custom directives, objects that can customize how Lit renders. Directives aren't new, but the new API makes them more powerful and easier to define.
Asynchronous directives. Async directives can be notified when they are added to and removed from the DOM, which allows directives to do clean up work. For example, an async directive could use the callbacks to subscribe and unsubscribe to an observable.
Reactive controllers. A reactive controller is an object that can hook into a component's lifecycle, so they can respond when the component updates, and when the component is added to or removed from the DOM. Controllers can bundle state and behavior related to a feature, making it reusable across multiple component definitions. Reactive controllers can make it easy to add state management, animations, async tasks and much more to components.
Element expressions. New in Lit 2 is the ability to add expressions that act on an element as a whole, rather than modifying a property, attribute, or the element's children. Element expressions are useful for directives that need to manipulate multiple properties or to call methods on the element.

For example, an experimental animation package, @lit-labs/motion provides an animate() directive that animates when the element's state changes. For example, the following snippet animates list items when the list reorders.
```
html`
  ${repeat(items,
    (item) => item.id,
    (item) => html`<div ${animate()}>${item}</div>`)
  }`
```
For a more complete example of the animate directive, see the package README.
Static expressions. Also new in Lit 2, static expressions allow you to interpolate constant or rarely-changed values into a template before processing. Static expressions can be used in a variety of places where ordinary expressions cannot—for example, in tag-name position:
```
const tagName = literal`button`;
html`<${tagName}></${tagName}>`
```
SSR-ready. Lit 2 was rebuilt to be SSR-ready. The new @lit-labs/ssr package implements fast, streaming SSR for Lit on Node.js. SSR support is still experimental; work is ongoing to finish and test the SSR library.

In addition to the new features in the Lit library, we've made a few more changes around Lit:

All Lit related projects are in a new GitHub organization. Most Lit related code has been moved to a monorepo to make it easier to test changes.
The monorepo also includes a number of experimental projects, including server-side rendering support for Lit and other web components; animation helpers; and a Lit controller for asynchronous tasks. Experimental projects are published under the @lit-labs npm scope.
An all-new website, lit.dev, featuring guides, API docs, tutorials, and an interactive code editor. We launched the site with the initial Lit release candidate; since then we've added two of the most-requested features: site search, and better support for JavaScript users, with switchable JavaScript/TypeScript code snippets.

Changes since RC 1

Since the initial RC, most changes have been bug fixes. A few notable changes:

Element lifecycle not paused when an element is disconnected. This reverts a change in Lit that caused some subtle bugs. If you developed an asynchronous directive using one of the Lit 2 release candidates, you may need to make some changes. For details, see PR #2034.
Better runtime warnings in the development build. For information on using the development build, see Development and production builds.

For a full list of changes, see the changelog.

Get started with Lit 2

Want to try out Lit 2? Visit lit.dev to get started. The site features a catalog of interactive tutorials to get you started with Lit 2, an interactive playground for live coding, guides, and API docs.

Want to talk Lit? Join the Lit Discord for discussions on Lit and web components, or open a discussion on our GitHub Discussions board.

Watch the Lit 2 release livestream

2021-09-22T00:00:00Z

If you weren't able to join us for the Lit 2 release livestream, you can watch the recording on YouTube.

Lit 2.1 Release

2022-01-05T00:00:00Z

Happy New Year from the Lit team! This week we're excited to share a few updates with our fantastic community in the form of the Lit 2.1 release and some Lit Labs updates.

Lit 2.1 consists of:

New directives that help with looping and conditionals in your templates.
New @queryAssignedElements decorator, related to the existing @queryAssignedNodes decorator.

Plus we have some Lit Labs updates to make your season bright:

The new @lit-labs/observers package provides reactive controllers for working with web platform observers like MutationObserver and ResizeObserver.
Updates to the @lit-labs/task package.
Updates to the @lit-labs/ssr package.

For more details, read on.

New directives

Lit brings a handful of new convenience directives that make working with conditionals and looping a bit more declarative. Mostly wrappers around plain JavaScript expressions, we've found that many users appreciate the way these helpers reduce clutter in their templates.

Like all of the directives included with Lit, these new directives are pay-as-you-go: they're shipped as separate modules, so you only bundle the directives that you choose to import.

when(cond, t, f) is like a ternary where the else clause is optional. It renders the first template if the condition is true, and the second if present and the condition is false.

render() {
  return html`
    ${when(this.user, () => html`User: ${this.user.username}`, () => html`Sign In...`)}
  `;
}

map(iter, fn) is like Array.map, but also works on iterators. It's similar to repeat() without the key function, but much smaller in code size.

render() {
  return html`
    <ul>
      ${map(this.items, (i) => html`<li>${i}</li>`)}
    </ul>
  `;
}

join(iter, t) interleaves items in an iterable with a joiner value or function. Useful for adding separators between items, like Array.join() but instead of returning a string returns an iterable of renderable values.

render() {
  return html`
    ${join(this.items, html`<span class="separator">|</span>`)}
  `;
}

range(start, end, step) is useful for iterating a specific number of times in a template.

render() {
  return html`
    ${map(range(8), () => html`<div class="cell"></div>`)}
  `;
}

choose(v, cases, defaultCase) chooses one template to render among a set of cases. It's like an inline switch statement.

render() {
  return html`
    ${choose(this.section, [
      ['home', () => html`<h1>Home</h1>`],
      ['about', () => html`<h1>About</h1>`]
    ],
    () => html`<h1>Error</h1>`)}
  `;
}

New @queryAssignedElements() decorator

@queryAssignedElements() returns the slotted or assigned elements for a given slot. It's similar to the existing @queryAssignedNodes() but uses the slot.assignedElements() method rather than slot.assignedNodes(). @queryAssignedNodes() has been updated to take an options object as an alternative to the positional argument API.

@queryAssignedElements({ slot: 'icon' })
private _icon!: Array<HTMLElement>;

Easy to use observers with @lit-labs/observers

In Lit Labs we've introduced a new package called @lit-labs/observers which contains reactive controllers that let you easily use the web platform observer APIs: MutationObserver, IntersectionObserver, ResizeObserver, and PerformanceObserver. The controllers automatically drive the host element's update lifecycle when they observe changes.

import { ResizeController } from '@lit-labs/observers/resize_controller.js';

class MyResizableElement extends LitElement {

  _resizeController = new ResizeController(this, {});

  render() {
    return html`Current size is ${this.offsetWidth} x ${this.offsetHeight}`;
  }
}

Task updates

We've landed some changes to @lit-labs/task that allow for manually run tasks and automatic tasks with no dependencies. Tasks with no dependencies will run once when the host is connected, and all tasks can be run manually with the new run() method.

SSR updates

We've also landed some bug fixes to @lit-labs/ssr, reduced its NPM dependencies footprint, and refactored the importModule function into a new ImportModule class as some groundwork for upcoming changes.

Keep in touch

We hope your 2022 is off to a good start. If you've tried the new releases, we'd love to hear from you. For questions and discussions, please join us on Discord or on GitHub Discussions. As always you can check out our documentation and code playground at lit.dev and report issues on our GitHub issue tracker.

Eleventy + Lit

2022-02-07T00:00:00Z

The Lit team is pleased to announce an experimental preview release of @lit-labs/eleventy-plugin-lit, a new plugin for Eleventy that renders your Lit components as static HTML during your Eleventy build, and lets you hydrate them after your JavaScript loads.

Check it out now on GitHub and NPM, or read on to learn more about what it does, why you might want to use it, and how it works.

What does it do?

After you've added @lit-labs/eleventy-plugin-lit to your Eleventy config, then whenever you write a custom element tag in a markdown or HTML file, the initial state of that component's shadow DOM and styles will be rendered directly into the static HTML.

For example, given a markdown file hello.md:

# Greetings

<demo-greeter name="World"></demo-greeter>

And a component definition js/demo-greeter.js:

import {LitElement, html, css} from 'lit';

class DemoGreeter extends LitElement {
  static styles = css`
    b { color: red; }
  `;

  static properties = {
    name: {},
  };

  render() {
    return html`Hello <b>${this.name}</b>!`;
  }
}
customElements.define('demo-greeter', DemoGreeter);

Then Eleventy will produce an HTML file hello/index.html like this:

<h1>Greetings</h1>

<demo-greeter name="World">
  <template shadowroot="open">
    <style>
      b { color: red; }
    </style>
    Hello <b>World</b>!
  </template>
</demo-greeter>

This HTML allows the browser to paint the initial state of the component's DOM and styles, preserving all of the encapsulation boundaries of web components, even before a single line of JavaScript has downloaded!

Later, when the JavaScript definition of <demo-greeter> has finally loaded, the statically rendered component is upgraded to its fully interactive JavaScript implementation through a process called hydration.

Why should I use it?

Statically rendering components can be an effective method for reducing the time it takes between a page starting to load, and the content becoming visible. This is an important consideration that contributes to the responsiveness of your site, particularly for users with slower connections and devices.

By transmitting the initial state of your components as static HTML, the browser is able to paint the initial view much faster than it takes to download, parse, and evaluate the JavaScript implementations of those components.

For a deeper dive into the benefits of static rendering, check out Rendering on the Web, and for a discussion of how to measure this aspect of web performance, check out Largest Contentful Paint (LCP).

How does it work?

Lit Labs SSR

The plugin uses @lit-labs/ssr under the hood, which works by creating an instance of each component in a lightweight browser-like environment within the Eleventy Node process, and evaluating the element's template using a special version of Lit's render function. This special render function behaves much like the render function that Lit uses in the browser, except that it emits a stream of strings instead of writing to the DOM, allowing it to be efficiently written out as static HTML.

For more information about @lit-labs/ssr, check out its GitHub repo. We'll be expanding the documentation soon to help developers integrate @lit-labs/ssr into more tools and frameworks!

Declarative Shadow DOM

When @lit-labs/ssr renders a component, it uses <template shadowroot> HTML elements to represent the component's shadow DOM and styles. When the browser HTML parser encounters a <template shadowroot>, it applies that template's content as the shadow root of its parent element. This way, all of the DOM and style encapsulation guarantees of web components are preserved.

As of February 2022, Chrome and Edge have native support for Declarative Shadow DOM, but Firefox and Safari have not yet implemented it. A very small polyfill is available for browsers that don't yet have support. Integrating the polyfill into your site is documented in the @lit-labs/eleventy-plugin-lit README.

For more information about Declarative Shadow DOM, check out Declarative Shadow DOM.

Hydration

While static rendering lets your components' initial paint happen as quickly as possible, the components won't yet be interactive, because their JavaScript implementations haven't loaded.

Hydration is the process where a statically rendered component is upgraded to its JavaScript implementation, becoming responsive and interactive.

Lit comes with automatic support for hydration via the special @lit-labs/ssr-client/lit-element-hydrate-support.js module. As long as this module has been loaded, Lit components will detect when they have been statically rendered, and will adopt their existing shadow root.

Hydration with Lit is very efficient, because Lit knows that it doesn't need to re-render the existing shadow root when it upgrades. If data changes after hydration, then only the parts of the shadow root that changed will be updated.

What's next?

Check out the roadmap for @lit-labs/eleventy-plugin-lit for some of the main features and fixes you can expect to land over the coming months.

If you try out @lit-labs/eleventy-plugin-lit, let us know if you have any suggestions or find any problems by starting a discussion or filing an issue.

Lit on Discord!

2022-09-06T00:00:00Z

We've just launched a brand new Lit Discord server, and we'd love for you to join it now! Everybody is welcome, whether you are brand new to Lit, or an experienced user.

We think the Lit Discord will be the best place to chat with the Lit community, talk to the Lit dev team, get help using Lit, and show off your Lit projects! We also plan to host special events there, using both chat and voice!

Why Discord?

Here's what we like best about Discord:

It's easy to be in many communities, becuase you can quickly switch between them.

There are already Discords for Modern Web, Shoelace, Vaadin, Material, Astro, and many other open source projects, so we think it will be great to be able to easily jump between them, share announcements, and more.
Syntax highlighting, including for nested html tagged template literals!
Traction & growth. Discord has had huge growth in recent years, and new open source projects seem to be choosing Discord more often than not now. We think that's becuase using Discord is a great experience, and because the friction to joining new Discord servers is low after you've started using it.

What's happening to Slack?

The Lit & Friends workspace on Slack will be going into read-only mode on Tuesday, September 13, 2022. After that, you'll be able to read existing messages, but won't be able to post new ones. We've already sent a message to every channel about these plans.

We decided to retire the Slack instead of maintaining both because we want to encourage more communication and less silos. Slack has served the Lit community well, but we think now is the right time to move to Discord!

Get the lowdown on Lit Labs

2022-10-18T00:00:00Z

The Lit team is hosting a virtual event on Monday, October 24th 2022 at 10AM PDT to talk about all of the exciting work going on in Lit Labs. We'll give an overview of the Lit Labs program, followed by detailed presentations on several Labs packages. And we'll let you know how you can help get these packages across the finish line and shape the future of Lit!

To make sure you don't miss it, go to the live stream and sign up for notifications.

What is Lit Labs?

Lit Labs is an umbrella for Lit packages under development that we are actively seeking community engagement on. These projects may be experimental or incomplete, or simply looking for real-world feedback. Lit Labs projects are published under the @lit-labs npm scope.

What will be covered at the Lit Labs event?

We'll show you how individual Labs packages can help you in your Web Component projects, and let you know what each package needs to graduate from Labs. Here are the packages we'll be covering:

Task
Virtualizer
Motion
Context
React
CLI-generated Framework Wrappers
SSR
Observers

When is it, again?

The event will be on Monday, October 24th 2022 at 10AM PDT. Make sure to sign up for YouTube reminders and notifications on the event page so you don't miss it!

Announcing Lit 3.0 Pre-releases

2023-05-15T00:00:00Z

Announcing Lit 3.0 Pre-releases

The Lit team is excited to announce the first pre-releases of Lit 3.0!

Lit 3.0 is our first major version since introducing the unified Lit project and Lit 2.0 two years ago. We really value stability and backwards compatibility for our community, so we've focused on adding new features with minor versions of the core libraries and new labs packages, and not making any breaking changes.

But the time is right for just a few breaking changes that will improve development velocity and testing stability on the core Lit project.

Changes

Lit 3.0 adds no new features, because new features are generally not breaking changes and can be added in minor versions, according to semver. The Lit 3.0 release is an opportunity to make a few breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series.

The Lit 3.0 changes are mostly in browser support, removing deprecated APIs, and how packages are published. If you run Lit 2.x with no deprecation warnings, this should be a seamless upgrade!

Here are the biggest things Lit 3.0 changes:

IE11 is no longer supported.
Lit's npm modules are now published as ES2021.
APIs deprecated during the Lit 1.x release timeframe have been removed.
SSR hydration support modules were moved to the @lit-labs/ssr-client package.

A preview of the Lit v2 to v3 upgrade guide is available on the site.

Detailed change logs can be found on GitHub.

Trying the Pre-releases

We would love your help testing the new versions, to ensure a smooth upgrade process with the final releases. We're especially interested in making sure the new language version works with your toolchains. We expect some users may need to upgrade their tooling to the latest versions.

You can try the pre-releases out by updating your package.json file to include the following:

  "lit": "^3.0.0-pre.0"
  "lit-html": "^3.0.0-pre.0"
  "lit-element": "^4.0.0-pre.0"
  "@lit/reactive-element": "^2.0.0-pre.0"

You can also use the pre npm tag, like npm i lit@pre.

All other packages, like labs packages, have pre-release versions too that depend on the pre-release core libraries. If you depend on those you'll have to update them too. If you're more daring you can use npm overrides to select the pre-releases even for dependencies. This should work for most dependencies.

Even if dependencies are using Lit 2.x, the good news is that Lit 2.x and Lit 3.x are interoperable, because:

The inherent interoperability web components: components built with different libraries work together, including those build with different versions of Lit.
We made interop of core features like templates and directives a priority for Lit 2. You can share templates, directives, decorators, etc., across Lit versions.

Docs

We are preparing new docs for 3.0 on lit.dev. Even though these will be mostly the same as 2.x, we are clarifying the browser and toolchain support, and want to make it easy to select the right docs set for the version you're using to enable future changes specific to to 3.x. At the 3.0 launch, we’ll archive the 2.x docs (but they will remain available in the doc version dropdown, as will 1.x). During the 3.0 pre-release phase, 2.x will remain the default, and you can select v3 from the dropdown next to the Documentation tab.

Feedback

We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in GitHub issues or on our Lit and Friends Discord.

Thanks!,

-The Lit Team

Lit 3.0 Prerelease 2 and more!

2023-09-28T00:00:00Z

Lit 3.0 Prerelease 2 and more!

Today we are publishing the second prerelease of Lit 3.0.

This prerelease includes:

The core Lit 3.0 packages
The first graduating class of Lit Labs: Task, Context, and React
Our first preview of our new optimizing template compiler
A Preact Signals integration library

There are many other packages in this prerelease. See the full list and how to try them out here.

Lit 3.0 Prerelease 2

As we announced with the first prerelease, Lit 3.0 is a breaking change that most notably removes support for IE11. As a new major version, Lit 3.0 is intended to have no new features, since new features can be added in non-breaking minor versions.

Breaking changes

IE11 is no longer supported.
Lit's npm modules are now published as ES2021.
APIs deprecated with the Lit 2.0 release have been removed.
SSR hydration support modules are moved to the @lit-labs/ssr-client package.
Decorator behavior has been unified between TypeScript experimental decorators and standard decorators.
Support was removed for Babel decorators version "2018-09"

These breaking changes should have minimal impact for most users – based on testing against Google's codebase, they impact about one in a thousand elements – and allow our project to move forward more efficiently.

New: standard decorators support

The one new feature that we did add to Lit 3.0 is support for the TC39 standard decorators specification to our existing decorators.

The new decorator spec has reached Stage 3 in TC39, meaning that browsers and compilers are now implementing them. This is a huge step for Lit! The arrival of standard decorators allows us to begin the process of moving to a decorator implementation that won't require a compiler to use.

It's very important to us to make the upgrade path from experimental decorators as smooth as possible. To accomplish this we made our existing decorators support the standard spec and made them work with the new accessor keyword in experimental decorator mode.

This way you can use Lit decorators with auto-accessors (using the accessor keyword) so that the same call site works with both settings:

class MyElement extends LitElement {
  @property()
  accessor myProperty = 'hello';
}

Once all decorator call sites in your project use the accessor keyword, you can build with experimentalDecorators set to true or false without a change in behavior.

But in order to make these hybrid decorators have consistent behavior in both modes we had to make a few minor breaking changes to our experimental decorators:

We now call requestUpdate() automatically for @property and @state decorated accessors where previously that was the setter's responsibility.
The value of an accessor is read on first render and used as the initial value for changedProperties and attribute reflection.
@property and @state must be used on the setter for hand-written accessors.

Standard decorator mode requires TypeScript 5.2 or Babel 7.23 with the @babel/plugin-proposal-decorators plugin using decorator version "2023-05".

Outstanding issues with standard decorators

We still need to update our decorator documentation on lit.dev
The TypeScript and Babel emit for standard decorators is quite a bit larger than for TypeScript experimental decorators. We still recommend experimentalDecorators: true for production.

New Lit template compiler!

The releases today also include the first preview of our new template compiler: @lit-labs/compiler.

Our compiler is a TypeScript transform that rewrites lit-html templates into a prepared representation so that the template prep steps are skipped at runtime. This can improve first render performance, sometimes dramatically. All template behavior remains exactly the same.

We plan on offering the compiler in a number of tool plugin formats, but for now we just have a TypeScript transform. One of the easiest ways to use it is via Rollup's TypeScript plugin, which allows you to add transforms:

rollup.config.js:

import typescript from '@rollup/plugin-typescript';
import {compileLitTemplates} from '@lit-labs/compiler';

export default {
  // ...
  plugins: [
    typescript({
      transformers: {
        before: [compileLitTemplates()],
      },
    }),
    // other rollup plugins
  ],
};

Preact Signals integration

Signals: they're so hot right now!

Many frameworks are adopting signals – observable holders of state and computation – for performance and DX improvements. Lit already has a very efficient rendering system, and in preliminary tests signals aren't a clear performance improvement.

For Lit developers we think signals promise to offer a convenient and relatively simple option for shared observable state, a recurring need in our community. So we are starting to explore what it would look like to integrate signals with Lit with a new @lit-labs/preact-signals package.

This package provides three ways to use Preact Signals:

A SignalWatcher mixin, which makes a component automatically watch all signals used during updates.
A watch() directive, which watches one signal and updates a binding with it.
A special html template tag that auto-applies the watch() directive to all bindings that use signals.

Here's an example of using the SignalWatcher mixin:

import {LitElement, html} from 'lit';
import {customElement, property} from 'lit';
import {SignalWatcher, signal} from '@lit-labs/preact-signals';

const count = signal(0);

@customElement('signal-example')
export class SignalExample extends SignalWatcher(LitElement) {

  render() {
    return html`
      <p>The count is ${count.value}</p>
      <button @click=${this._onClick}>Increment<button></button></button>
    `;
  }

  private _onClick() {
    // A change to the signal value causes the element to re-render!
    count.value = count.value + 1;
  }
}

Why Preact Signals?

One issue that signals present for web components is that there are many different signals implementations and no interoperability between them. This goes against the interoperability goals of web components, so for now, rather than build our own signals package or pick just one that we endorse, we plan on offering integration packages to be able to use various signal libraries with Lit.

These integrations will be relatively simple because we have two straight-forward ways of using signals:

Treat a component's update lifecycle as an effect, so that it's run when any signals it accesses (like in templates) changes. This integrates signals with Lit's batching async lifecycle for good performance when many signals change.
Use a directive to wire a signal directly to a location in DOM.

We chose Preact's signals library for our first integration because it's a relatively small, fast, and easy-to-understand implementation published to npm as standard JS modules.

Lit Labs graduations

We are also graduating our first set of Lit Labs packages: Context, Task, and React.

These packages have a new home in the @lit npm scope, but are otherwise exactly the same as the current labs versions. The labs packages have been updated to depend on and re-export the non-labs versions so that they share a single implementation.

Trying out the prerelease

To try out the prerelease, update your package.json to depend on the prerelease package versions.

The packages in the prerelease are:

lit@3.0.0-pre.1
lit-element@4.0.0-pre.1
lit-html@3.0.0-pre.1
@lit/reactive-element@2.0.0-pre.1
@lit/context@1.0.0-pre.0
@lit/react@1.0.0-pre.0
@lit/task@1.0.0-pre.0
@lit-labs/compiler@1.0.0-pre.0
@lit-labs/preact-signals@1.0.0-pre.0

You should also update dependencies on our other packages so that they pick up the Lit prerelease as well.

Other Lit prerelease packages

@lit/localize-tools@0.7.0-pre.1
@lit/localize@0.12.0-pre.1
@lit/ts-transformers@2.0.0-pre.1
@lit-labs/analyzer@0.10.0-pre.0
@lit-labs/cli-localize@0.2.0-pre.1
@lit-labs/cli@0.6.1-pre.0
@lit-labs/context@0.5.0-pre.0
@lit-labs/eleventy-plugin-lit@1.0.2-pre.1
@lit-labs/gen-manifest@0.3.0-pre.0
@lit-labs/gen-utils@0.3.0-pre.0
@lit-labs/gen-wrapper-react@0.3.0-pre.0
@lit-labs/gen-wrapper-vue@0.3.0-pre.0
@lit-labs/motion@1.0.5-pre.0
@lit-labs/nextjs@0.1.2-pre.1
@lit-labs/observers@2.0.1-pre.1
@lit-labs/react@2.1.1-pre.0
@lit-labs/router@0.1.2-pre.1
@lit-labs/scoped-registry-mixin@1.0.2-pre.1
@lit-labs/ssr-client@1.1.4-pre.1
@lit-labs/ssr-dom-shim@1.1.2-pre.1
@lit-labs/ssr-react@0.2.1-pre.0
@lit-labs/ssr@3.1.8-pre.0
@lit-labs/task@3.1.0-pre.0
@lit-labs/testing@0.2.2-pre.1
@lit-labs/virtualizer@2.0.8-pre.0
@lit-labs/vue-utils@0.1.1-pre.1

Remember that Lit 2.x and Lit 3.0 are interoperable, so even if some of your dependencies are using Lit 2.x you can try the Lit 3.0 prerelease on your components!

Docs

You can view the Lit 3.0 docs on lit.dev at https://lit.dev/docs/v3/ .

We are still updating some of the docs, our main task until the final release of Lit 3.0.

Feedback

We hope you enjoy Lit 3.0! If you have questions or feedback, please let us know in GitHub issues or on our Lit and Friends Discord.

Thanks! - The Lit Team

Lit Launch Day: Lit 3.0, Labs graduations, a compiler and more!

2023-10-10T00:00:00Z

Lit Launch Day: Lit 3.0, Labs graduations, a compiler and more!

It's launch day for the Lit project, and we have a bunch of exciting releases to share with the Lit and web components communities!

After several months of development, the Lit team is happy to announce the final release of Lit 3.0 – our first major version since Lit 2.0 in early 2021, the first graduating class of Lit Labs packages @lit/react, @lit/task, and @lit/context, and two bonus releases @lit-labs/compiler and @lit-labs/preact-signals.

This is a big release, so here are links to the individual announcements:

Lit 3.0: Bye, Bye IE, Hello TC39 Decorators!

We value stability for our community. Breaking changes are a cost that every user and the entire ecosystem has to bear: projects have to upgrade, multiple versions can be included in an app, and documents, samples, tutorials, starter kits, etc. have to be updated for every breaking change.

So we want to only make breaking changes when we must, or when the benefits to the community clearly outweigh the costs. For benefits we tend look for decreased code size, increased performance, reduction in maintenance burden, and better alignment with standards.

We also follow semantic versioning, so we increase the major version only when there are breaking changes. New features typically arrive in new minor versions, which are backwards compatible. So Lit 3.0 is intended to only be a breaking change, with no new features. There is one exception though – standard decorators!

Breaking changes

For Lit 3.0, the biggest breaking change is that we've dropped IE11 support. After surveying our developer community, we feel like now is the right time to say goodbye to IE, and very few customers will be affected.

This release is also an opportunity to make a few additional breaking changes that trim out some technical debt to unlock new features we have scheduled for our 3.x release series and beyond.

These changes are hopefully minor for most customers. If you run Lit 2.x with no deprecation warnings, and use toolchain that supports modern JS, this should be a seamless upgrade!

Here are the biggest things Lit 3.0 changes:

IE11 is no longer supported.
Lit's npm modules are now published as ES2021.
APIs deprecated with the Lit 2.0 release have been removed.
SSR hydration support modules were moved to the @lit-labs/ssr-client package.
Decorator behavior has been unified between TypeScript experimental decorators and standard decorators.
Support was removed for Babel decorators version "2018-09"

Full details in the the upgrade guide.

New: standard decorators support

The one new feature that we did add to Lit 3.0 is support for the TC39 standard decorators specification to our existing decorators.

This way you can use Lit decorators with auto-accessors (using the accessor keyword) so that the same call site works with both settings:

class MyElement extends LitElement {
  @property()
  accessor myProperty = 'hello';
}

Once all decorator call sites in your project use the accessor keyword, you can build with experimentalDecorators set to true or false without a change in behavior.

But in order to make these hybrid decorators have consistent behavior in both modes, we had to make a few minor breaking changes to our experimental decorators:

We now call requestUpdate() automatically for @property and @state decorated accessors where previously that was the setter's responsibility.
The value of an accessor is read on first render and used as the initial value for changedProperties and attribute reflection.
@property and @state must be used on the setter for hand-written accessors.

Standard decorator mode requires TypeScript 5.2 or Babel 7.23 with the @babel/plugin-proposal-decorators plugin using decorator version "2023-05".

Upgrading

The upgrade from Lit 2.0 should be seamless for the vast majority of users. You can usually upgrade your npm dependency version with:

> npm i lit@latest

You can find more details and how to handle the changes in the Lit 3 upgrade guide.

Detailed change logs can be found on GitHub.

Even Faster Rendering with the new Lit Template Compiler

The new @lit-labs/compiler Labs package provides a TypeScript Transformer that can be run over your JavaScript or TypeScript files to do build-time preparation of Lit templates that Lit would normally do at runtime.

While not all templates will see rendering performance improvements from compilation, on our "template heavy" benchmark we measured a 46% faster first render, and a 21% faster update!

To try out @lit-labs/compiler today, you’ll need a build step that accepts a TypeScript transformer. For Rollup.js users, this could be @rollup/plugin-typescript. An example rollup.config.js file might look like:

// File: rollup.config.js
import typescript from '@rollup/plugin-typescript';
import {compileLitTemplates} from '@lit-labs/compiler';

export default {
  // ...
  plugins: [
    typescript({
      transformers: {
        before: [compileLitTemplates()],
      },
    }),
    // other rollup plugins
  ],
};

What does the transform do?

Given some source code containing an html tag function to declare templates:

const hi = (name) => html`<h1>Hello ${name}!</h1>`;

The Lit template transform will remove the html tag function and replace it with something similar to the following:

const b = (s) => s;
const lit_template_1 = {h: b`<h1>Hello <?></h1>`, parts: [{type: 2, index: 1}]};
const hi = (name) => ({_$litType$: lit_template_1, values: [name]});

We call this a compiled template, and it behaves the same as your authored template, except that when Lit renders the compiled template, Lit can skip an internal render phase called the Prepare phase, meaning you get a quicker initial render.

As you can see in the above example, there is some additional code generated as part of the transform. We’ve measured that minified and compressed, you may get a 5% increase in file size for the compiled file. This is something we have plans to address.

Looking forward

We’d love to hear from you and get feedback on your experience using the transform, as well as hear what you’d like to see optimized! Leave that feedback in this Labs Feedback discussion. We’d also like to learn more about what build systems Lit is used in, and welcome contributions!

This is just the beginning. With this new package we have a foundation for layering on additional build-time optimizations. Some optimizations we’ve thought about:

For a Lit app which can be completely compiled, we could vend an import of lit-html that is smaller.
Add an option to the compiler transform to also minify the HTML in the templates.
Do build-time evaluation of other parts of the Lit API, such as compiling away the built-in Lit decorators.
Compress the emitted output file by applying domain-specific file compression.

Preact Signals integration

Signals: they're so hot right now!

Many frameworks are adopting signals – reactive holders of state and computation – for performance and DX improvements. Lit already has a very efficient rendering system, and our preliminary benchmarks don't show a clear performance wins from signals.

This package provides three ways to use Preact Signals:

A SignalWatcher mixin, which makes a component automatically watch all signals used during updates.
A watch() directive, which watches one signal and updates a binding with it.
A special html template tag that auto-applies the watch() directive to all bindings that use signals.

Here's an example of using the SignalWatcher mixin:

import {LitElement, html} from 'lit';
import {customElement, property} from 'lit';
import {SignalWatcher, signal} from '@lit-labs/preact-signals';

const count = signal(0);

@customElement('signal-example')
export class SignalExample extends SignalWatcher(LitElement) {

  render() {
    return html`
      <p>The count is ${count.value}</p>
      <button @click=${this._onClick}>Increment</button>
    `;
  }

  private _onClick() {
    // A change to the signal value causes the element to re-render!
    count.value = count.value + 1;
  }
}

Why Preact Signals?

These integrations will be relatively simple because we have two straight-forward ways of using signals:

Treat a component's update lifecycle as an effect, so that it's run when any signals it accesses (like in templates) changes. This integrates signals with Lit's batching async lifecycle for good performance when many signals change.
Use a directive to wire a signal directly to a location in DOM.

We chose Preact's signals library for our first integration because it's a relatively small, fast, and easy-to-understand implementation published to npm as standard JS modules.

Lit Labs Graduation Day

We are also graduating our first set of Lit Labs packages: Context, Task, and React.

Find them in their new npm homes: @lit/react, @lit/task, and @lit/context

These packages can now be considered stable, and have documentation and examples on lit.dev!

Current users of these packages under the @lit-labs scope can migrate by first updating to the latest version of those packages to test for any breakages, then update the import to use the @lit scoped package. The latest @lit-labs scoped packages will receive the same updates until the next major version of the @lit scoped package.

Thank you so much to everyone in the community who has tested out a Labs package, filed issues, discussed features, and led these packages to graduation! 🎓

React

While custom elements can be used in React projects as is, there are some rough edges around their usage, namely:

Setting properties on elements (rather than attributes)
Adding handlers for custom events
Type checking custom elements and their props

Some of these are being addressed by React in a future version, but they are currently only present in experimental builds not recommended for production.

@lit/react allows creation of React components wrapping the custom element. The created components can be idiomatic to React such that users of the component do not have to worry about the inner web component implementation.

It is useful for both web component authors who wish to vend React versions of their components for users to reach a wider audience, as well as React developers who wish to use a neat web component that they found in their project more ergonomically.

@lit-labs/react has been our most popular labs project by far with over 500k weekly npm downloads and is already being used by many web component libraries to provide React versions of their components to users.

Read more about it at our React framework integration documentation.

Task

Working with asynchronous data in a Lit component tends to involve boiler plate code, and there are a few subtle edge cases to handle. Task is a simple ReactiveController that automatically handles these edge cases and makes it easy to do asynchronous work correctly.

Some considerations include:

Conditionally rendering different content while the data is pending, retrieved, or the request failed
Handling race conditions, ensuring the data for the latest request is kept and previous requests are cancelled or ignored if completed later

We've found @lit-labs/task indispensable when working with asynchronous values. It includes a number of refinements since its initial release, like how every task receives an AbortSignal that the library ensures aborts if the task run becomes obsolete.

We are happy for it to officially graduate and encourage everyone to use it! For more info see the new Async Tasks docs page.

Context

@lit/context is an interoperable system for an element to request data from any of its ancestors. It's useful for shared elements to receive configuration from their environment, for elements in a composable plugin system to exhange data, and as an interoperable DOM-based dependency injection system.

Start by creating a context using the createContext() function. A context acts as a key, for the consumer and provider of the data to identify each other.

Then, on the providing element, declare a property with the @provide decorator. As with the main lit decorators, these work as standard decorators, and with TypeScript's experimentalDecorators option enabled. The property's value will be made available to any descendents of the element that consume the context.

Finally, on the consuming element, declare a property with the @consume decorator. When the element attaches to the DOM it will receive the current value of the first ancestor that provides the context. If called with subscribe: true then it will also receive updates as the value changes.

For more info, see the Context documentation.

We're excited to see what you build with Lit!

We're constantly amazed by the things the Lit and web components communities are building, and can't wait to see what's going to be made with Lit 3.0 and our growing collection of helper libraries.

Please drop by our Discord server, GitHub discussions or find us on the site formerly known as Twitter to join our community and show us what you're up to!

Thanks!,

-The Lit Team

Bringing Signals to Lit Labs

2024-10-08T00:00:00Z

Announcing @lit-labs/signals: Integrating the TC39 Signals Proposal with Lit

We’re thrilled to announce the release of our newest Lit Labs package, @lit-labs/signals, which integrates the polyfill for the exciting new TC39 Signals Proposal directly with Lit. This package provides a powerful, reactive way to manage state in your web applications by allowing you to use shared, observable signals that automatically update components when their values change.

Signals are quickly becoming a core feature in the JavaScript ecosystem, and the TC39 proposal has the potential to unify signals and how we manage state and reactivity across various libraries and frameworks.

Though the proposal is in its early stages, you can start experimenting with signals and @lit-labs/signals today to see how building components and apps on a universal reactivity primitive might work for you.

What Are Signals?

In simple terms, signals are observable data structures that hold values or computations. When the value of a signal changes, all components or parts of your app that depend on it are automatically notified and updated. This is particularly useful in UIs where multiple components might need to share and react to changes in state.

Key Benefits of Standards-Based Signals

Shared observable state: Signals are great for managing state shared across multiple components. If one component updates a signal, all others using it will automatically update as well.
Pinpoint updates: Signals enable precisely targeted re-renders, potentially improving performance by processing only bindings whose signal- backed values have changed, skipping other bindings in the same templates.
Interoperability: The standardization of signals means different libraries and frameworks can use signals interoperably, reducing the need for complex adapters and improving compatibility.

Why We're Excited About `@lit-labs/signals`

Lit is already known for its lightweight, performant, and declarative approach to building web components. But Lit is tightly focused on helping you build reusable, encapsulated components. Lit is not a framework and does not precribe how to model your data or make it observable.

Lit's reactivity is by default relatively shallow. Components automatically update when their own reactive properties change, but not when nested properties change. Responding to deep property changes has either required manual update requests, or the integration of a state management system like Redux or MobX.

Signals give us many of the same deep observability abilities as these state management systems, but with a smaller, simpler API, and the potential to be a common standard across a large ecosystem of utilies, components, and frameworks.

Signals aren't entirely new to Lit. We previously released the @lit-labs/preact-signals package, but we were somewhat unsatisfied with the need to build a Lit integration for a specific signals library, and potentially every signals library that Lit developers might want to use.

Standardized signals in JavaScript would let us build just one integration (and eventually add signals support directly in Lit's core), and enable interop between signal-using libraries in the same spirit of the interop that web components enable.

The new @lit-labs/signals package makes it super easy to use the new signals proposal from within your Lit components.

Let’s dive into a few examples...

Example 1: A Shared Counter

Here’s a simple example of a shared counter using @lit-labs/signals. To enable signal-based reactivity in this component, we just use the SignalWatcher mixin in our Custom Element definition; any signals we read from will automatically be observed, triggering updates whenever their values change:

import {LitElement, html} from 'lit';
import {customElement} from 'lit/decorators.js';
import {SignalWatcher, signal} from '@lit-labs/signals';

// This is a standard TC39 signal that uses the signals polyfill.
// The signal is shared across all component instances.
const count = signal(0);

@customElement('shared-counter')
export class SharedCounterComponent extends SignalWatcher(LitElement) {
  render() {
    // Just by using the signal in your template, your component will update
    // when the signal changes.
    return html`
      <p>The count is ${count.get()}</p>
      <button @click=${this.increment}>Increment</button>
    `;
  }

  increment() {
    count.set(count.get() + 1);
  }
}

With this approach, any number of <shared-counter> components can be added to the DOM, and all will reflect the same counter value, automatically updating when the signal changes.

You can also see this example in the Lit Playground.

Example 2: Pinpoint DOM Updates

Using the watch directive, we can also achieve pinpoint updates targeting individual bindings rather than an entire component:

import {LitElement, html} from 'lit';
import {customElement} from 'lit/decorators.js';
import {SignalWatcher, watch, signal} from '@lit-labs/signals';

const count = signal(0);

@customElement('pinpoint-counter')
export class PinpointCounter extends SignalWatcher(LitElement) {
  render() {
    return html`
      <p>The count is ${watch(count)}</p>
      <button @click=${this.increment}>Increment</button>
    `;
  }

  increment() {
    count.set(count.get() + 1);
  }
}

Here, only the binding displaying the count is processed when the signal changes, skipping unnecessary work and improving performance.

Future Work

This is just the beginning of our exploration of signals integration for Lit. Coming soon, we will add more utilities to @lit-labs/signals for incrementally rendering changes from collections, easily running side-effects in components, and using signals for reactive properties.

Eventually—as the proposed standard progresses and we gain experience using signals in Lit—signals will likely become part of the core library.

The Lit team is working closely with the TC39 Signals Proposal champions to ensure that signals work great for Lit, web components, and plain-DOM use cases. We can't overstate how much potential we see in signals to form an interoperable reactivity primitive that works across libraries and components without requiring a centralized framework.

Try It Out and Give Feedback

We’re eager to get feedback from the community as you experiment with this new package. As part of the Lit Labs family, @lit-labs/signals is still experimental and may undergo significant changes based on user feedback and advancements in the TC39 Signals Proposal.

To get started, simply install the package:

npm i @lit-labs/signals

We’d love to hear your thoughts, so please try it out, and let us know how it works for you.

Preliminary docs are available at lit.dev/docs/data/signals/
You can share feedback on the GitHub feedback discussion
Report issues in the Lit monorepo issues
Join us on our Discord server to chat!

We’re excited to see what you’ll build with signals and how they will shape the future of state management in web applications!

Thanks!

-The Lit Team

Lit is Joining the OpenJS Foundation!

2025-10-14T00:00:00Z

Announcing Lit's admission to the OpenJS Foundation as an Impact Project

This morning at JSConf, the OpenJS Foundation announced that Lit is officially joining as an Impact Project! We are incredibly excited to share this news with you. After a long journey working through the necessary administrative and legal processes, Lit is moving from a solely Google-owned project to a new home with the OpenJS Foundation, under a truly open governance model.

This is a huge milestone for Lit, and it's something we've been working towards for a long time. Joining the OpenJS Foundation as an Impact Project places Lit alongside other critical projects in the JavaScript ecosystem like Node.js, Electron, and Webpack. It's a recognition of the project's maturity, stability, and importance to the web platform.

A New Era of Open Governance

This move is a continuation of Lit's evolution from a single-vendor project into a true community-driven one. Already, all project planning, design discussions, and roadmap decisions have been happening in public, with no Google-only documents or private conversations. Major technical changes are proposed and decided on via a formal RFC process, and open engineering meetings are held bi-weekly.

Now, as part of this move, all of Lit's assets, including code, documentation, websites, and the Lit brand, are being transferred to the OpenJS Foundation. This ensures that the project's future is no longer tied to a single company. The stability and longevity of Lit will now be supported by a neutral, non-profit foundation dedicated to the health of the open-source JavaScript ecosystem.

To govern the project, we are establishing a Technical Steering Committee (TSC). The founding members of the TSC include representatives that work at Google, Adobe, and Reddit, as well as long-time independent project leaders who have been instrumental to Lit's success. This structure gives critical users of Lit a real stake and a voice in the technical direction and management of the project.

The initial TSC members will include the following:

Justin Fagnani (Independent)
Steve Orvell (Independent)
Jim Simon (Reddit)
Gray Norton (Adobe)
Kevin Schaaf (Google)
Peter Burns (Google)

Why This Matters

We believe this move will be incredibly positive for the Lit community. It reflects the already community-driven nature of the project, but makes it more formal and sustainable. In the past, we’ve heard that some potential contributors were hesitant to get involved with a project that was solely owned by Google. We hope that being a part of the OpenJS Foundation will open the doors to more contributors and collaborators. We're committed to cultivating a vibrant and welcoming community, and this is a major step in that direction.

Building a Strong Community

Lit is already the most popular library for authoring web components, and the fifth-most downloaded web framework or web component library on npm, right behind Angular. It's used in a massive number of critical, high-impact projects, from complex web applications to high-traffic websites and cross-framework component sets.

Just a few examples include Adobe Photoshop and Illustrator for Web, Reddit, MDN, The Internet Archive, Chrome DevTools and settings UI, Firefox's browser UI, The Microsoft Store, Home Assistant, Web Awesome, and tens of thousands of components at Google across YouTube, Waymo, Google Maps Platform, Labs, web.dev, Colab, Gerrit, and many more projects.

A big focus of the project for the last few years, and even more so now that we're in an independent foundation, is to grow this incredible user community into a stronger contributor community, with true community ownership. Creating a vendor-neutral TSC is just one more step on this path. We'll continue to welcome new contributors with more events, documentation, open meetings, and clear workflows; and invite more critical stakeholders to have official representation on our leadership teams. Soon, we'll be putting out a call for our first Lit community manager. Stay tuned!

We're especially excited to be part of the OpenJS Foundation's commitment to growing and maintaining critical JavaScript projects like Node.js, Express, Webpack, and Electron, and we share their mission of enabling an open and accessible web. The OpenJS Foundation is providing the Lit project guidance on formal, open governance, project support, community building, and more, and as an Impact Project, Lit will participate in the OpenJS Foundation's Cross Product Council (CPC).

Advancing the Web Platform

Lit was created in order to help make web standards like web components easier to use. The Lit team has always been deeply involved in the web standards process, working with browser vendors, prominent web standards bodies, and the Web Components Community Group to advance the web platform. Recently, we’ve seen some huge wins, including scoped custom element registries shipping in Safari, CSS module scripts landing in Firefox, composed selection hitting baseline 2025, and the cross-scope ARIA references specification being finalized.

While we've always strived to be a distinct voice from Chrome in standards discussions, being an OpenJS Foundation project makes that distinction even clearer. Now, with a diverse TSC, we can bring even more perspectives to the table and continue to push the web forward for everyone.

This is an incredibly exciting new chapter for Lit. OpenJS is a wonderful host for us, as our missions to advance the web and JavaScript align so well. We can't wait to see what more we all build together. Thank you to everyone who has been a part of our evolution so far. The future of Lit is bright, and it's a future we'll all build together.

Get involved

We invite everyone to become part of Lit's developer and user community. Whether you simply use Lit for your projects or are interested in contributing code, documentation, outreach, feedback, or good vibes, there is a way to get involved.

You can find more about the project at lit.dev and by joining our Discord server at https://lit.dev/discord/. All community members are invited to our engineering meetings that occur every other Thursday, posted on the calender here. It's a great way to connect with the project and learn how to get involved.