lit/lit.dev

The Lit website

Simple. Fast. Web Components.

Lit is a simple library for building fast, lightweight web components.

At Lit's core is a boilerplate-killing component base class that provides reactive state, scoped styles, and a declarative template system that's tiny, fast and expressive.

Documentation

See the full documentation for Lit at lit.dev.

Additional documentation for developers looking to contribute or understand more about the project can be found in dev-docs.

npm

To install from npm:

npm i lit

Lit Monorepo

This is the monorepo for Lit packages.

lit 2.x source is available on the 2.x branch. lit-html 1.x source is available on the lit-html-1.x branch.

Packages

• Core packages
  • lit - The primary user-facing package of Lit which includes everything from lit-html and lit-element.
  • lit-element - The web component base class used in Lit.
  • lit-html - The rendering library used by LitElement.
  • @lit/reactive-element - A low level base class that provides a reactive lifecycle based on attribute/property changes.
• Additional libraries
  • @lit/localize - A library and command-line tool for localizing web applications built using Lit.
  • @lit/localize-tools - Localization tooling for use with @lit/localize.
  • @lit/react - A React component wrapper for web components.
  • @lit/task - A controller for Lit that renders asynchronous tasks.
  • @lit/context - A system for passing data through a tree of elements using browser events, avoiding the need to pass properties down every layer of the tree using a community defined protocol.
• Labs
  • @lit-labs/ssr - A server package for rendering Lit templates and components on the server.
  • @lit-labs/ssr-client - A set of client-side support modules for rendering Lit components and templates on the server using @lit-labs/ssr.
  • @lit-labs/eleventy-plugin-lit - A plugin for Eleventy that pre-renders Lit components using @lit-labs/ssr with optional hydration.
  • @lit-labs/ssr-react - A package for integrating Lit SSR with React and React frameworks.
  • @lit-labs/nextjs - A plugin for Next.js that enables deep server rendering of Lit components with Lit SSR.
  • @lit-labs/router - A router for Lit.
  • @lit-labs/motion - Lit directives for making things move
  • @lit-labs/scoped-registry-mixin - A mixin for LitElement that integrates with the speculative Scoped CustomElementRegistry polyfill.
  • @lit-labs/observers - A set of reactive controllers that facilitate using the platform observer objects.
  • @lit-labs/preact-signals - Preact Signals integration for Lit.
  • @lit-labs/testing - Utilities for testing Lit components.
  • @lit-labs/virtualizer - Viewport-based virtualization (including virtual scrolling).
  • @lit-labs/compiler - A compiler for optimizing Lit templates.
• Starter kits (not published to npm)
  • lit-starter-ts (template repo) - A starter repo for building reusable components using Lit in TypeScript.
  • lit-starter-js (template repo) - A starter repo for building reusable components using Lit in JavaScript.
• Internal packages (not published to npm)
  • tests - Test infrastructure for the monorepo.
  • benchmarks - Benchmarks for testing various libraries in the monorepo.
  • @lit-internal/scripts - Utility scripts used within the monorepo.

Contributing to Lit

Lit is open source and we appreciate issue reports and pull requests. See CONTRIBUTING.md for more information.

Setting up the lit monorepo for development

Initialize repo:

git clone https://github.com/lit/lit.git
cd lit
npm ci

Build all packages:

npm run build

Test all packages:

npm run test

Run benchmarks for all packages:

npm run benchmarks

See individual package READMEs for details on developing for a specific package.

lit.dev's Issues

[lit-html] Find a new home for how-it-works deep dives

Remove concepts doc for now

Maybe add to a new how-it-works section, combined with content from the wiki as well as LitElement content.

https://github.com/Polymer/lit-html/wiki/How-it-Works

Alert styles missing

When I was demoing the site today, I realized the alert styles were missing.

It looks like they got dropped as part of one of the big clean-ups:

https://github.com/PolymerLabs/lit.dev/pull/37/files#diff-3b9e86ecc61632ab075bd985e7366ae7f4c151634f65e5e0c100a03383661cb4L288

If that link doesn't work right... Starting on L288 of main.css in that PR, you can see the deleted styles. We need to put these back--not sure if they should go in main.css or guide.css, though. (We use them in both the guides and the tutorial typically, if that helps--although I'm not sure whether that will make sense with the new tutorial format.

Don't add links for directories in guides structure

To match our current outline, I'd like to omit link for the directories themselves.

I did this by replacing the index.md in a given directory with a stub that contains only metadata, and rewriting the nav template like this:

      <side-nav>
        {%- set navSections = collections.guide | eleventyNavigation -%}
        {# Uncomment to use prebuilt nav
        {{ navSections | eleventyNavigationToHtml | safe }}
        #}
        <ul>
        {%- for entry in navSections %}
          <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
            {%- if entry.children | length %}
              <span class="sectionHead">{{ entry.title }}</span>
              {% set navPages = entry.children %}
              <ul>
              {%- for entry in navPages %}
                <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
                  <a href="{{ entry.url | url }}">{{ entry.title }}</a>
                </li>
              {%- endfor %}
              </ul>  
            {%- else %}
              <a href="{{ entry.url | url }}">{{ entry.title }}</a>
            {%- endif %}
          </li>
        {%- endfor %}
        </ul>
      </side-nav>

Not sure if there's a simpler way to do this.

lit.dev docs for lit-localize

Components-- Shadow DOM-- Edit for Consistency

[docs] Add example documentation for `unsafeCss` attack vectors

Some documentation about what common security issues to be aware of, would be a nice addition

Originally posted by @kenchris in lit/lit-element#474 (comment)

[docs] Provide a way for local users to do the Try LitElement tutorial

Currently, the Try LitElement tutorial is only available as StackBlitz examples.

Provide a way for people to do the tutorial and work locally. E.g. put the Try samples on GitHub and provide instructions for doing the tutorial with Polymer CLI

Introduction--Lit-- Contents

This is placeholder content, need to decide what exactly we want to say here.

Playground eleventy shortcodes pre-render preview result

Related libraries—Finish Standalone lit-html section

• Add intro, explaining that lit-html can be used independently of web components or LitElement to render DOM anywhere in the page.

• Fill in missing content. In particular, probably restructure a bit to clarify where the context comes from when using lit-html standalone, and how the examples differ from the LitElement based examples.

• Edit & clean up.

Choose canonical path for docs

By default eleventy adds a slash after filenames, but allows users to access the path without the slash. This results in relative URLs failing in some cases.

We need to pick a scheme and possibly add a redirect handler to rewrite the non-canonical form.

I prefer not adding the slash, because it's easier to write hrefs correctly when they match the file system. (When adding the slash, a sibling link from guides/foo to guides/bar needs to be written as ../bar/ instead of just bar.)

[docs] Add language and version to docs URLs

We should be able to preserve docs for each release, and plan for the future with docs in multiple languages. URLs would end up looking like https://polymer.github.io/lit-html/en/1.0/guide or https://polymer.github.io/lit-html/en/latest/guide.

Playground eleventy shortcodes pre-render syntax highlighted code

Alert formatting is missing

We seem to have lost the CSS that formats alerts (aka notes, warnings, "pretty boxes," or asides).

Components-- Reactive Properties -- Edit for Consistency

Improve playground code highlight theme for lit.dev

The default playground theme is a bit drab looking, and doesn't even include colors for a few tokens. Choose a nicer theme for lit.dev, and maybe make it the default playground theme too.

Fix broken docker image build

Inline editable code snippet

Prove out an inline + editable documentation code snippet, where the preview renders below the code.

Document handling rejected `updateComplete` promise

When lit/lit-element#607 is merged, the updateComplete promise will be able to be rejected. We need to add documentation explaining that these exceptions need to be handled in any code that awaits the updateComplete promise. This might go in the promises section of the lifecycle.

[docs] Docs feedback mechanism

Another general design request for post-1.0: I'd like to provide a feedback mechanism. We can easily put one at the bottom of the page, but since some of our pages are quite long, having a "was this page helpful" button at the very end isn't perfect.

Old Polymer site had "Edit on GitHub" buttons, which were nice, but much higher friction, since users had to have a GitHub account, be willing to click through and create a PR, instead of just commenting anonymously.

Options include:

• A sticky footer (see the Sentry docs.
• Something attached to the header.
• A small feedback tab on the side that opens an overlay. I'm not saying this well, but I've seen that implemented somewhere, too.

Information to collect:
Was this page helpful to you? [Yes] {No]
[If no] Comment [ ]
Could also offer "Edit on GitHub" or "Open an Issue" as options.

Playground examples

Add a LHS drawer to the playground page with a gallery of examples (similar to https://svelte.dev/examples, but with the playground + examples combined into one page).

Render all code samples using playground

Components-- Rendering-- Make Samples Runnable

Edit and make sure language is consistent.
Make samples runnable?

Tweak template intro wording

Comments from #14, to handle after larger reorgs are done:

"Since "tag" is used to refer to HTML tags too, do we want to clarify that html is a "template literal tag" the first time we use it? I know that could be a lot of "tagged template literal tagged with the template literal tag" and such... so maybe not a great idea. Maybe there's a way to work the full phrase "tagged template literal" in there. Also thinking if we should emphasize that this is standard plain JS, considering how many other frameworks use some fork of JS.

And should we have a link to MDN on tagged template literals, or would we lose readers to the hyperlink void that way?"

"We don't mention that html is a function prior to this, we just call it a tag, so this could be a bit too much detail on that aspect. Could we say something around a lit-html template being an expression that returns a value that can be stored in variables, passed to and from functions, etc? I think JSX or React docs go into this a bit, for comparison."

"Rather than the specifics of the browser passing things to a tag function, we could describe the end result which is that the html tag captures the template strings and expression values separately, so that on repeated renders is can update only the expressions that changed.

One specific thing I have in mind there is around "re-render only the parts of template that have changed." - depending on our semantics here, the "template" doesn't change, only the values passed to it do. So we could lean more on saying we only update the expressions that change."

Components-- Reactive Properties-- Restructure to place TypeScript/Decorators examples first

Restructure to place TypeScript/decorators examples first, show JavaScript as an option.

Auto deploy on push to master

This has recently broken

Components-- Shadow DOM-- Add interactive examples

Consider migrating to AppEngine

Deploying via cloud build/cloud run seems pretty broken. At the moment, cloud build is timing out with no useful error message, while the local lerna build works fine.

Even when it works, it's slower and less intuitive than working with App Engine.

Introduction-- Getting Started--Edit and review for technical accuracy

Edit for consistency.
Review for technical accuracy, make any updates required for Lit.

[docs] Add a gif of optimal DOM updates

This could be on the home page, introduction, concepts, or all of the above.

Similar to: https://reactjs.org/docs/rendering-elements.html#react-only-updates-whats-necessary

[docs] Lit for Polymer users

Is there any plan to create a component migration guide from PolymerElement to LitElement

Setup second origin for playground

E.g. playground.lit.dev

Add docs for platform-support

Previously LitElement's polyfill support was built in. Now it's opt-in via the platform-support module. Docs should be added for this.

There are platform-support modules in:

• updating-element
• lit-html
• lit-element (includes updating-element and lit-html's platform-support modules)

The idea is that platform-support should be loaded right after loading the webcomponents polyfills.

Introduction-- Why Lit?-- Write Content

Decide if this content goes here or on the main landing page.
Conclusion: probably OK to go here.
Even if it covers similar ground, it'll be in a different form.
Write content.

Auto deploy to private URL on PR

Components-- Reactive properties-- Add Interactive examples

Components-- Shadow DOM-- Update createRenderRoot/etc. section for Lit.

Asynchronous operation cancellation or order

Description

When you rely on an asynchrounous task to complete, if an earlier asynchronous task completes after its next iteration, you get the result of the first task instead of the last.

Steps to Reproduce

1. Use a directive that updates the value in a relatively long time.
2. Update the rendering, making the directive fire again but this time faster.

The same happen if you render something else afterward, your new value is overridden.

Live Reproduction Link

https://stackblitz.com/edit/lit-html-jdv5ml?file=src%2Findex.js

Actual Results

The result from the last directive call show up but shortly after the result from the first directive call show up.

Expected Results

This code obviously miss some order or cancellation management. I do not expect it to work as is.
Should this library support also a conditional rendering at this point ?
A solution would be a pattern to use to fix this behaviour and maybe extend the documentation on Asynchronous Directives

An other solution would be to use a central model such as redux but this would imply a big change to my application that I would better avoid if possible.

Eleventy shortcode for playground

[docs] Add info on automatic XSS-prevention / escaped characters

Description

In this article, it mentions that 'lit-html' includes XSS-prevention. That's what lead me to this library.
https://benfrain.com/html-templating-with-vanilla-javascript-es2015-template-literals/

Naturally, I wanted to verify that before using lit-html so I searched for 'escape' and 'XSS' in the documentation, but I wasn't able to find any mention of that functionality anywhere.

By trial and error, I found out that lit-html automatically removes <script></script> tags when using the html tagged template literal.

I also could not find info about the unsafeHTML directive in the docs although it is included in the source code.

Minimal usability pass

There are some janky things about the site right now in terms of layout and nav. Do a minimal pass through to make things more reasonable.

Add release notes to docs site

Description

• For consistency with lit-html docs.

Acceptance criteria

• Individual pages per-release (for example, /guide/release-notes/2.4.0.html)
• Summary page collecting all release notes. (for example, /guides/release-notes.html) release
• Only document releases going forward; for older releases, we can point to the changelog.

Active page highlighting not set up

Template currently applies .my-active-class to the active link in the left nav. Need to add something to the CSS to highlight it.

Redirect lit-html.com to the lit-html docs site

Initiative / goal

We now have the lit-html.com domain!
It doesn't point anywhere :/

Scope

Figure out DNS settings to redirect to the current docs site

Acceptance criteria and must have scope

Typing lit-html.com into a browser redirects to the current docs site

[docs] "Updates?" in shouldUpdate

I've made several checks with method shouldUpdate, and property changes inside this method do not trigger an element update, but the parameter changedProperties itself of shouldUpdate is updated synchronously in the same element update.

So I think the field "Updates?" of this method in this doc is wrong. It should says:

Updates? | No | Property changes inside this method will not trigger an element update.

Add section on working with other libraries?

Description

An expression in the child position (aka text position) can return a node or iterable of nodes, something that can be used to integrate the output of other libraries into a Lit template. We don't really cover this at the moment.

Acceptance criteria

Section on working with other libraries that describes, at minimum, using child position expressions to inject nodes into the templated DOM.

Redirects

• A way to declare redirects for future document moves
• Fragment redirects somehow?
• Redirects from old site to new site

Fix server out of memory errors

Rumor has it the typescript worker is having some trouble getting served? Need to investigate.

Document Trusted Types support

Users shouldn't need to do much if they know how to enable it, but we should at least list this as a feature.

[lit-html] Docs should describe lit-html change detection explictly

Currently the docs say things like, "When you call render, lit-html only updates the parts of the template that have changed since the last render. This makes lit-html updates very fast."

But they don't say explicitly how this happens. In particular, that lit keeps track of the current value at each binding site (aka "hole in the DOM", aka Part). On render, it compares the new value with the current rendered value, and only re-renders if they're different.

The live() directive is designed to apply different change detection logic (against the live DOM value, instead of the value that lit rendered).