lit / lit/lit.dev

Guidelines on when (not) to imperatively update DOM

Open
#857 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
142
Forks
230
PR merge metrics
No merged PRs in 30d

Description

The question came up 2x today in Lit&Friends slack: When is it ok to update lit-managed DOM imperatively?

Like, this is ok:
```js
#charts = new SomeCleverDomCharts();
firstUpdated() {
this.#shadowContainer = this.renderRoot.querySelector('.container');
this.#charts.mount(this.#shadowContainer);
}
```
because lit won't be updating `#shadowContainer`'s child tree

but in a case like:

```js
render() { return html`

` }
updated(changed) {
if (changed.has('expanded') {
this.#shadowContainer.classList.toggle('expanded', this.expanded);
}
}
```
That's ok *only* if lit will *never* update the class, right?
or we could say the same with an svg use case:
```js
render() {
return html`

`;
}
```

-----

So it would be nice to have a page to point to with instructions on *what* will lead to breakage (updating DOM that's already managed) and what's perhaps a matter of "best practice" (preferring to do it in the template)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the imperative DOM and SVG examples in the issue, then identify the documentation page or entry point where guidance on Lit-managed DOM belongs. Define the page around when imperative updates are safe, what causes breakage, and when template updates are preferred; it is done when these cases are explained clearly with the issue's examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.