Quick Start#

All HTML tags can be used in Lessjs HTML, but some tags can be replaced with Lessjs components, which are more powerful. For example, the <img> tag can be replaced with the spz-img component.

#Key Takeaways First

• To get a page running fast, focus on three things first: layout, template rendering, and @tap interaction.
• If a component does not render as expected, check layout and sizing first.
• If interaction fails, check both the target id and the action expression (for example, hello.hide).

#Minimal Running Path (3 Steps)

1. Render one spz-img with fixed dimensions to verify layout setup.
2. Render simple data with spz-render + <template> to verify data-to-DOM flow.
3. Add one @tap action on a button to verify event/action execution.

#Prerequisites

The content of the document assumes that you have some understanding of HTML, CSS, JavaScript, and Web Components. If you are completely new to front-end development, it's better to grasp the basics before returning here. Having experience with other frameworks can be helpful but is not mandatory.

#Understanding Layout

When placing elements on a webpage, Lessjs follows stricter rules. On regular HTML pages, you use CSS almost exclusively to place elements. However, for performance reasons, Lessjs requires that all elements must set their display size from the start, so each component element must configure a layout attribute.

#Adding Images

Most HTML tags can be used directly in Lessjs HTML, but some tags (like the <img> tag) are replaced with more performance-efficient spz-img components.

In the example below, we use a fixed width and height layout to create a placeholder for the image element. In the fixed layout, you must configure a specific width and height. The displayed width and height of the image match the width and height we set in the layout configuration.

<spz-img
  layout="fixed"
  height="300"
  width="300"
  src="https://img.staticdj.com/5236bc0a95a0196e21bc3b52fcabab3f.jpeg"
  alt="Landscape image"
  class="rounded-xl"
></spz-img>

In the above example, besides the layout attribute, the src attribute is also configured, which contains the path of the image you want to embed, which is necessary.

#Using Templates

Some content on the page needs to be rendered through DOM elements after data is returned by an API request. At this time, we need to use templates to write markup templates that are not displayed on the page. The template content is rendered only after the data request is successful, displaying the rendered result on the page.

In the example below, spz-render uses local JSON data to render the template content.

Use a application/json type script on the page to generate JSON data.

<script id="render-data" type="application/json">
  {
    "name": "John von Neumann",
    "brief": "He was a Hungarian-American mathematician, physicist, computer scientist, engineer and polymath.",
    "imageSrc": "https://img.staticdj.com/5da228ddd934fd6ffecb3f95e985ee5a.gif"
  }
</script>

Then, use the generated JSON data as the data source in spz-render.

<spz-render layout="container" src="script:render-data">
</spz-render>

Then, use a template in spz-render. Inside the template, there can only be one root element. Use ${} to access the template data.

<spz-render layout="container" src="script:render-data">
  <template>
    <div>
      ${data.name}
    </div>
  </template>
</spz-render>

Finally, extract all data and display it on the page.

<script id="render-data" type="application/json">
  {
    "name": "John von Neumann",
    "brief": "He was a Hungarian-American mathematician, physicist, computer scientist, engineer and polymath.",
    "imageSrc": "https://img.staticdj.com/5da228ddd934fd6ffecb3f95e985ee5a.gif"
  }
</script>

<spz-render layout="container" src="script:render-data">
  <template>
    <div class="m-flex m-p-4 m-mx-auto m-bg-white m-shadow-sm m-rounded-xl" style="width: 480px;">
      <spz-img
        layout="fixed"
        width="80"
        height="80"
        src="${data.imageSrc}"
        alt="${data.name}"
        object-fit="cover"
        auto-fit
        class="m-flex-shrink-0 m-rounded-full m-overflow-hidden"
      ></spz-img>
      <div class="m-ml-6 m-text-left">
        <p class="m-font-bold m-pb-2">${data.name}</p>
        <div>${data.brief}</div>
      </div>
    </div>
  </template>
</spz-render>

#Methods and Events

Lessjs supports interactive user experiences. However, to ensure page performance and user experience, its approach is slightly different from non-Lessjs pages.

Lessjs uses @eventName to install event handlers on elements. Like attributes, some events and methods are available to all elements, while others are specific to certain components. Below, we will register a basic event, a user's click, and then respond using a hide operation.

Add a button to the page and assign the @tap attribute:

<button @tap="">
  Goodbye Lessjs HTML!
</button>

Then, we add the defined id (the target we want our action to affect). We will hide our <h3 id="hello"> element, so we add "hello" in the attribute value.

<button @tap="hello">
  Goodbye Lessjs HTML!
</button>

Finally, add a period (.), and then define the action. In the current case, it's hide.

<button @tap="hello.hide">
  Goodbye Lessjs HTML!
</button>

Now, if we click our button, the <h3> element will be hidden.

<h3 id="hello">Hello Lessjs HTML!</h3>

<button @tap="hello.hide">
  Goodbye Lessjs HTML!
</button>

#Common Pitfalls

• Treating layout as optional: in Lessjs, layout information is usually required for components.
• Using multiple root nodes in <template>: only one root element is allowed.
• Providing only a target id without an action: @tap="hello" is incomplete; use an expression like @tap="hello.hide".

#AI Usage Notes (LLM Ready)

• Section density: detected 5 level-2 headings.
• Example density: detected 9 code blocks.
• Read conclusions first: extract definitions, constraints, and boundary conditions.
• Then verify with examples: rely on executable snippets rather than prose only.
• Finally cross-check: open related component pages to avoid doc/runtime drift.