Lit

https://lit.dev/docs
Admin
Lit is a simple library for building fast, lightweight web components. It provides a declarative way...
Tokens:96,436
Snippets:959
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Part constructor

Source: https://lit.dev/docs/api/custom-directives

Creates a new Part instance.

```APIDOC
## Part

### Constructor

#### new Part(_partInfo: PartInfo): Part

##### Parameters
- **partInfo** (`PartInfo`) - The part information.

### Methods

#### render(props: Array<unknown>): unknown
Renders the part with the given props.

##### Parameters
- **props** (`Array<unknown>`) - The props to render.

#### update(_part: Part, props: Array<unknown>): unknown
Updates the part with the given props.

##### Parameters
- **_part** (`Part`) - The part to update.
- **props** (`Array<unknown>`) - The props to update with.
```

--------------------------------

### updated

Source: https://lit.dev/docs/api/ReactiveElement

Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

```APIDOC
## ReactiveElement.updated

### Description
Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

### Method
updated

### Parameters
- **_changedProperties** (`Map<PropertyKey, unknown> | PropertyValueMap<any>`) - Map of changed properties with old values

### Details
Setting properties inside this method will trigger the element to update again after this update cycle completes.

### Returns
void
```

--------------------------------

### static shadowRootOptions: ShadowRootInit

Source: https://lit.dev/docs/api/LitElement

Options used when calling `attachShadow`. Set this property to customize the options for the shadowRoot; for example, to create a closed shadowRoot: `{mode: 'closed'}`. These options are used in `createRenderRoot`.

```APIDOC
## static shadowRootOptions: ShadowRootInit

### Description
Options used when calling `attachShadow`. Set this property to customize the options for the shadowRoot; for example, to create a closed shadowRoot: `{mode: 'closed'}`.

### Details
Note, these options are used in `createRenderRoot`. If this method is customized, options should be respected if possible.

### Property
`shadowRootOptions`

### Type
`ShadowRootInit`

### Access
Static
```

--------------------------------

### ReactiveControllerHost

Source: https://lit.dev/docs/api/controllers

Documentation for the ReactiveControllerHost interface, including its properties and methods.

```APIDOC
## ReactiveControllerHost

### Description
An object that can host Reactive Controllers and call their lifecycle callbacks. It provides methods to add/remove controllers and request updates.

### Properties

#### readonly updateComplete: Promise<boolean>
Returns a Promise that resolves when the host has completed updating. The Promise value is `true` if the element completed the update without triggering another update, `false` if a property was set inside `updated()`, and rejected if an exception was thrown during the update.

### Methods

#### addController(controller): void
Adds a controller to the host, which sets up the controller's lifecycle methods to be called with the host's lifecycle.

##### Parameters
- **controller** (`ReactiveController`) - The controller to add.

#### removeController(controller): void
Removes a controller from the host.

##### Parameters
- **controller** (`ReactiveController`) - The controller to remove.

#### requestUpdate(): void
Requests a host update which is processed asynchronously. The update can be waited on via the `updateComplete` property.
```

--------------------------------

### RenderOptions

Source: https://lit.dev/docs/api/LitElement

Documentation for the RenderOptions type.

```APIDOC
## RenderOptions

### Description
Object specifying options for controlling lit-html rendering. Note that while `render` may be called multiple times on the same `container` (and `renderBefore` reference node) to efficiently update the rendered content, only the options passed in during the first render are respected during the lifetime of renders to that unique `container` + `renderBefore` combination.

### Properties
- **creationScope?** (`{importNode: (node: Node, deep?: boolean) => Node}`) - Optional - Node used for cloning the template (`importNode` will be called on this node). This controls the `ownerDocument` of the rendered DOM, along with any inherited context. Defaults to the global `document`.
- **host?** (`object`) - Optional - An object to use as the `this` value for event listeners. It's often useful to set this to the host component rendering a template.
- **isConnected?** (`boolean`) - Optional - The initial connected state for the top-level part being rendered. If no `isConnected` option is set, `AsyncDirective`s will be connected by default. Set to `false` if the initial render occurs in a disconnected tree and `AsyncDirective`s should see `isConnected === false` for their initial render. The `part.setConnected()` method must be used subsequent to initial render to change the connected state of the part.
- **renderBefore?** (`null | ChildNode`) - Optional - A reference node before which the rendered content will be inserted.

```

--------------------------------

### createContext()

Source: https://lit.dev/docs/data/context

Creates a typed Context object. Contexts are compared with strict equality. Use a key that is equal under strict equality (e.g., a string or `Symbol.for()`) to refer to the same context, or a unique key (e.g., a `Symbol()` or object) to guarantee no collision.

```APIDOC
## `createContext()`

### Description
Creates a typed Context object. Contexts are compared with strict equality. Use a key that is equal under strict equality (e.g., a string or `Symbol.for()`) to refer to the same context, or a unique key (e.g., a `Symbol()` or object) to guarantee no collision.

### Signature
```ts
createContext<ValueType>(key: unknown): Context<ValueType>
```

### Parameters
- **key** (`unknown`) - Required - The key used to identify the context. Must be unique under strict equality.

### Returns
- **Context<ValueType>** - A typed Context object. The `ValueType` type parameter is the type of value that can be provided by this context.

### Example
```ts
// Using a string key (same context)
const ctx1 = createContext<string>('my-context');
const ctx2 = createContext<string>('my-context');

// Using a Symbol key (unique context)
const ctx3 = createContext<number>(Symbol('unique'));
```
```

--------------------------------

### ElementPart constructor

Source: https://lit.dev/docs/api/custom-directives

Creates a new ElementPart instance.

```APIDOC
## ElementPart

### Constructor

#### new ElementPart(element: Element, parent: Disconnectable, options: undefined | RenderOptions): ElementPart

##### Parameters
- **element** (`Element`) - The element.
- **parent** (`Disconnectable`) - The parent disconnectable.
- **options** (`undefined | RenderOptions`) - The render options.

### Properties

- **element**: `Element` - The element.
- **options**: `undefined | RenderOptions` - The render options.
- **readonly type**: `6` - The type of the part.
```

--------------------------------

### @provide()

Source: https://lit.dev/docs/data/context

A property decorator that adds a ContextProvider controller to the component, making it respond to any `context-request` events from its children consumers.

```APIDOC
## `@provide()`

### Description
A property decorator that adds a ContextProvider controller to the component, making it respond to any `context-request` events from its children consumers.

### Usage
```ts
@provide({context: MyContext})
value = ...;
```

### Parameters
- **options** (object) - Required - Configuration for the provider.
  - `context` (Context) - Required - The context to provide.
```

--------------------------------

### createComponent()

Source: https://lit.dev/docs/frameworks/react

Documentation for the createComponent() function from @lit/react, which creates a React wrapper component for custom elements.

```APIDOC
## createComponent()

### Description
Creates a React component wrapper for a custom element class. The wrapper passes React props to properties accepted by the custom element and listens for events dispatched by the custom element.

### Method
createComponent

### Parameters
#### Options Object
- **tagName** (string) - Required - The custom element's tag name.
- **elementClass** (CustomElementClass) - Required - The custom element class.
- **react** (React object) - Required - The imported React object, used to create the wrapper component. Can also be an import of preact-compat.
- **events** (object) - Optional - An object that maps an event handler prop to an event name fired by the custom element.

### Usage Example
```jsx
import React from 'react';
import { createComponent } from '@lit/react';
import { MyElement } from './my-element.js';

export const MyComponent = createComponent({
  tagName: 'my-element',
  elementClass: MyElement,
  react: React,
  events: {
    onactivate: 'activate',
    onchange: 'change',
  },
});
```

### Events Option
- The `events` option maps React prop names to event names. When a callback prop with one of the event prop names is passed, the wrapper adds it as an event handler for the corresponding event.
- Recommended convention: prefix event names with `on` (e.g., `onfoo` for event `foo`).
- In TypeScript, cast the event name to `EventName<MyEvent>` to provide accurate event types.

### Slots
- Children of the component render to the default slot of the custom element.
- To render to a named slot, add the standard `slot` attribute to a wrapper element.
- If a wrapper element interferes with styling, give it `display: contents;` to remove the container from rendering.

### How It Works
- During render, the wrapper receives props from React and changes behavior based on the options and custom element class:
  - If a prop name is a property on the custom element (determined with an `in` check), the wrapper sets that property on the element to the prop value.
  - If a prop name is an event name passed to the `events` option, the prop value is passed to `addEventListener()` with the event name.
  - Otherwise, the prop is passed to React's `createElement()` to be rendered as an attribute.
- Properties and events are added in `componentDidMount()` and `componentDidUpdate()` callbacks.

### TypeScript Event Typing
```ts
import { EventName } from '@lit/react';

const MyComponent = createComponent({
  tagName: 'my-element',
  elementClass: MyElement,
  react: React,
  events: {
    onMyEvent: 'my-event' as EventName<MyEvent>,
  },
});
```
```

--------------------------------

### constructor()

Source: https://lit.dev/docs/templates/custom-directives

Called when Lit constructs an instance of the directive class for the first time. Receives a PartInfo object with metadata about the expression.

```APIDOC
## constructor()

### Description
Called when Lit encounters a DirectiveResult in an expression for the first time. The constructor receives a single PartInfo object providing metadata about the expression.

### Method
constructor

### Parameters
- **partInfo** (PartInfo) - Required - Metadata about the expression the directive was used in.

### Notes
- The constructor is used for one-time initialization.
- As long as the same directive function is used in the same expression each render, the previous instance is reused.
- Can be used for error checking to limit the directive to specific expression types.
```

--------------------------------

### new LiveDirective(partInfo)

Source: https://lit.dev/docs/api/directives

Constructor for the LiveDirective class. It initializes a new instance with the provided PartInfo.

```APIDOC
## new LiveDirective(partInfo)

### Description
Constructor for the LiveDirective class. It initializes a new instance with the provided PartInfo.

### Parameters
- **partInfo** (`PartInfo`) - The part information for the directive.

### Returns
- `LiveDirective` - A new instance of LiveDirective.
```

--------------------------------

### ReactiveController

Source: https://lit.dev/docs/api/controllers

Documentation for the ReactiveController interface, including its lifecycle callback methods.

```APIDOC
## ReactiveController

### Description
A Reactive Controller is an object that enables sub-component code organization and reuse by aggregating the state, behavior, and lifecycle hooks related to a single feature. Controllers are added to a host component via the `addController()` method and can hook into the host's lifecycle.

### Methods

#### hostConnected(): void
Called when the host is connected to the component tree. For custom element hosts, this corresponds to the `connectedCallback()` lifecycle.

#### hostDisconnected(): void
Called when the host is disconnected from the component tree. For custom element hosts, this corresponds to the `disconnectedCallback()` lifecycle.

#### hostUpdate(): void
Called during the client-side host update, just before the host calls its own update. Code in `update()` can depend on the DOM as it is not called in server-side rendering.

#### hostUpdated(): void
Called after a host update, just before the host calls `firstUpdated` and `updated`. It is not called in server-side rendering.
```

--------------------------------

### Keyed

Source: https://lit.dev/docs/api/directives

Base class for creating custom directives. Users should extend this class, implement `render` and/or `update`, and then pass their subclass to `directive`.

```APIDOC
## Keyed

### Description
Base class for creating custom directives. Users should extend this class, implement `render` and/or `update`, and then pass their subclass to `directive`.

### Constructor
#### new Keyed(_partInfo): Keyed

### Parameters
- **_partInfo** (`PartInfo`) - The part information.

### Methods
#### render(_value, f): unknown

##### Parameters
- **_value** (`unknown`) - The value to render.
- **f** (`() => unknown`) - A function that returns the unknown value.

#### update(_part, __namedParameters): unknown

##### Parameters
- **_part** (`Part`) - The part to update.
- **__namedParameters** (`[_value, f]`) - An array containing the value and function.
```

--------------------------------

### EventPart constructor

Source: https://lit.dev/docs/api/custom-directives

Creates a new EventPart instance.

```APIDOC
## EventPart

### Constructor

#### new EventPart(element: Element, name: string, strings: ReadonlyArray<string>, parent: Disconnectable, options: undefined | RenderOptions): EventPart

##### Parameters
- **element** (`Element`) - The element.
- **name** (`string`) - The event name.
- **strings** (`ReadonlyArray<string>`) - The static strings of the interpolation.
- **parent** (`Disconnectable`) - The parent disconnectable.
- **options** (`undefined | RenderOptions`) - The render options.

### Properties

- **readonly element**: `Element` - The element.
- **readonly name**: `string` - The event name.
- **readonly options**: `undefined | RenderOptions` - The render options.
- **readonly strings?**: `ReadonlyArray<string>` - If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.
- **readonly type**: `5` - The type of the part.
```

--------------------------------

### static styles

Source: https://lit.dev/docs/api/ReactiveElement

Static property for user-supplied styles.

```APIDOC
## static styles

### Description
Static property for user-supplied styles. The type is CSSResultGroup.

### Property
static styles?: CSSResultGroup

```

--------------------------------

### new ChildPart(startNode, endNode, parent, options): ChildPart

Source: https://lit.dev/docs/api/custom-directives

Creates a new ChildPart instance. This part handles child node bindings in lit-html templates.

```APIDOC
## [CONSTRUCTOR] new ChildPart(startNode, endNode, parent, options): ChildPart

### Description
Creates a new ChildPart instance. This part handles child node bindings in lit-html templates.

### Parameters
- **startNode** (`ChildNode`) - The start node of the part.
- **endNode** (`null | ChildNode`) - The end node of the part, or null.
- **parent** (`undefined | ChildPart | TemplateInstance`) - The parent part or template instance.
- **options** (`undefined | RenderOptions`) - Render options.

### Properties
- **options** (readonly) - Render options.
- **type** (readonly) - Always 2.
- **endNode** (readonly) - The end node of the part, or null.
```

--------------------------------

### choose

Source: https://lit.dev/docs/api/directives

Chooses and evaluates a template function from a list based on matching the given value to a case. Cases are structured as [caseValue, func] and matched by strict equality.

```APIDOC
## choose

### Description
Chooses and evaluates a template function from a list based on matching the given `value` to a case. Cases are structured as `[caseValue, func]`. `value` is matched to `caseValue` by strict equality. The first match is selected. Case values can be of any type including primitives, objects, and symbols. This is similar to a switch statement, but as an expression and without fallthrough.

### Signature
`choose(value, cases, defaultCase?): undefined | V`

### Parameters
- `value` (T) - Required - The value to match against case values.
- `cases` (Array<[T, () => V]>) - Required - An array of tuples where each tuple contains a case value and a function that returns the template result.
- `defaultCase` (() => V) - Optional - A function that returns the default template result if no case matches.
```

--------------------------------

### ContextProvider

Source: https://lit.dev/docs/data/context

A ReactiveController which adds context provider behavior to a custom element by listening to `context-request` events.

```APIDOC
## `ContextProvider`

### Description
A ReactiveController which adds context provider behavior to a custom element by listening to `context-request` events.

### Constructor
```ts
new ContextProvider(host: ReactiveElement, options: ContextProviderOptions<T>)
```

### Members
- `setValue(v: T, force = false): void` - Sets the value provided, and notifies any subscribed consumers of the new value if the value changed. `force` causes a notification even if the value didn't change, which can be useful if an object had a deep property change.
```

--------------------------------

### static getPropertyOptions(name)

Source: https://lit.dev/docs/api/LitElement

Returns the property options associated with the given property. These options are defined with a `PropertyDeclaration` via the `properties` object or the `@property` decorator and are registered in `createProperty(...)`.

```APIDOC
## static getPropertyOptions(name)

### Description
Returns the property options associated with the given property. These options are defined with a `PropertyDeclaration` via the `properties` object or the `@property` decorator and are registered in `createProperty(...)`.

### Method
static getPropertyOptions

### Parameters
- **name** (`PropertyKey`) - Required - The name of the property.

### Details
Note, this method should be considered "final" and not overridden. To customize the options for a given property, override `createProperty`.
```

--------------------------------

### connectedCallback(): void

Source: https://lit.dev/docs/api/ReactiveElement

Lifecycle callback called when the element is connected to the DOM. Sets up rendering and updating.

```APIDOC
## connectedCallback(): void

### Description
On first connection, creates the element's renderRoot, sets up element styling, and enables updating.

```

--------------------------------

### render

Source: https://lit.dev/docs/api/templates

Renders a value to a DOM container.

```APIDOC
## render

### Description
Renders a value, usually a lit-html TemplateResult, to the container.

### Signature
`render(value, container, options?): RootPart`

### Parameters
- **value** (`unknown`) - Required - Any renderable value, typically a TemplateResult created by evaluating a template tag like `html` or `svg`.
- **container** (` | `) - Required - A DOM container to render to. The first render will append the rendered value to the container, and subsequent renders will efficiently update the rendered value if the same result type was previously rendered there.
- **options** (`RenderOptions`) - Optional - See RenderOptions for options documentation.

### Details
This example renders the text "Hello, Zoe!" inside a paragraph tag, appending it to the container `document.body`.
```

--------------------------------

### asyncAppend

Source: https://lit.dev/docs/api/directives

Documentation for the asyncAppend directive, which renders items from an async iterable.

```APIDOC
## asyncAppend

### Description
A directive that renders the items of an async iterable, appending new values after previous values, similar to the built-in support for iterables. This directive is usable only in child expressions.

### Signature
`asyncAppend(value, _mapper?): DirectiveResult<AsyncAppendDirective>`

### Parameters
- **value** (`AsyncIterable<unknown>`) - Required - An async iterable.
- **_mapper?** (`(v: unknown, index?: number) => unknown`) - Optional - A mapper function.

### Details
Async iterables are objects with a [Symbol.asyncIterator] method, which returns an iterator whose `next()` method returns a Promise. When a new value is available, the Promise resolves and the value is appended to the Part controlled by the directive. If another value other than this directive has been set on the Part, the iterable will no longer be listened to and new values won't be written to the Part.
```

--------------------------------

### queryAll

Source: https://lit.dev/docs/api/decorators

A property decorator that converts a class property into a getter that executes a querySelectorAll on the element's renderRoot.

```APIDOC
## queryAll

### Description
A property decorator that converts a class property into a getter that executes a querySelectorAll on the element's renderRoot.

### Signature
`queryAll(selector): (protoOrDescriptor: ReactiveElement | ClassElement, name?: PropertyKey) => any`

### Parameters
- **selector** (`string`) - Required - A DOMString containing one or more selectors to match.
```
Tokens:
Raw