1 | # LitElement
|
2 | A simple base class for creating fast, lightweight web components with [lit-html](https://lit-html.polymer-project.org/).
|
3 |
|
4 | [![Build Status](https://travis-ci.org/Polymer/lit-element.svg?branch=master)](https://travis-ci.org/Polymer/lit-element)
|
5 | [![Published on npm](https://img.shields.io/npm/v/lit-element.svg)](https://www.npmjs.com/package/lit-element)
|
6 | [![Join our Slack](https://img.shields.io/badge/slack-join%20chat-4a154b.svg)](https://www.polymer-project.org/slack-invite)
|
7 | [![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/lit-element)
|
8 | [![Mentioned in Awesome lit-html](https://awesome.re/mentioned-badge.svg)](https://github.com/web-padawan/awesome-lit-html)
|
9 | [![BrowserStack Status](https://automate.browserstack.com/badge.svg?badge_key=TnM4R3dScWdhU1NRck1WejNtMmVoMzQrU2s5bnRtOVVGMmFkQWtEV25iST0tLTNiWEZVYldaV1VqY2oxTEVJV09XSFE9PQ==--e79a2e8601a562e5b200dfcd2d6a15416fd4ed5f)](https://automate.browserstack.com/public-build/TnM4R3dScWdhU1NRck1WejNtMmVoMzQrU2s5bnRtOVVGMmFkQWtEV25iST0tLTNiWEZVYldaV1VqY2oxTEVJV09XSFE9PQ==--e79a2e8601a562e5b200dfcd2d6a15416fd4ed5f)
|
10 |
|
11 | ## Documentation
|
12 |
|
13 | Full documentation is available at [lit-element.polymer-project.org](https://lit-element.polymer-project.org).
|
14 |
|
15 | ## Overview
|
16 |
|
17 | LitElement uses [lit-html](https://lit-html.polymer-project.org/) to render into the
|
18 | element's [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)
|
19 | and adds API to help manage element properties and attributes. LitElement reacts to changes in properties
|
20 | and renders declaratively using `lit-html`. See the [lit-html guide](https://lit-html.polymer-project.org/guide)
|
21 | for additional information on how to create templates for lit-element.
|
22 |
|
23 | ```ts
|
24 | import {LitElement, html, css, customElement, property} from 'lit-element';
|
25 |
|
26 | // This decorator defines the element.
|
27 | @customElement('my-element')
|
28 | export class MyElement extends LitElement {
|
29 |
|
30 | // This decorator creates a property accessor that triggers rendering and
|
31 | // an observed attribute.
|
32 | @property()
|
33 | mood = 'great';
|
34 |
|
35 | static styles = css`
|
36 | span {
|
37 | color: green;
|
38 | }`;
|
39 |
|
40 | // Render element DOM by returning a `lit-html` template.
|
41 | render() {
|
42 | return html`Web Components are <span>${this.mood}</span>!`;
|
43 | }
|
44 |
|
45 | }
|
46 | ```
|
47 |
|
48 | ```html
|
49 | <my-element mood="awesome"></my-element>
|
50 | ```
|
51 |
|
52 | Note, this example uses decorators to create properties. Decorators are a proposed
|
53 | standard currently available in [TypeScript](https://www.typescriptlang.org/) or [Babel](https://babeljs.io/docs/en/babel-plugin-proposal-decorators). LitElement also supports a [vanilla JavaScript method](https://lit-element.polymer-project.org/guide/properties#declare) of declaring reactive properties.
|
54 |
|
55 | ## Examples
|
56 |
|
57 | * Runs in all [supported](#supported-browsers) browsers: [Glitch](https://glitch.com/edit/#!/hello-lit-element?path=index.html)
|
58 |
|
59 | * Runs in browsers with [JavaScript Modules](https://caniuse.com/#search=modules): [Stackblitz](https://stackblitz.com/edit/lit-element-demo?file=src%2Fmy-element.js), [JSFiddle](https://jsfiddle.net/sorvell1/801f9cdu/), [JSBin](http://jsbin.com/vecuyan/edit?html,output),
|
60 | [CodePen](https://codepen.io/sorvell/pen/RYQyoe?editors=1000).
|
61 |
|
62 | * You can also copy [this HTML file](https://gist.githubusercontent.com/sorvell/48f4b7be35c8748e8f6db5c66d36ee29/raw/67346e4e8bc4c81d5a7968d18f0a6a8bc00d792e/index.html) into a local file and run it in any browser that supports [JavaScript Modules]((https://caniuse.com/#search=modules)).
|
63 |
|
64 | ## Installation
|
65 |
|
66 | From inside your project folder, run:
|
67 |
|
68 | ```bash
|
69 | $ npm install lit-element
|
70 | ```
|
71 |
|
72 | To install the web components polyfills needed for older browsers:
|
73 |
|
74 | ```bash
|
75 | $ npm i -D @webcomponents/webcomponentsjs
|
76 | ```
|
77 |
|
78 | ## Supported Browsers
|
79 |
|
80 | The last 2 versions of all modern browsers are supported, including
|
81 | Chrome, Safari, Opera, Firefox, Edge. In addition, Internet Explorer 11 is also supported.
|
82 |
|
83 | Edge and Internet Explorer 11 require the web components polyfills.
|
84 |
|
85 | ## Contributing
|
86 |
|
87 | Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
|