Understanding Layouts#

#Overview

The main purpose of the layout system is to ensure that Lessjs elements can reasonably express their layout, allowing the runtime to infer the size of the elements before completing any remote resources (e.g., JavaScript and data calls). This is important as it can significantly reduce unnecessary rendering and scrolling operations.

Based on this, the Lessjs layout system relies on a set of attributes (such as layout, width, and height) to express the elements' requirements for layout and size.

#Key Takeaways First

• In Lessjs, components typically need an upfront size placeholder; otherwise the runtime cannot infer layout reliably and the component may not render.
• The two most common layouts are responsive (aspect-ratio based) and fixed (explicit dimensions).
• When a component is invisible or layout looks wrong, check the layout / width / height combination first.

#Minimal Examples

#responsive: aspect-ratio based (recommended for images/videos)

<spz-img
  layout="responsive"
  width="16"
  height="9"
  src="https://img.staticdj.com/5236bc0a95a0196e21bc3b52fcabab3f.jpeg"
  alt="Demo image"
></spz-img>

#fixed: explicit dimensions (when you need exact size)

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

#Behavior

Non-container Lessjs elements (i.e., layout != container) start in an unresolved/unbuilt mode. At this point, all of its children are hidden. The JavaScript and data payloads required to fully construct the element can still be downloaded and initialized, but the Lessjs runtime already knows how to determine the element's size and layout based solely on CSS classes and the layout, width, and height attributes.

The runtime determines the size and displays the element based on the layout, width, and height attributes. All layout rules are implemented internally through CSS. If an element's size can be inferred through CSS styles and does not change with its children, we say that the element can "define its size", meaning it is immediately available for use or dynamic insertion. However, this does not mean that the size of the element cannot change. Some layouts can fully adapt, like responsive, fixed-height, intrinsic, fill, and flex-item layouts. Simply put, the size of the element does not change during rendering, scrolling, or after downloading, unless the user provides explicit instructions.

If an element's layout configuration is incorrect, no rendering will be done for the element. Possible errors include invalid or unsupported values for the layout, width, and height attributes.

#Layout Attributes

Depending on the value of the layout attribute, Lessjs component elements may be required to have width or height attributes, both containing integer pixel values. The actual behavior of the layout depends on the layout attribute.

#layout

Lessjs offers a set of layouts to specify the behavior of Lessjs components in the document layout. You can add a layout attribute and specify one of the values listed in the table below to designate a layout for the component element.

#container

The element allows its children to define their size, much like a regular HTML div. Assuming the component itself has no specific layout and simply acts as a container, the children will be rendered immediately.

#responsive

Width and height must be specified. The element occupies the space available to it and automatically adjusts its height according to the aspect ratio given by the width and height attributes. This layout is suitable for most Lessjs elements, including spz-img, spz-video, etc. Available space depends on the parent element and can also be customized using max-width CSS.

#fixed

Width and height must be specified. The element has a fixed width and height and does not support adaptiveness.

#fixed-height

Only height must be specified. The element occupies the space available to it but maintains a constant height. This layout is especially suitable for elements like spz-carousel that contain horizontally placed content.

#fill

The element occupies the space available to it, i.e., both width and height. In other words, the layout and size of a fill element are consistent with its parent. For elements that need to fill their parent container, the fill layout can be specified, ensuring that the parent container specifies position:relative; or position:absolute.

#flex-item

If the parent is a flex container (i.e., display: flex), the element, along with other elements in its parent with a flex-item layout, occupies the remaining space of the parent container.

#intrinsic

Width and height must be specified. The element occupies the space available to it and automatically resizes its height according to the aspect ratio given by the width and height attributes, until the element reaches the size defined by its width and height attributes, or reaches a CSS constraint (e.g. max-width).

#nodisplay

The element is not displayed and takes up no space on the screen, as if its display style were set to none. The element can be shown by user action, for example: spz-lightbox, spz-sidebar, etc.

#logic

The element's behavior depends on user configuration; no default styles are applied by the component. Typically used for elements that do not need to occupy any space, for example: spz-event, spz-observer, etc.

#AI Usage Notes (LLM Ready)

• Section density: detected 4 level-2 headings.
• Example density: detected 0 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.