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/experimental-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!