render() method option „clearContainer“

[samuelecalamita]

Should this be an RFC?

• This is not a substantial change

Which package is this a feature request for?

Lit Core (lit / lit-html / lit-element / reactive-element)

Description

I would like to propose a feature enhancement for the lit-html library that introduces a new option, 'clearContainer,' for the render method. This option would streamline the process of clearing initial server-rendered skeleton markup during the first render, offering a more elegant and efficient solution.

Feature Request:
I propose introducing a 'clearContainer' option within the render method to streamline the process of clearing the target container, specifically on the first render. When 'clearContainer' is set to true, lit-html would automatically clear the container before rendering, offering a more concise and intuitive solution:

export class myComponent extends HTMLElement {
  renderComponent() {
    // Render using lit-html with clearContainer option
    render(myTemplate, this, { clearContainer: true });
  }
}

Benefits:

1. Simplified Code: The 'clearContainer' option simplifies the code by removing the need for manual conditional checks and DOM manipulations.
2. Improved Readability: Developers can easily understand the intention of clearing the container, resulting in cleaner and more maintainable code.
3. Ease of Use: The 'clearContainer' option offers a convenient way to handle initial cleanup without extra steps.

I believe that this feature addition would be a valuable improvement for lit-html users who frequently encounter scenarios involving server-rendered skeleton markup. It enhances the library's ease of use, consistency, and code readability while simplifying the handling of initial content cleanup.

I am enthusiastic about collaborating with the lit-html community and maintainers to discuss and refine this feature request further. Your feedback and insights are highly appreciated.

Alternatives and Workarounds

When transitioning from server-side rendering (SSR) to client-side rendering (CSR), it is common to encounter scenarios where server-generated skeleton markup needs to be removed from the target container before rendering the actual content. The current approach, as exemplified below, is functional but can be further improved for simplicity and readability:

export class myComponent extends HTMLElement {
  initialContentCleared = false;

  renderComponent() {
    if (this.initialContentCleared === false) {
      this.innerHTML = "";
      this.initialContentCleared = true;
    }
    // Render using lit-html
    render(myTemplate, this);
  }
}

[samuelecalamita]

@justinfagnani any thoughts about this enhancement?

[rictic]

I'm not sure if this is worth it to go into lit-html. It's a rare option, and it's easy for the caller to handle, as you demonstrate with your five line initialContentCleared solution.

One recomendation: instead of this.innerHTML = '' you could instead write: this.replaceChildren() and it will likely be a bit more efficient and not trip any content security policies.

[samuelecalamita]

@rictic I understand your perspective, and I appreciate your feedback. While the initialContentCleared workaround is functional, I believe that introducing the 'clearContainer' option could significantly enhance the user experience and simplify the code for developers who frequently encounter scenarios like this.

It's true that it may not be a widely used feature, but it could provide valuable convenience and readability improvements for those who do need it. This option can help maintain a cleaner and more concise codebase, making the library even more user-friendly.

It might not be an essential addition, but it could make a difference for some users. I believe that even a relatively rare option can have its place if it enhances the library's overall usability.

I'm open to further discussion and collaboration to refine this feature request and address any concerns. Thank you for considering the proposal.

[rictic]

I appreciate that! Philosophically, our aim is for lit-html to be as small as possible while still enabling powerful, fast, and secure templates. Every additional feature has a size and runtime cost, and while this would be small, given that it's easy for the caller to do outside of the render method I think that's the better place for it.