---
url: /guide/ui/elements-components.md
---

# Composing Elements

A Lynx page may contain various visual elements such as text and images, presented in different layouts to create diverse page styles. This section aims to help everyone understand how to construct the most basic views.

## Element tag: UI Building Blocks

Lynx defines content and structure using a markup language, with the most basic unit being an [element tag](/guide/spec.md#element-tag). The concept of an element tag is similar to [HTML elements](https://developer.mozilla.org/en-US/docs/Glossary/Element), which can be used to encapsulate different parts of the content to present or operate in a specific manner.

Unlike HTML, Lynx uses some unique element tags such as [`<view>`](/api/elements/built-in/view.md), [`<text>`](/api/elements/built-in/text.md), and [`<image>`](/api/elements/built-in/image.md) to display different content. For example, in Lynx, the following source code can be used to display a piece of text:

```html
<text>Hello Lynx</text>
```

### Anatomy of an Element tag

The basic usage of element tags is very similar to [HTML elements](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content#anatomy_of_an_html_element):

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tags.png)
Each element tag consists of the following parts:

1. **Start tag**: Includes the name of the element tag (in this case, text) surrounded by angle brackets, indicating where the element tag begins.
2. **End tag**: Similar to the start tag but includes a forward slash before the element tag's name, indicating where the element tag ends.
3. **Content**: The content of the element tag, which for the `<text>` element tag is the text itself.

Combining the start tag, end tag, and content forms a complete element tag.

### Attributes

Each element tag has its own attributes that can be set by adding attribute names and values within the element tag's tag to describe its behavior and appearance.

For example, each element tag can use attributes such as [`style`](/api/elements/built-in/view.md#style) and [`class`](/api/elements/built-in/view.md#class) to set background, border-radius, shadow styles, and support some CSS syntax. The following code sets the background color of an element tag to red:

```html
<text style="background:red;">Hello Lynx</text>
```

In this example, `style` is the attribute name, and `background:red` is the attribute value.

For more attributes, refer to the [API Reference](/api/elements/built-in/view.md).

### Empty Element tags

Some element tags do not have content, such as the `<image>` element tag:

```html
<image src="assets/logo.png" />
```

It does not use an `</image>` end tag, nor does it have any content inside because the `<image>` element tag uses an attribute `src` to display an image rather than content.

### Nested Element tags

Element tags can be nested within other element tags. For example, multiple `<text>` element tags can be nested inside a `<view>` element tag:

```html
<view>
  <text>Hello</text>
  <text>Lynx</text>
</view>
```

### Element Tree

The element tags in the source code will be parsed by the Lynx engine at runtime and translated into [elements](/guide/spec.md#element) for rendering. Nested element tags will form a tree composed of elements, which we refer to as the [element tree](/guide/spec.md#element-tree). We rely on this tree structure to build and manage more complex interfaces.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tree.png)
## Built-in Elements

The Lynx Engine comes with some built-in elements by default to help you quickly build pages.

### View

The `<view>` is the most basic element, commonly used to wrap other elements and carry some drawing capability. For example, the following code sets the entire view's background color to gray and adds some padding within the view:

```html
<view style="padding:10px;background:gray;">
  <text>Hello Lynx</text>
</view>
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx_gray.png)
### Text

As mentioned earlier, the `<text>` element is used to display text content. For instance, the following code can be used to display a piece of text:

```html
<text>Hello Lynx</text>
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx.png)
### Image

The `<image>` element is used to display images. For example, the following code can be used to display an image:

```html
<image auto-size style="width:100px;" src="assets/logo.png" />
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_lynx_logo.png)
### More Built-in Elements

For all built-in Lynx elements, refer to [Built-in Elements Documentation](/api/elements/built-in/view.md).

### XElement

XElement is an extended native elements library maintained by the Lynx team. It provides richer component capabilities, enabling faster adoption of Lynx in production environments and enhancing the vibrancy of the Lynx ecosystem.

To use XElement, it needs to be integrated into your native project first. See [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md) for setup instructions.

## Behind the Elements: Native Rendering

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_2_na.png)
Lynx elements are designed to be platform-agnostic. They are rendered natively by the Lynx Engine into the UI primitives for each platforms, such as iOS and Android views, or HTML elements (including [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)) on the Web.

Lynx enables cross-platform application development based on the web technology, with its core being the establishment of a unified rendering system through element abstraction. Understanding the mapping relationship between the native views of the platform and Lynx elements is crucial to mastering the design concepts of elements within this framework. Below are some of the built-in elements and their corresponding concepts or analogues in different platforms:

| Element                                                  | Android                  | iOS                               | HarmonyOS                                  | Web analogy                    | Description                                                                                                               |
| :------------------------------------------------------- | :----------------------- | :-------------------------------- | :----------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| [`<view>`](/api/elements/built-in/view.md)               | `ViewGroup`              | `UIView`                          | `Stack`                                    | Non-scrollable `<div>`         | Basic view container, often used for layout capabilities, stylization, and wrapping other elements.                       |
| [`<text>`](/api/elements/built-in/text.md)               | `TextView`               | `UITextView`                      | `Text`                                     | `<p>`                          | Used for displaying text content. Specific text styles can be aligned.                                                    |
| [`<image>`](/api/elements/built-in/image.md)             | `ImageView`              | `UIImageView`                     | `Image`                                    | `<img>`                        | Used for displaying different types of images, including web images, static resources, and local disk images.             |
| [`<scroll-view>`](/api/elements/built-in/scroll-view.md) | `ScrollView`             | `UIScrollView`                    | `Scroll`                                   | `<div>` with `overflow:scroll` | Basic scrollable element that supports horizontal and vertical scrolling. Allows users to scroll to display more content. |
| [`<list>`](/api/elements/built-in/list.md)               | `RecyclerView`           | `UICollectionView`                | `List`                                     | None                           | High-performance scrollable element that reduces memory pressure through lazy loading and view reuse.                     |
| [`<page>`](/api/elements/built-in/page.md)               | `ViewRootImpl` of a page | `UIViewController.view` of a page | A custom component decorated with `@Entry` | Non-resizable `<body>`         | Root node of a page, usually doesn't need to be added manually.                                                           |

## Extending with Custom Elements

If built-in elements can't meet your needs, you can expand Lynx's capabilities by implementing native elements customarily. This is one of Lynx's powerful features.

For more details, refer to [Extending Native Elements Documentation](/guide/custom-native-component.md).

## Components: Composition of Elements

In more complex Lynx view structures, various types of elements are often nested and combined layer by layer to form richer and more diverse interface units. This is the core idea of component-based development in front-end frameworks: achieving modular construction of interfaces through reusable encapsulation units.

In ReactLynx, we follow the React development paradigm. By using a function and JSX to assemble the elements and define a component, its design philosophy and basic principles follow the [React Component Design Documentation](https://react.dev/learn/describing-the-ui). For example:

**This is an example below: composing-elements**

**Entry:** `src/App.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {7-10}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

export const App = ({ src }: { src: string }) => {
  return (
    <view>
      <image auto-size style="width:100px" src={src} />
      <text>Hello Lynx</text>
    </view>
  );
};

```



***

In the next chapter, we will add more elaborate styles to the interface.



---
url: /guide/ui/styling.md
---

# Styling with CSS

Cascading Style Sheets (CSS) are used to style and layout Lynx pages. For example, you can change the font, color, size, and position of the content, split the content into multiple columns, or add animations and other decorative elements to make your pages more vivid and interesting.
In addition, Lynx provides numerous properties starting with `-x-` to help you achieve style design more easily.
The following tutorial will demonstrate how to add styles to elements using CSS.

:::tip

If you have no basic knowledges about CSS,
you can go through the [guidance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics) from web docs.

:::

## Selectors and inline styles

You can use selectors and inline styles to set values to element's properties.

Such as using `class` attribute with a class selector:

The following example set the background property of the element whose `class` has 'bg-gradient'.

**This is an example below: css**

**Entry:** `src/class_guide`
**Bundle:** `dist/class_guide.lynx.bundle` | Web: `dist/class_guide.web.bundle`

```tsx {16}
import { root } from "@lynx-js/react";

import "./index.css";

function App() {
  return (
    <view
      style={{
        flexDirection: "column",
        marginTop: "50%",
        transform: "translate(-50%, -50%)",
        marginLeft: "50%",
        width: "150px",
        height: "150px",
      }}
      className="bg-gradient"
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



And you can also set the element's properties via `style` attribute directly. In the example before, we use `style` to change the element's position and size.

- [Learn more about styling properties](/guide/styling/appearance.md)
- [Property API references](/api/css/properties.md)
- [Selector API references](/api/css/selectors.md)

### Nesting

With nesting syntax, you can declare classes in an easier way.
You can get this in [Sass](/rspeedy/styling.md#%E4%BD%BF%E7%94%A8-sass), which is already supported in ReactLynx, or other [post css plugins](/rspeedy/styling.md#using-postcss), such as [postcss-nesting](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting).

```scss
.a {
  background: red;
  &-b {
    border-radius: 30px;
  }
}

/* equals */

.a {
  background: red;
}

.a-b {
  border-radius: 30px;
}
```

## CSS cascading

The [Cascade](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade) specification defines which value takes effect when multiple selectors applied to the same element, and they got duplicate properties with different values.

For example, properties set by `style` attribute covers those set by style rules (e.g class selector), class with higher [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) covers those lower ones.

**This is an example below: css**

**Entry:** `src/cascade_guide`
**Bundle:** `dist/cascade_guide.lynx.bundle` | Web: `dist/cascade_guide.web.bundle`

```css
.bg-gradient {
  background: radial-gradient(
    circle at top left,
    rgb(255, 53, 26),
    rgb(0, 235, 235)
  );
}

.bg-color {
  background: rgb(255, 53, 26);
}

```



In the case above，both two selectors, `bg-gradient` and `bg-color` are taking effect on the `<view>`，and they are both changing the `background` property.
Following the specification of the cascade, the class appears later in the document covers the earlier one, thus the rectangle should be red.

## CSS Variables and Opt-in Inheritance

Lynx supports [CSS custom properties](/api/css/properties/css-variable.md) (CSS variables) and opt-in CSS inheritance for dynamic styling and theming.

CSS custom properties are inherited by default, while regular (non-custom) CSS properties require explicit configuration.
See the Theming guide for details:

- [Switch themes using CSS descendant selectors](/guide/styling/custom-theming.md#using-css-descendant-selectors-to-switch-themes)
- [Switch themes using CSS custom properties](/guide/styling/custom-theming.md#using-css-variables-to-switch-themes)
- [Configure Lynx's opt-in CSS inheritance](/guide/styling/custom-theming.md#leveraging-css-inheritance-as-needed)



---
url: /guide/ui/layout/index.md
---

# Understanding Layout

Lynx provides:

- Properties such as [`width`], [`height`], [`margin`], and [`padding`] are used to describe the size of elements.
- The [`display`] property, along with [linear layout], [flexible box layout], [grid layout], and [relative layout], are used for laying out elements.
- The aligning properties, including [`align-items`], [`justify-content`] and etc., are used for aligning elements.
- The [`position`] property, along with [`left`], [`right`], [`top`], [`bottom`] properties, are used to position elements.
- [`direction`] and [logical properties] are used to support the internationalization of layouts.

For the layout properties supported by Lynx with the same name in the Web, the behavior of these properties will be consistent with those in the Web.
However, there is a difference in the design concept between Lynx layout and Web layout: Web layout is primarily text-based. While Lynx layout is based on elements (`<view>`, `<text>`, `<image>`, etc.). In other words, elements in Lynx are all [block-level elements](https://developer.mozilla.org/en/docs/Glossary/Block-level_content).

The following tutorial will show you how to complete the layout of elements in Lynx.

## Sizing the Elements

You can use [`width`], [`height`], [`max-width`], [`min-width`], [`max-height`], [`min-height`], [`margin`], [`padding`], and [`border-width`] to describe the size and box model of an element. These properties support various [length units] such as `px`, `%`, `vh` and etc. Additionally, `width` and `height` support [`max-content`] and [`fit-content`] for sizing elements according to their content.

**This is an example below: layout**

**Entry:** `src/sizing`
**Bundle:** `dist/sizing.lynx.bundle` | Web: `dist/sizing.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const SizingExample = () => {
  return (
    <scroll-view>
      <text className="box">Auto Sized Element</text>
      <text className="box" style={{ width: "fit-content" }}>
        Size Decided by Content
      </text>
      <text className="box" style={{ width: "150px", height: "150px" }}>
        Size as Specified
      </text>
      <text className="box" style={{ width: "50%" }}>
        Specify Size with Percentage
      </text>
      <text className="box" style={{ maxWidth: "100px" }}>
        Limited By Max Size
      </text>
      <text className="box" style={{ minHeight: "100px" }}>
        Expanded By Min Size
      </text>
    </scroll-view>
  );
};

root.render(<SizingExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



`box-sizing` is `border-box` by default and Lynx does not exhibit the behavior of margin collapsing.By default, the size properties of Lynx, such as `width`, `height`, and `max-width`, describe the size of the border box. This is inconsistent with the default behavior of the Web.
Lynx does not exhibit the behavior of [margin collapsing](https://developer.mozilla.org/en/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) as in the Web.

## Layout the Elements

The [`<view>`] element can be used for laying out child elements, and by setting the [`display`] property on the `<view>` element, you can control the way it lays out its child elements. The display property supports five values: `linear`, `flex`, `grid`, `relative` and `none`.

### Linear Layout

If you want to simply arrange the elements in order, you can set the [`display`] property to linear and use Lynx's default layout, which is the [linear layout]. The Linear layout (inspired by Android's [Linear Layout](https://developer.android.com/develop/ui/views/layout/linear)) can arrange the elements in order according to the direction you declare.

**This is an example below: layout**

**Entry:** `src/linear`
**Bundle:** `dist/linear.lynx.bundle` | Web: `dist/linear.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const LinearExample = () => {
  return (
    <view className="column">
      <text className="item">column item 1</text>
      <text className="item">column item 2</text>
      <text className="item">column item 3</text>
      <view className="row">
        <text className="item">row item 1</text>
        <text className="item">row item 2</text>
        <text className="item">row item 3</text>
      </view>
    </view>
  );
};

root.render(<LinearExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Flexible Box Layout

If you need to make the size of child elements adapt to the space of the parent element (such as expanding child elements to fill the unused space or shrinking child elements to avoid overflow), you can set the [`display`] property to `flex` and use the [flexible box layout]. The flexible box layout in Lynx is consistent with the one in Web.

**This is an example below: layout**

**Entry:** `src/flex`
**Bundle:** `dist/flex.lynx.bundle` | Web: `dist/flex.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const FlexExample = () => {
  return (
    <view>
      <view className="flex">
        <text className="item">item</text>
        <text className="item" style={{ flexGrow: 1 }}>
          grow to fill
        </text>
      </view>
      <view className="flex">
        <text className="item" style={{ flexShrink: 0, width: "75%" }}>
          large item
        </text>
        <text className="item" style={{ flexShrink: 1 }}>
          shrink to fit
        </text>
      </view>
    </view>
  );
};

root.render(<FlexExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Grid Layout

If you want to arrange multiple elements alternately in both vertical and horizontal directions to form a two-dimensional layout, you can set the [`display`] property to `grid` and use the [grid layout], a layout in the Web that can divide the space into a two-dimensional grid and place elements in the specified rows and columns. Lynx supports a subset of its features.

**This is an example below: layout**

**Entry:** `src/grid`
**Bundle:** `dist/grid.lynx.bundle` | Web: `dist/grid.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridExample = () => {
  return (
    <scroll-view>
      <text className="title">
        grid-template-columns: 1fr 100px 2fr;
      </text>
      <text className="title">
        grid-template-rows: 1fr 1fr;
      </text>
      <view
        className="container"
        style={{ height: "80px", gridTemplateColumns: "1fr 100px 2fr", gridTemplateRows: "1fr 1fr" }}
      >
        <text className="item" style={{ gridRowStart: "span 2" }}>span 2</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item" style={{ gridColumnStart: "span 2" }}>span 2</text>
      </view>

      <text className="title">
        grid-template-columns:
      </text>
      <text className="title">
        20% max-content minmax(50px, max-content);
      </text>
      <view
        className="container"
        style={{
          gridTemplateColumns: "20% max-content minmax(50px, max-content)",
          height: "max-content",
        }}
      >
        <text className="item">20%</text>
        <text className="item" style={{ fontSize: "17px" }}>NO WRAP!</text>
        <text className="item">min-width:50px, will fit the container</text>
      </view>

      <text className="title">
        grid-template-columns: 1fr 1fr;
      </text>
      <text className="title">grid-template-rows: 1fr max-content 1fr;</text>
      <view
        className="container"
        style={{
          gridTemplateColumns: "1fr 1fr",
          gridTemplateRows: "1fr max-content 1fr",
          height: "140px",
        }}
      >
        <text className="item" style={{ gridColumnStart: "span 2" }}>span 2</text>
        <text className="item">max-content: will take the maximum size of the items as the row size</text>
        <text className="item">THREE</text>
        <text className="item" style={{ gridColumnStart: "-2" }}>columnStart: -2</text>
      </view>
    </scroll-view>
  );
};

root.render(<GridExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Relative Layout

If you want to describe the layout through the relative position relationship between elements, you can set the [`display`] property to `relative` and use the [relative layout]. The relative layout(inspired by Android's [Relative Layout](https://developer.android.com/develop/ui/views/layout/relative)) can declare the layout by describing the position relationship between elements (for example, one element is located to the left of another element).

**This is an example below: layout**

**Entry:** `src/relative_layout`
**Bundle:** `dist/relative.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const RelativeExample = () => {
  return (
    <view className="container">
      <view className="close"></view>
      <view className="user_name"></view>
      <view className="user_description"></view>
      <view className="avatar"></view>
      <view className="user_lv"></view>
      <view className="follow"></view>
    </view>
  );
};

root.render(<RelativeExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Text and Inline Layout

In Lynx, text cannot be directly inserted into the [`<view>`] element, and the [`display`] property of Lynx does not support the values of `inline` and `block`. The [`<text>`] element can complete text display and the inline layout of elements. For details, please refer to [Text Typography](/guide/styling/text-and-typography.md).

## Aligning the Elements

You can align the elements laid out by a [`<view>`] with [`align-items`], [`align-self`], [`justify-content`], [`align-content`], [`justify-items`] and [`justify-self`] properties.

**This is an example below: layout**

**Entry:** `src/align`
**Bundle:** `dist/align.lynx.bundle` | Web: `dist/align.web.bundle`

```tsx {10,13,18,29}
import { root } from "@lynx-js/react";

import "./index.scss";

const AlignExample = () => {
  return (
    <view className="container">
      <view
        className="linear box"
        style={{ alignItems: "center", justifyContent: "space-between" }}
      >
        <text>linear item 1</text>
        <text style={{ alignSelf: "end" }}>linear item 2</text>
        <text>linear item 3</text>
      </view>
      <view
        className="flex  box"
        style={{ justifyContent: "center", alignContent: "center" }}
      >
        <text>flex item 1</text>
        <text>flex item 2</text>
        <text>flex item 3</text>
        <text>flex item 4</text>
      </view>
      <view className="grid box">
        <text>grid item 1</text>
        <text
          className="grid-row-span"
          style={{ justifySelf: "center", alignSelf: "center" }}
        >
          grid item 2
        </text>
        <text>grid item 3</text>
      </view>
    </view>
  );
};

root.render(<AlignExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Offsetting and Absolute Positioning

You can offset the elements with [`top`], [`left`], [`bottom`], and [`right`] properties. And you can make elements absolutely positioned with [`position`] property.

**This is an example below: layout**

**Entry:** `src/position`
**Bundle:** `dist/position.lynx.bundle` | Web: `dist/position.web.bundle`

```tsx {12,26-28,43}
import { root } from "@lynx-js/react";

import "./index.scss";

const PositionExample = () => {
  return (
    <view className="column">
      <view className="row">
        <view className="box">
          <text>1</text>
        </view>
        <view className="box" style={{ bottom: "20px", right: "10px" }}>
          <text>2</text>
        </view>
        <view className="box">
          <text>3</text>
        </view>
      </view>
      <view className="row">
        <view className="box">
          <text>1</text>
        </view>
        <view
          className="box"
          style={{
            position: "absolute",
            top: "20px",
            left: "10px",
          }}
        >
          <text>ABS</text>
        </view>
        <view className="box">
          <text>3</text>
        </view>
      </view>
      <view className="row">
        <view className="box">
          <text>1</text>
        </view>
        <view
          className="box"
          style={{ position: "fixed", top: "50px", left: "50px" }}
        >
          <text>FIXED</text>
        </view>
        <view className="box">
          <text>3</text>
        </view>
      </view>
    </view>
  );
};

root.render(<PositionExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Internationalization

You can use the [`direction`] property and [logical properties] to make your page support both languages written from left to right (such as Chinese) and languages written from right to left (such as Arabic).
[logical properties] refer to a series of properties like `XX-inline-start` and `XX-inline-end` (such as [`inset-inline-start`]).

Enable CSS Inheritance and Logical PropertiesPlease refer to [CSS
Inheritance](/guide/styling/custom-theming.md#how-to-enable-css-inheritance),
using [`enableCSSInheritance`] to enable `direction` to be inheritable, and
using logical properties depends on the `direction` value.

**This is an example below: layout**

**Entry:** `src/direction`
**Bundle:** `dist/direction.lynx.bundle` | Web: `dist/direction.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const DirectionExample = () => {
  return (
    <view className="column">
      <view className="row logic-padding" style={{ direction: "ltr" }}>
        <view className="box">
          <text>1</text>
        </view>
        <view className="box">
          <text>2</text>
        </view>
        <view className="box">
          <text>3</text>
        </view>
      </view>
      <view className="row logic-padding" style={{ direction: "rtl" }}>
        <view className="box">
          <text>1</text>
        </view>
        <view className="box">
          <text>2</text>
        </view>
        <view className="box">
          <text>3</text>
        </view>
      </view>
    </view>
  );
};

root.render(<DirectionExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



[`width`]: /api/css/properties/width.md

[`height`]: /api/css/properties/height.md

[`min-width`]: /api/css/properties/min-width.md

[`min-height`]: /api/css/properties/min-height.md

[`max-width`]: /api/css/properties/max-width.md

[`max-height`]: /api/css/properties/max-height.md

[`flex-grow`]: /api/css/properties/flex-grow.md

[`flex-shrink`]: /api/css/properties/flex-shrink.md

[`direction`]: /api/css/properties/direction.md

[`display`]: /api/css/properties/display.md

[`margin`]: /api/css/properties/margin.md

[`padding`]: /api/css/properties/padding.md

[`position`]: /api/css/properties/position.md

[`border-width`]: /api/css/properties/border-width.md

[`inset-inline-start`]: /api/css/properties/inset-inline-start.md

[`top`]: /api/css/properties/top.md

[`bottom`]: /api/css/properties/bottom.md

[`max-content`]: /api/css/data-type/max-content.md

[`fit-content`]: /api/css/data-type/fit-content.md

[`justify-self`]: /api/css/properties/justify-self.md

[`justify-items`]: /api/css/properties/justify-items.md

[`align-self`]: /api/css/properties/align-self.md

[`align-content`]: /api/css/properties/align-content.md

[`justify-content`]: /api/css/properties/justify-content.md

[`align-items`]: /api/css/properties/align-items.md

[`left`]: /api/css/properties/left.md

[`right`]: /api/css/properties/right.md

[`<view>`]: /api/elements/built-in/view.md

[`<text>`]: /api/elements/built-in/text.md

[length units]: /api/css/data-type/length-percentage.md

[linear layout]: /guide/ui/layout/linear-layout.md

[relative layout]: /guide/ui/layout/relative-layout.md

[flexible box layout]: /guide/ui/layout/flexible-box-layout.md

[grid layout]: /guide/ui/layout/grid-layout.md

[logical properties]: https://developer.mozilla.org/en/docs/Web/CSS/CSS_logical_properties_and_values

[`enableCSSInheritance`]: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md#pluginreactlynxoptionsenablecssinheritance-property



---
url: /guide/ui/layout/linear-layout.md
---

# Linear Layout

If you want to arrange children sequentially without dealing with the complexities of [flexible box](/guide/ui/layout/flexible-box-layout.md) and [grid](/guide/ui/layout/grid-layout.md) layouts (such as shrink and placement issues), consider using **linear layout**. This layout is inspired by [linear layout](https://developer.android.com/develop/ui/views/layout/linear) in Android.

The default layout direction of a linear layout is vertical. You can also use Web's alignment properties such as [`align-items`](/api/css/properties/align-items.md), [`align-self`](/api/css/properties/align-self.md), and [`justify-content`](/api/css/properties/justify-content.md) with this layout. For the supported properties, please refer to the [Reference section](#reference).

## How to Build a Linear Layout?

### Step 1: Apply `display: linear`

To implement a linear layout, modify the `display` property of the parent element to use a linear layout for its children.

```css
display: linear;
```

### Step 2: Set the Layout Direction

A linear layout arranges elements along the main and cross axes, similar to a [flexible box layout](/guide/ui/layout/flexible-box-layout.md). The **main axis** refers to the direction in which elements are aligned, whereas the **cross axis** is perpendicular to it.

You can adjust the layout direction by altering the [`linear-direction`](/api/css/properties/linear-direction.md) property of the parent container, akin to the [`flex-direction`](/api/css/properties/flex-direction.md) property in flexible box layouts. By default, `linear-direction` is set to `column`.

```css
linear-direction: column;
```

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/linear_main_axis.png)
### Step 3: Align Children Along the Main Axis

To control the position of child elements along the main axis, use the [`justify-content`](/api/css/properties/justify-content.md) property. In the demo below, the main axis is vertical.

**This is an example below: layout**

**Entry:** `src/linear_justify_content`
**Bundle:** `dist/linear_justify_content.lynx.bundle` | Web: `dist/linear_justify_content.web.bundle`

```tsx {9,16,23}
import { root } from "@lynx-js/react";

import "./index.scss";

const LinearJustifyContentExample = () => {
  return (
    <scroll-view>
      <text className="title_style">justify-content: start</text>
      <view className="container" style={{ justifyContent: "start" }}>
        <view className="item1"></view>
        <view className="item2"></view>
        <view className="item3"></view>
      </view>

      <text className="title_style">justify-content: end</text>
      <view className="container" style={{ justifyContent: "end" }}>
        <view className="item1"></view>
        <view className="item2"></view>
        <view className="item3"></view>
      </view>

      <text className="title_style">justify-content: center</text>
      <view className="container" style={{ justifyContent: "center" }}>
        <view className="item1"></view>
        <view className="item2"></view>
        <view className="item3"></view>
      </view>

      <text className="title_style">justify-content: space-between</text>
      <view className="container" style={{ justifyContent: "space-between" }}>
        <view className="item1"></view>
        <view className="item2"></view>
        <view className="item3"></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearJustifyContentExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Step 4: Align Children Along the Cross Axis

To align items within a container along the cross axis, apply [`align-items`](/api/css/properties/align-items.md) to the container or [`align-self`](/api/css/properties/align-items.md) to children.

In the example below, the cross axis is vertical, with `align-items: center` used in the container to center children along this axis.

**This is an example below: layout**

**Entry:** `src/linear_align_items`
**Bundle:** `dist/linear_align_items.lynx.bundle` | Web: `dist/linear_align_items.web.bundle`

```tsx {27}
import { root } from "@lynx-js/react";

const LinearAlignItemsExample = () => {
  return (
    <scroll-view>
      <text
        style={{
          fontSize: "45rpx",
          fontWeight: "bold",
          marginLeft: "auto",
          marginRight: "auto",
          textAlign: "center",
          color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))",
        }}
      >
        align-items: center
      </text>
      <view
        className="container"
        style={{
          display: "linear",
          linearOrientation: "horizontal",
          height: "300px",
          width: "90%",
          padding: "5px",
          margin: "10px",
          justifyContent: "center",
          marginLeft: "auto",
          marginRight: "auto",
          alignItems: "center",
          border: "1px solid #000",
          borderRadius: "6px",
        }}
      >
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            backgroundColor: "rgb(0,235,235)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearAlignItemsExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



By adjusting the `align-self` property on a child, you can override `align-items` behavior, as shown with the first block below the parent element.

**This is an example below: layout**

**Entry:** `src/linear_align_self`
**Bundle:** `dist/linear_align_self.lynx.bundle` | Web: `dist/linear_align_self.web.bundle`

```tsx {17,27}
import { root } from "@lynx-js/react";

const LinearAlignSelfExample = () => {
  return (
    <scroll-view>
      <view
        className="container"
        style={{
          display: "linear",
          linearOrientation: "horizontal",
          height: "300px",
          width: "90%",
          padding: "5px",
          margin: "10px",
          justifyContent: "center",
          marginLeft: "auto",
          marginRight: "auto",
          alignItems: "center",
          border: "1px solid #000",
          borderRadius: "6px",
        }}
      >
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            alignSelf: "end",
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            backgroundColor: "rgb(0,235,235)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "2px",
            height: "100px",
            width: "30%",
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearAlignSelfExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



::: info
Please note that when the cross-axis size of the parent element (such as the `width` when `linear-direction: column`) is set, and if the size of the child element in this direction is not specified (or `auto`), the children's size along the cross-axis will expand to fill the container.
:::

### Step 5: Specify Dynamic Sizes Along the Main Axis

Linear layout allows for the [`linear-weight`](/api/css/properties/linear-weight.md) attribute, enabling adaptive sizing along the main axis based on assigned weight ratios and available space.

Set the [`linear-weight`](/api/css/properties/linear-weight.md) for each child to define its size share along the main axis. The parent container adjusts every child's dimensions to fit proportions derived from their respective weight values relative to available space.

**This is an example below: layout**

**Entry:** `src/linear_weight`
**Bundle:** `dist/linear_weight.lynx.bundle` | Web: `dist/linear_weight.web.bundle`

```tsx {33,42,51}
import { root } from "@lynx-js/react";

const LinearAlginItemsExample = () => {
  return (
    <scroll-view>
      <text
        style={{
          fontSize: "45rpx",
          fontWeight: "bold",
          marginLeft: "auto",
          marginRight: "auto",
          textAlign: "center",
          color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))",
        }}
      >
        linear-weight: 0.5 : 2 : 0.5
      </text>
      <view
        style={{
          display: "linear",
          linearOrientation: "vertical",
          height: "300px",
          width: "90%",
          padding: "5px",
          margin: "10px",
          marginLeft: "auto",
          marginRight: "auto",
          border: "1px solid #000",
          borderRadius: "6px",
        }}
      >
        <view
          style={{
            margin: "5px",
            linearWeight: 0.5,
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "5px",
            linearWeight: 2,
            backgroundColor: "rgb(0,235,235)",
            borderRadius: "6px",
          }}
        >
        </view>
        <view
          style={{
            margin: "5px",
            linearWeight: 0.5,
            backgroundColor: "rgb(255,53,26)",
            borderRadius: "6px",
          }}
        >
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearAlginItemsExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, `linear-weight` specifies a scale value without unit representing the amount of space available for each child element along the main axis. The three child elements will have a 0.5 : 2 : 0.5 ratio of the main axis space.

## Reference

Currently, the linear layout supports the following layout properties:

- **Specific CSS Properties**
  - [`linear-direction`](/api/css/properties/linear-direction.md)
  - [`linear-weight`](/api/css/properties/linear-weight.md)

- **Alignment Properties**
  - [`justify-content`](/api/css/properties/justify-content.md)
  - [`align-items`](/api/css/properties/align-items.md)
  - [`align-self`](/api/css/properties/align-self.md)

- **Other Properties**

  Other properties such as [`order`](/api/css/properties/order.md), [`aspect-ratio`](/api/css/properties/aspect-ratio.md), etc., are not listed individually here; for specific property support, refer to the [API Reference](/api/css/properties.md).



---
url: /guide/ui/layout/flexible-box-layout.md
---

# Flexible Box Layout

If you need to make the size of child elements adapt to the space of the parent element (such as expanding child elements to fill the unused space or shrinking child elements to avoid overflow), you can set the [`display: flex`](/api/css/properties/display.md) property to the parent element and use the **flexible box layout**.

::: info
For more information, please refer to the [CSS Flexible Box Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout) on MDN. Lynx supports common flexible box layout properties and in most cases aligns with Web standards. For the supported properties, please refer to the [Reference section](#reference).
:::

**The following examples show typical features of the flexible box layout.**

## Typical Features

### Filling the Parent Element with `flex-grow`

The [`flex-grow`] property helps you allocate the remaining space of the parent element to the size of the sub-elements based on the weight declared by `flex-grow`.

**This is an example below: layout**

**Entry:** `src/flex_grow`
**Bundle:** `dist/flex_grow.lynx.bundle` | Web: `dist/flex_grow.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const FlexGrowExample = () => {
  return (
    <scroll-view>
      <text className="title">
        flex-direction: column
      </text>
      <view className="container">
        <view className="item1">
          <text className="text">flex-grow: 1</text>
        </view>
        <view className="item2">
          <text className="text">flex-grow: 2</text>
        </view>
        <view className="item3">
          <text className="text">100px</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexGrowExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Shrinking Child Elements with `flex-shrink`

When the child elements are about to overflow the parent element, the child elements can shrinked according to the weight declared by [flex-shrink](/api/css/properties/flex-shrink.md) to fit the size of the parent element.

**This is an example below: layout**

**Entry:** `src/flex_shrink`
**Bundle:** `dist/flex_shrink.lynx.bundle` | Web: `dist/flex_shrink.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const FlexShrinkExample = () => {
  return (
    <scroll-view>
      <text className="title">
        flex-direction: column
      </text>
      <view className="container">
        <view className="item1">
          <text className="text">flex-shrink: 0</text>
          <text className="text">height 300px</text>
        </view>
        <view className="item2">
          <text className="text">flex-shrink: 1</text>
          <text className="text">height shrinks from 300px to fit container</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexShrinkExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Lynx differs from Web in the minimum value for shrinking sub-elements.Lynx currently does not support [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content), and therefore treats it temporarily as `0px`. This means that while the Web can ensure sub-elements do not shrink below their minimum content width when fitting the parent element size, Lynx cannot guarantee this at present.
Code```html
<div
  style="width:100px;
            height:70px;
            display:flex;
            background-color:rgb(0, 235, 235);"
>
  <div
    style="display:flex;
              height:50px;
              background-color:rgb(255, 53, 26);"
  >
    <div
      style="width:150px;
                height:50px;"
    ></div>
  </div>
</div>
```
Inconsistent behavior between Web and Lynx![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/layout_min_content.png)
### Wrapping with `flex-wrap`

The [`flex-wrap`] property allows content that doesn't fit on a single line to be displayed on subsequent lines. This attribute specifies whether flex elements are shown in a single or multiple lines. When allowed to wrap, this attribute can control the stacking direction of the lines.

**This is an example below: layout**

**Entry:** `src/flex_wrap`
**Bundle:** `dist/flex_wrap.lynx.bundle` | Web: `dist/flex_wrap.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const FlexWrapExample = () => {
  return (
    <scroll-view>
      <text className="title">
        flex-direction: row;
      </text>
      <text className="title">
        flex-wrap: wrap;
      </text>
      <view className="container" style={{ flexWrap: "wrap" }}>
        <view className="item">
          <text className="text">Item 1</text>
        </view>
        <view className="item" style={{ backgroundColor: "rgb(0,235,235)" }}>
          <text className="text">Item 2</text>
        </view>
        <view className="item">
          <text className="text">Item 3</text>
        </view>
      </view>

      <text className="title">
        flex-direction: row;
      </text>
      <text className="title">
        flex-wrap: nowrap;
      </text>
      <view className="container" style={{ flexWrap: "nowrap" }}>
        <view className="item">
          <text className="text">Item 1</text>
        </view>
        <view className="item" style={{ backgroundColor: "rgb(0,235,235)" }}>
          <text className="text">Item 2</text>
        </view>
        <view className="item">
          <text className="text">Item 3</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexWrapExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Reference

Currently, Lynx supports the following common flexible box layout properties:

- **CSS Properties**
  - [`flex`](/api/css/properties/flex.md)
  - [`flex-basis`](/api/css/properties/flex-basis.md)
  - [`flex-direction`](/api/css/properties/flex-direction.md)
  - [`flex-flow`](/api/css/properties/flex-flow.md)
  - [`flex-grow`](/api/css/properties/flex-grow.md)
  - [`flex-shrink`](/api/css/properties/flex-shrink.md)
  - [`flex-wrap`](/api/css/properties/flex-wrap.md)
  - [`order`](/api/css/properties/order.md)

- **Alignment Properties**
  - [`align-content`](/api/css/properties/align-content.md)
  - [`align-items`](/api/css/properties/align-items.md)
  - [`align-self`](/api/css/properties/align-self.md)
  - [`justify-content`](/api/css/properties/justify-content.md)
  - [`row-gap`](/api/css/properties/row-gap.md)
  - [`column-gap`](/api/css/properties/column-gap.md)
  - [`gap`](/api/css/properties/gap.md)

For more usage details, please refer to the [CSS Flexible Box Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout) on MDN.

[`flex-grow`]: /api/css/properties/flex-grow.md

[`flex-shrink`]: /api/css/properties/flex-shrink.md

[`flex-wrap`]: /api/css/properties/flex-wrap.md



---
url: /guide/ui/layout/grid-layout.md
---

# Grid Layout

If you want a responsive layout where multiple elements are staggered both vertically and horizontally, the **grid layout** is your best choice. This layout is based on a two-dimensional grid, and it is the most powerful CSS layout on the Web.

:::info
For further details, please refer to MDN's [css grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout).
In Lynx, the grid layout largely follows with web standards. Currently, Lynx does not support [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) and [`grid-area`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area). Please refer to the [Reference](#reference) section for supported properties.
:::

**Here is a brief guide on using the grid layout.**

## How to Build a Grid Layout?

Before you build a grid layout, it's important first to understand the basic concepts.

### Basic Concepts

- **Grid Containers and Grid Items**

  The parent element using grid layout is called a "grid container." The children within the container that are layouted using grid layout are called "grid items".

- **Grid Lines**

  The lines that divide the grid layout are called "grid lines." Typically, x rows have x+1 horizontal grid lines, y columns have y+1 vertical grid lines, as shown in the image below with 6 horizontal and 4 vertical grid lines.

- **Grid Rows and Grid Columns**

  The spaces between two grid lines are called grid tracks. The horizontal tracks in the container are called "grid rows," and vertical tracks are called "grid columns."

- **Grid Cells**

  The intersection of rows and columns forms a grid cell.

- **Grid Areas**

  The area occupied by one or more grid cells by a grid item is called a grid area.

- **Inline Axis and Block Axis**

  As Lynx does not support [`writing-mode`](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode), the inline axis is horizontal, and the block axis is vertical.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/grid_define.png)
### Step 1: Apply `display: grid`

To implement the grid layout, set `display: grid` on the parent element.

```css
display: grid;
```

### Step 2: Specify the Size of Rows and Columns

Once the container has the grid layout specified, define the rows and columns. The [`grid-template-columns`] property specifies each column's width, while the [`grid-template-rows`] property defines each row's height.

If `grid-template-columns` or `grid-template-rows` are not explicitly used to define dimensions, the grid layout uses [`grid-auto-columns`] and [`grid-auto-rows`] for determining column widths and row heights.

**This is an example below: layout**

**Entry:** `src/grid_size`
**Bundle:** `dist/grid_size.lynx.bundle` | Web: `dist/grid_size.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridSize = () => {
  return (
    <scroll-view>
      <text className="title">grid-template-columns: 1fr 100px;</text>
      <text className="title">grid-template-rows: repeat(3, 1fr);</text>
      <view className="container">
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<GridSize />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Step 3: Specify Grid Gaps

Grid gap is the spacing between grid tracks. It can be indicated by [`column-gap`] for columns, [`row-gap`] for rows, or [`gap`] for both columns and rows.

**This is an example below: layout**

**Entry:** `src/grid_gap`
**Bundle:** `dist/grid_gap.lynx.bundle` | Web: `dist/grid_gap.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridGap = () => {
  return (
    <scroll-view>
      <text className="title">gap: 20px;</text>
      <view className="container" style={{ gap: "20px" }}>
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>

      <text className="title">column-gap: 20px;</text>
      <view className="container" style={{ columnGap: "20px" }}>
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>

      <text className="title">row-gap: 20px;</text>
      <view className="container" style={{ rowGap: "20px" }}>
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<GridGap />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Step 4: Align Grid Tracks to Inline and Block Axes

Align the grid tracks with the inline (horizontal axis) and block (vertical axis) using [`justify-content`] and [`align-content`].

**This is an example below: layout**

**Entry:** `src/grid_axis_alignment`
**Bundle:** `dist/grid_axis_alignment.lynx.bundle` | Web: `dist/grid_axis_alignment.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridAxisAlignment = () => {
  return (
    <scroll-view>
      <text className="title">justify-content: center;</text>
      <text className="title">align-content: start;</text>
      <view className="container" style={{ justifyContent: "center", alignContent: "start" }}>
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>

      <text className="title">justify-content: end;</text>
      <text className="title">align-content: center;</text>
      <view className="container" style={{ justifyContent: "end", alignContent: "center" }}>
        <view className="item">
          <text className="text">ONE</text>
        </view>
        <view className="item">
          <text className="text">TWO</text>
        </view>
        <view className="item">
          <text className="text">THREE</text>
        </view>
        <view className="item">
          <text className="text">FOUR</text>
        </view>
        <view className="item">
          <text className="text">FIVE</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<GridAxisAlignment />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Step 5: Specify the Grid Lines for Grid Items

The positions of grid items can be specified. Use [`grid-column-start`] and [`grid-column-end`] to set the columns a grid area spans, and [`grid-row-start`] and [`grid-row-end`] to define rows.

**This is an example below: layout**

**Entry:** `src/grid_placement`
**Bundle:** `dist/grid_placement.lynx.bundle` | Web: `dist/grid_placement.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridAxisAlignment = () => {
  return (
    <scroll-view>
      <view className="container" style={{ justifyContent: "center", alignContent: "start" }}>
        <view className="item" style={{ gridColumnStart: "span 2" }}>
          <text className="text">grid-column-start: span 2</text>
        </view>
        <view className="item" style={{ gridColumnStart: "2", gridRowStart: "2" }}>
          <text className="text">grid-column-start: 2;</text>
          <text className="text">grid-row-start: 2</text>
        </view>
        <view className="item" style={{ gridRowEnd: "-2", gridColumnStart: "span 2" }}>
          <text className="text">grid-column-start: span 2;</text>
          <text className="text">grid-row-end: -2</text>
        </view>
        <view className="item" style={{ gridColumnEnd: "-2", gridRowEnd: "-1" }}>
          <text className="text">grid-column-end: -2;</text>
          <text className="text">grid-row-end: -1</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<GridAxisAlignment />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Step 6: Align Grid Items to the Grid Area

Having established the grid items' respective grid areas in previous steps, you can now use [`align-items`] and [`align-self`] to vertically align grid items to the grid area, and [`justify-items`] and [`justify-self`] to horizontally align them as well. It's notable that `align-self` and `justify-self` settings on grid items will override those set by `align-items` and `justify-items` on the container.

**This is an example below: layout**

**Entry:** `src/grid_area_alignment`
**Bundle:** `dist/grid_area_alignment.lynx.bundle` | Web: `dist/grid_area_alignment.web.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const GridAxisAlignment = () => {
  return (
    <scroll-view>
      <text className="title">align-items: center;</text>
      <text className="title">justify-items: center;</text>
      <view className="container" style={{ alignItems: "center", justifyItems: "center" }}>
        <view className="item" style={{ gridColumnStart: "1", alignSelf: "end" }}>
          <text className="text">align-self: end;</text>
        </view>
        <view className="item_stretch">
          <text className="text">align-self: stretch;</text>
          <text className="text">justify-self: stretch;</text>
        </view>
        <view
          className="item"
          style={{ gridRowStart: "2", gridColumnStart: "1", justifySelf: "end", alignSelf: "start" }}
        >
          <text className="text">justify-self: end;</text>
          <text className="text">align-self: start;</text>
        </view>
        <view className="item_stretch">
          <text className="text">align-self: stretch;</text>
          <text className="text">justify-self: stretch;</text>
        </view>
        <view className="item" style={{ gridRowStart: "3", gridColumnStart: "1", justifySelf: "start" }}>
          <text className="text">justify-self: start;</text>
        </view>
        <view className="item_stretch">
          <text className="text">align-self: stretch;</text>
          <text className="text">justify-self: stretch;</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<GridAxisAlignment />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Reference

Currently, Lynx supports the following common grid layout properties:

- **CSS Properties**
  - [`grid-template-columns`](/api/css/properties/grid-template-columns.md)
  - [`grid-template-rows`](/api/css/properties/grid-template-rows.md)
  - [`grid-auto-columns`](/api/css/properties/grid-auto-columns.md)
  - [`grid-auto-rows`](/api/css/properties/grid-auto-rows.md)
  - [`grid-auto-flow`](/api/css/properties/grid-auto-flow.md)
  - [`grid-row-start`](/api/css/properties/grid-row-start.md)
  - [`grid-row-end`](/api/css/properties/grid-row-end.md)
  - [`grid-column-start`](/api/css/properties/grid-column-start.md)
  - [`grid-column-end`](/api/css/properties/grid-column-end.md)

- **Alignment Properties**
  - [`align-content`](/api/css/properties/align-content.md)
  - [`align-items`](/api/css/properties/align-items.md)
  - [`align-self`](/api/css/properties/align-self.md)
  - [`justify-content`](/api/css/properties/justify-content.md)
  - [`justify-items`](/api/css/properties/justify-items.md)
  - [`justify-self`](/api/css/properties/justify-self.md)
  - [`row-gap`](/api/css/properties/row-gap.md)
  - [`column-gap`](/api/css/properties/column-gap.md)
  - [`gap`](/api/css/properties/gap.md)

For more information on usage, please refer to MDN's [css grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout).

[`grid-template-columns`]: /api/css/properties/grid-template-columns.md

[`grid-template-rows`]: /api/css/properties/grid-template-rows.md

[`grid-auto-columns`]: /api/css/properties/grid-auto-columns.md

[`gap`]: /api/css/properties/gap.md

[`column-gap`]: /api/css/properties/column-gap.md

[`row-gap`]: /api/css/properties/row-gap.md

[`grid-auto-rows`]: /api/css/properties/grid-auto-rows.md

[`grid-column-start`]: /api/css/properties/grid-column-start.md

[`grid-column-end`]: /api/css/properties/grid-column-end.md

[`grid-row-start`]: /api/css/properties/grid-row-start.md

[`grid-row-end`]: /api/css/properties/grid-row-end.md

[`justify-content`]: /api/css/properties/justify-content.md

[`align-content`]: /api/css/properties/align-content.md

[`align-items`]: /api/css/properties/align-items.md

[`align-self`]: /api/css/properties/align-self.md

[`justify-items`]: /api/css/properties/justify-items.md

[`justify-self`]: /api/css/properties/justify-self.md



---
url: /guide/ui/layout/relative-layout.md
---

# Relative Layout no Web
If you want a layout that allows easily control the relative position between the parent and children or between the sibling elements without using complex hierarchical structure, **relative layout** (inspired by [relative Layout](https://developer.android.com/develop/ui/views/layout/relative) in Android) is the best choice. While using [grid](/guide/ui/layout/grid-layout.md), [flexible box](/guide/ui/layout/flexible-box-layout.md), and [linear](/guide/ui/layout/linear-layout.md) layouts, it's challenging to achieve a design that includes numerous relative positions using only a few styles.

Relative layout is a layout that displays children in relative positions, where each view's position can be specified relative to sibling elements (for example, to the left or below another view) or relative to the parent's area (e.g., align at bottom, left or center). For the supported properties, please refer to the [Reference section](#reference).

## How to Build a Relative Layout?

In the scenario described below, where the "user name" and "description" have a positional relationship, and the "user name" also aligns with the "avatar" on the right. What's more, the "follow", "close", "user" also have corresponding relationships with each other. The dashed lines and arrows in the image below are to indicate their positional relationship.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/relative_demo_1.png)
**Let's implement the above diagram using the relative layout in following steps:**

### Step 1: Apply `display: relative`

You can apply [`display: relative`](/api/css/properties/display.md) to the parent element where you want the relative layout.

```css
display: relative;
```

### Step 2: Set ID for Children

Assign a unique [`relative-id`](/api/css/properties/relative-id.md) (integer, not `0`) for each child in the relative layout. This step is to better identify each element.

```css
// avatar
relative-id: 1;
// user_name
relative-id: 2;
// user_description
relative-id: 3;
// user_lv
relative-id: 4;
// close
relative-id: 5;
// follow
relative-id: 6;
```

### Step 3: Set Edge Alignment Properties

Use these edge alignment properties to specify alignment of the element with its **parent or sibling**'s edge. For instance, [`relative-align-top`](/api/css/properties/relative-align-top.md) ensures the element aligns with the top edge of the designated parent or sibling id.

Physical Properties

- [`relative-align-top`](/api/css/properties/relative-align-top.md)、[`relative-align-right`](/api/css/properties/relative-align-right.md)、[`relative-align-bottom`](/api/css/properties/relative-align-bottom.md)、[`relative-align-left`](/api/css/properties/relative-align-left.md)

Logical Properties

- [`relative-align-inline-start`](/api/css/properties/relative-align-inline-start.md)、[`relative-align-inline-end`](/api/css/properties/relative-align-inline-end.md)

### Step 4: Set Relative Position Properties

Define relative positioning of the current element to its **sibling** elements using these properties. As an example, [`relative-left-of`](/api/css/properties/relative-left-of.md) arranges the current element to the left of the designated sibling, closely aligning right edge with the sibling's left edge.

Physical Properties

- [`relative-left-of`](/api/css/properties/relative-left-of.md)、[`relative-right-of`](/api/css/properties/relative-right-of.md)、[`relative-top-of`](/api/css/properties/relative-top-of.md)、[`relative-bottom-of`](/api/css/properties/relative-bottom-of.md)

Logical Properties

- [`relative-inline-start-of`](/api/css/properties/relative-inline-start-of.md)、[`relative-inline-end-of`](/api/css/properties/relative-inline-end-of.md)

### Step 5: Set Center Property

Use [`relative-center`](/api/css/properties/relative-center.md) declare how the current children element is centered in the container. By setting `vertical` to achieve vertical centering, setting `horizontal` to achieve horizontal centering, or setting `both` to simultaneously achieve both vertical and horizontal centering.

### Example

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/lynx_layout_relative_demo.png)
In this example, the container's width is fixed, while its height adjusts to its content. To incorporate gaps between elements, use `margin`.

**This is an example below: layout**

**Entry:** `src/relative_layout`
**Bundle:** `dist/relative.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const RelativeExample = () => {
  return (
    <view className="container">
      <view className="close"></view>
      <view className="user_name"></view>
      <view className="user_description"></view>
      <view className="avatar"></view>
      <view className="user_lv"></view>
      <view className="follow"></view>
    </view>
  );
};

root.render(<RelativeExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



- **Best Practices**

  Reasonable use of the relative layout can offer developers a convenient and efficient layout experience. Therefore, it is strongly recommended that developers follow the following points when developing.

  1. Parent container positioning can be used freely without affecting performance.
  2. When using the positioning between sibling elements, it is recommended to enable the [`relative-layout-once`](/api/css/properties/relative-layout-once.md) (default enabled) style, and the sibling element will only rely on upwards.
  3. Avoid circular dependencies where 'a' depends on 'b' for its horizontal width, and 'b' depends on 'a' for its vertical width, as this can severely impact performance.
  4. Please do not have unresolved circular dependencies, which cannot get the correct layout result.
  5. Try to use logical attributes, inline-start and inline-end, to facilitate page internationalization support.

## Reference

- **Relative Id**
  - [`relative-id`](/api/css/properties/relative-id.md)

- **Edge Alignment Properties**

  **Physical Properties**

  - [`relative-align-top`](/api/css/properties/relative-align-top.md)
  - [`relative-align-right`](/api/css/properties/relative-align-right.md)
  - [`relative-align-bottom`](/api/css/properties/relative-align-bottom.md)
  - [`relative-align-left`](/api/css/properties/relative-align-left.md)

  **Logical Properties**

  - [`relative-align-inline-start`](/api/css/properties/relative-align-inline-start.md)
  - [`relative-align-inline-end`](/api/css/properties/relative-align-inline-end.md)

- **Relative Position Properties**

  **Physical Properties**

  - [`relative-left-of`](/api/css/properties/relative-left-of.md)
  - [`relative-right-of`](/api/css/properties/relative-right-of.md)
  - [`relative-top-of`](/api/css/properties/relative-top-of.md)
  - [`relative-bottom-of`](/api/css/properties/relative-bottom-of.md)

  **Logical Properties**

  - [`relative-inline-start-of`](/api/css/properties/relative-inline-start-of.md)
  - [`relative-inline-end-of`](/api/css/properties/relative-inline-end-of.md)

- **Center Property**
  - [`relative-center`](/api/css/properties/relative-center.md)

- **Layout Optimization Property**
  - [`relative-layout-once`](/api/css/properties/relative-layout-once.md)



---
url: /guide/ui/scrolling.md
---

# Managing Scrolling

Overflow behavior occurs when the content of an element (its own content and child elements) exceeds the size of the element itself. During the process of building a page, it is inevitable to encounter situations of overflow. You can use the [`overflow`](/api/css/properties/overflow.md) property to crop the overflowing content, or use a \[scrollable element]\(#scrollable element to make the overflowing content scrollable, and control the scrolling direction of the content through the `scroll-orientation` property.

non-scrollable element
scrollable element
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/style-guide-overflow-visible.png) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/style-guide-overflow-hidden.png) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-scroll-orientation-vertical.gif) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-scroll-orientation-horizontal.gif) |
| Content overflow has occurred. | crop the overflowing content through 
`overflow: hidden
` | `scroll-orientation: vertical
` scrollable element | `scroll-orientation: horizontal
` scrollable element |


Doesn't support`overflow:scroll`for scrolling effect !In `Lynx`, the `view` component doesn't support the scrolling effect achieved by `overflow: scroll` as in the Web. Only scrolling containers like `<scroll-view>` and `<list>` have the scrolling effect.

## scrollable element

For some basic `<view>` element, the scrolling effect is not supported. Please use dedicated scroll container components [`<scroll-view>`](/api/elements/built-in/scroll-view.md) or [`<list>`](/api/elements/built-in/list.md).

### use `<scroll-view>` for basic scrolling

`<scroll-view>` is a basic scrolling component in `Lynx`. It allows users to scroll content vertically or horizontally within a fixed viewport area. Take the following figure as an example. When the height of the internal child nodes exceeds that of the parent `<scroll-view>` container, you only need to set the layout direction `scroll-orientation` to `vertical` to achieve the vertical scrolling effect.

**This is an example below: scroll-view**

**Entry:** `src/event`
**Bundle:** `dist/vertical.lynx.bundle` | Web: `dist/vertical.web.bundle`

```tsx {9}
import { root } from "@lynx-js/react";
import { VerticalScrollItem } from "../component/scrollItem.jsx";

const VerticalScrollContainer = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <text className="title">ScrollView Example</text>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "10px", marginLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => <VerticalScrollItem index={index} />)}
      </scroll-view>
    </view>
  );
};

root.render(<VerticalScrollContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### use `<list>` to manage large amount of data

`<scroll-view>` is used to display a small amount of data in a simple and intuitive way. On the other hand, `<list>` is suitable for scenarios where a large amount of data needs to be presented, or in scenarios with infinite scrolling for loading more content. It can adopt an on-demand loading way, rendering only the content in the visible area.

**This is an example below: list**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {12-14}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      scroll-orientation="vertical"
      list-type="single"
      span-count={1}
      style={{
        width: "100%",
        height: "100vh",
        listMainAxisGap: "5px",
        padding: "10px",
      }}
    >
      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### use `<list>` to handle complex layout

`<scroll-view>` only has the ability of linear layout, presenting elements in an orderly manner through linear arrangement. However, when facing complex interfaces, `<list>` offers a wide range of layout options. You can choose different layouts such as [flow](/api/elements/built-in/list.md#flow) and [waterfall](/api/elements/built-in/list.md#waterfall) to flexibly customize business requirements.

**This is an example below: list**

**Entry:** `src/waterfall`
**Bundle:** `dist/waterfall.lynx.bundle` | Web: `dist/waterfall.web.bundle`

```tsx {14-16}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";

import "./index.scss";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      list-type="waterfall"
      span-count={2}
      scroll-orientation="vertical"
    >
      {Array.from({ length: 40 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Additional Features

- sticky capability：`<scroll-view>`[sticky](/api/elements/built-in/scroll-view.md#sticky-capability)；`<list>`[sticky](/api/elements/built-in/list.md#implementing-sticky-nodes)

- `<list>` [paginated scrolling](/api/elements/built-in/list.md#implementing-paginated-scrolling)

- `<list>` [load more](/api/elements/built-in/list.md#implementing-load-more)



---
url: /guide/interaction/event-handling.md
---

# Event Handling

Lynx provides an event mechanism similar to the Web, allowing developers to design and implement custom interaction logic based on events.

However, unlike the Web system, Lynx's event response mechanism supports dual-threaded processing. This means that event handling functions can be executed in the main thread or background thread as needed, thereby optimizing performance and response speed.

## What is an event

An event is a signal that triggers an action in the system. When an event is triggered, developers can implement the corresponding logic by listening to the event and executing the corresponding code. For example, developers can listen to click events and modify the background color of a node when a user clicks on the page.

**Example 1:**

**This is an example below: event**

**Entry:** `src/event_bubble`
**Bundle:** `dist/event_bubble.lynx.bundle` | Web: `dist/event_bubble.web.bundle`

```tsx {7-12,23}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [bgColor, setBgColor] = useState<string>("white");

  function handleTap(e: TouchEvent) {
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        backgroundColor: bgColor,
        justifyContent: "center",
        alignItems: "center",
      }}
      bindtap={handleTap}
    >
      <view
        style={{
          width: "100px",
          height: "50px",
          borderRadius: "5px",
          backgroundColor: "gray",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text style={{ color: "red" }}>click me</text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Listen for user clicks

When a user clicks on a page, the system triggers a `tap` event.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/event/event_handling.png)
As shown in the figure, developers can choose to handle the event in the main thread or the background thread.

- When timely event response is not required, you can choose to handle the event in the background thread, and the event processing of the background thread will not block the main thread.

- When timely event response is required, you can choose to handle the event in the main thread, which can avoid event delays caused by cross-threading, but it should be noted that excessive event processing may cause the main thread to be busy.

Specifically, if developers want to listen to the click event of a certain node, they can set the event handler property of type `bind` on the node:

```tsx
<view bindtap={handleTap} />
```

If the event handling function runs on the main thread, you need to add an additional `main-thread:` prefix before the event handler property, for example:

```tsx
<view main-thread:bindtap={handleTapInMTS} />
```

How to intercept or specifically listen to an event?In Lynx
, the event handler property can also implement event interception and cross-component event listening. For details, please refer to [Event Propagation](/guide/interaction/event-handling/event-propagation.md).

## Handling user clicks

When an event is triggered on a node, the event handling function set by the event handler property will be called. This function will receive an event object as a parameter, which contains detailed information about the event.

What are the event objects?All event objects inherit from [Event](/api/lynx-api/event/event.md). Developers
can write event processing logic based on event objects in event processing
functions.

When the event processing function is a [main thread script](/react/main-thread-script.md), you need to add a [`'main thread'`](/api/react/Document.directives.md#main-thread) directive to the first line of the function body to indicate that the function runs on the main thread.

### Main thread event processing

In Lynx, the event objects of the main thread and the background thread are different. The event object of the background thread is a pure `json` object, while the event object of the main thread is an operable `Event Object`.

How to operate nodes based on event objects?Lynx provides a variety of ways to operate nodes, please refer to
[Manipulating
elements](/guide/interaction/event-handling/manipulating-element.react.md) for
details.

For example, for **Example 1**, when the developer chooses to handle events in the main thread, he can directly get [`e.currentTarget`](/api/lynx-api/event/event.md#currenttarget) in the [main thread script](/react/main-thread-script.md) and call [`setStyleProperty`](/api/lynx-api/main-thread/main-thread-element.md#elementsetstyleproperty) to modify the background color of the node.

**Example 2**

**This is an example below: event**

**Entry:** `src/event_node_eom`
**Bundle:** `dist/event_node_eom.lynx.bundle` | Web: `dist/event_node_eom.web.bundle`

```tsx {4-11,16}
import { root } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export default function App() {
  function handleTapInMTS(e: MainThread.TouchEvent) {
    "main thread";
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    e.currentTarget.setStyleProperty("background-color", rndCol);
  }

  return (
    <view
      style={{ width: "100%", height: "100%", justifyContent: "center", alignItems: "center" }}
      main-thread:bindtap={handleTapInMTS}
    >
      <view
        style={{
          width: "100px",
          height: "50px",
          borderRadius: "5px",
          backgroundColor: "gray",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text style={{ color: "red" }}>click me</text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Background thread event processing

For the event processing function of the background thread, developers cannot directly operate the node through [`e.currentTarget`](/api/lynx-api/event/event.md#currenttarget), but can obtain the node reference through [`SelectorQuery`](/api/lynx-api/selector-query.md) and then call [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) Modify the background color of the node.

**Example 3:**

**This is an example below: event**

**Entry:** `src/event_node_sq`
**Bundle:** `dist/event_node_sq.lynx.bundle` | Web: `dist/event_node_sq.web.bundle`

```tsx {5-16,21}
import { root } from "@lynx-js/react";
import type { NodesRef, SelectorQuery, TouchEvent } from "@lynx-js/types";

export default function App() {
  function handleTap(e: TouchEvent) {
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    (lynx
      .createSelectorQuery() as { selectUniqueID(uid: number): NodesRef } & SelectorQuery)
      .selectUniqueID(e.currentTarget.uid)
      .setNativeProps({
        "background-color": rndCol,
      })
      .exec();
  }

  return (
    <view
      style={{ width: "100%", height: "100%", justifyContent: "center", alignItems: "center" }}
      bindtap={handleTap}
    >
      <view
        style={{
          width: "100px",
          height: "50px",
          borderRadius: "5px",
          backgroundColor: "gray",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text style={{ color: "red" }}>click me</text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Summary

So far, you have learned how to listen to user clicks and perform corresponding operations based on the event object.

For developers, Lynx events provide a Web-like API, but with a unique dual-threaded event response mechanism, allowing developers to choose to perform event processing in the main thread or background thread as needed, thereby optimizing performance and response speed.



---
url: /guide/interaction/event-handling/event-propagation.md
---

# Event Propagation

When an event is triggered, it will propagate along the event response chain. If the corresponding type of event handler property is set on the node, the node can listen to the corresponding event or even intercept it during the event propagation process.

In addition, Lynx also provides cross-component event monitoring, event aspect interface, and `GlobalEventEmitter` to implement special event propagation.

## Event handler property

By setting the event handler properties, developers can decide at which stage (or across components) of event propagation to listen or intercept the event, and specify the processing function to be called when the event is triggered. The names of these event handler properties are usually composed of the bound event type and event name.

| Event Type      | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| `bind`          | Listen to events in the bubbling stage, and do not intercept event bubbling.        |
| `catch`         | Listen to events in the bubbling stage and intercept event bubbling.                |
| `capture-bind`  | Listen to events in the capture phase, do not intercept event capture and bubbling. |
| `capture-catch` | Listen to events in the capture phase, intercept event capture and bubbling.        |
| `global-bind`   | Listen to events across components.                                                 |

In particular, when the event handler is a [main thread script](/react/main-thread-script.md), you need to add the `main-thread:` prefix before the event handler property name to ensure that the handler is executed in the main thread.

## Event response chain

The event response chain refers to a linked list of nodes that can respond to events. Generally speaking, the event response chain consists of the path from the root node of the page to the node where the action is actually triggered. However, for non-[touch events](/api/lynx-api/event/touch-event.md), the event response chain only contains the node where the action is actually triggered.

**Example 1:**

**This is an example below: event**

**Entry:** `src/event_chain`
**Bundle:** `dist/event_chain.lynx.bundle` | Web: `dist/event_chain.web.bundle`

```tsx {50,65,78,95,108}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [tap, setTap] = useState<boolean>(false);
  const [tap1, setTap1] = useState<boolean>(false);
  const [tap11, setTap11] = useState<boolean>(false);
  const [tap2, setTap2] = useState<boolean>(false);
  const [tap22, setTap22] = useState<boolean>(false);

  function handleTap(e: TouchEvent) {
    if (e.currentTarget.id === "tap") {
      setTap(!tap);
    }
    if (e.currentTarget.id === "tap1") {
      setTap1(!tap1);
    }
    if (e.currentTarget.id === "tap11") {
      setTap11(!tap11);
    }
    if (e.currentTarget.id === "tap2") {
      setTap2(!tap2);
    }
    if (e.currentTarget.id === "tap22") {
      setTap22(!tap22);
    }
  }

  function handletouchstart(e: TouchEvent) {
    setTap(false);
    setTap1(false);
    setTap11(false);
    setTap2(false);
    setTap22(false);
  }

  return (
    <view
      id="tap"
      style={{
        width: "calc(100% - 40px)",
        height: "90%",
        margin: "20px",
        borderRadius: "10px",
        boxShadow: "0 0 5px 5px #ccc",
        backgroundColor: tap ? "rgb(255, 179, 0)" : "white",
        justifyContent: "center",
        alignItems: "center",
      }}
      bindtap={handleTap}
      capture-bindtouchstart={handletouchstart}
    >
      <view
        id="tap1"
        style={{
          width: "70%",
          height: "40%",
          marginBottom: "25px",
          borderRadius: "10px",
          boxShadow: "0 0 5px 5px #ccc",
          backgroundColor: tap1 ? "rgb(255, 179, 0)" : "white",
          justifyContent: "center",
          alignItems: "center",
        }}
        bindtap={handleTap}
      >
        <view
          id="tap11"
          style={{
            width: "60%",
            height: "45%",
            borderRadius: "10px",
            boxShadow: "0 0 5px 5px #ccc",
            backgroundColor: tap11 ? "rgb(255, 179, 0)" : "white",
            justifyContent: "center",
            alignItems: "center",
          }}
          bindtap={handleTap}
        >
          <text user-interaction-enabled={false} style={{ color: "green" }}>click me 1</text>
        </view>
      </view>
      <view
        id="tap2"
        style={{
          width: "70%",
          height: "40%",
          marginTop: "25px",
          borderRadius: "10px",
          boxShadow: "0 0 5px 5px #ccc",
          backgroundColor: tap2 ? "rgb(255, 179, 0)" : "white",
          justifyContent: "center",
          alignItems: "center",
        }}
        bindtap={handleTap}
      >
        <view
          id="tap22"
          style={{
            width: "60%",
            height: "45%",
            borderRadius: "10px",
            boxShadow: "0 0 5px 5px #ccc",
            backgroundColor: tap22 ? "rgb(255, 179, 0)" : "white",
            justifyContent: "center",
            alignItems: "center",
          }}
          bindtap={handleTap}
        >
          <text user-interaction-enabled={false} style={{ color: "red" }}>click me 2</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, when the user clicks on the page, the background color of the node on the event response chain will be set to orange.

## Event capture

The event will go through two stages in the event response chain: event capture and event bubbling. In the event capture stage, the event will start from the root node of the page and propagate down along the event response chain until the node where the action is actually triggered. In the event capture stage, nodes with the event handler property of the `capture-bind` type set can listen to the corresponding event.

**Example 2:**

**This is an example below: event**

**Entry:** `src/event_capture`
**Bundle:** `dist/event_capture.lynx.bundle` | Web: `dist/event_capture.web.bundle`

```tsx {7-9,14}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [cnt, setCnt] = useState<number>(0);

  function handleTap(e: TouchEvent) {
    setCnt(cnt + 1);
  }

  return (
    <view
      style={{ width: "100%", height: "90%" }}
      capture-bindtap={handleTap}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text>
          Counts the number of clicks on a page: <text style={{ color: "red" }}>{cnt}</text>
        </text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "calc(100% - 150px)" }}
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
                  Math.floor(Math.random() * 256)
                })`,
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
            >
              <text>item-{item + 1}</text>
            </view>
          );
        })}
      </scroll-view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, since event propagation starts from the capture phase, and the capture phase starts from the root node, when the user clicks on the page, the root node can always listen to the `tap` event, thereby realizing the function of counting the number of page clicks.

## Event bubble

In the event bubbling phase, the event will propagate upward along the event response chain from the node where the action is actually triggered, until the root node of the page. In the event bubbling phase, nodes with the `bind` type event handler attribute set can listen to the corresponding event.

**Example 3**

**This is an example below: event**

**Entry:** `src/event_bubble`
**Bundle:** `dist/event_bubble.lynx.bundle` | Web: `dist/event_bubble.web.bundle`

```tsx {7-12,23}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [bgColor, setBgColor] = useState<string>("white");

  function handleTap(e: TouchEvent) {
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        backgroundColor: bgColor,
        justifyContent: "center",
        alignItems: "center",
      }}
      bindtap={handleTap}
    >
      <view
        style={{
          width: "100px",
          height: "50px",
          borderRadius: "5px",
          backgroundColor: "gray",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text style={{ color: "red" }}>click me</text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, when the user clicks any node on the page, the event will bubble from the child node to the parent node by default. Therefore, the parent node can always listen to the `tap` event and change the background color of the node.

## Event interception

During the process of event propagation, the event can be intercepted midway to prevent the event from continuing to propagate. When the `catch` type event handler property is set on the node, the event will be intercepted when it propagates to the node and will no longer propagate.

**Example 4**

**This is an example below: event**

**Entry:** `src/event_static_catch`
**Bundle:** `dist/event_static_catch.lynx.bundle` | Web: `dist/event_static_catch.web.bundle`

```tsx {7-12,23,34}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [bgColor, setBgColor] = useState<string>("white");

  function handleTap(e: TouchEvent) {
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        backgroundColor: bgColor,
        justifyContent: "center",
        alignItems: "center",
      }}
      bindtap={handleTap}
    >
      <view
        style={{
          width: "100px",
          height: "50px",
          borderRadius: "5px",
          backgroundColor: "gray",
          justifyContent: "center",
          alignItems: "center",
        }}
        catchtap={(e: TouchEvent) => {}}
      >
        <text style={{ color: "red" }}>click me</text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, since the `click me` area sets the static interception `tap` event, the event will bubble to the parent node and the background color of the node will change only when the non-`click me` area is clicked.

## Prevent Event Propagation in Main Thread Script

When used with [Main Thread Script](/react/main-thread-script.md), event propagation can be prevented by calling the [`stopPropagation`](/api/lynx-api/event/event.md#stoppropagation) method of the event object.

**Example 5:**

**This is an example below: event**

**Entry:** `src/event_stop_propagation`
**Bundle:** `dist/event_stop_propagation.lynx.bundle` | Web: `dist/event_stop_propagation.web.bundle`

```tsx {34}
import { root, runOnBackground, useState } from "@lynx-js/react";
import "./index.css";
import type { MainThread } from "@lynx-js/types";

export default function App() {
  const [active, setActive] = useState({ outer: false, middle: false, inner: false });

  // Utility to flash a box when it's clicked
  const flashBT = (key: "outer" | "middle" | "inner") => {
    setActive((prev) => ({ ...prev, [key]: true }));
    setTimeout(() => setActive((prev) => ({ ...prev, [key]: false })), 200);
  };

  // Utility to flash a box when it's clicked
  const flash = (
    key: "outer" | "middle" | "inner",
  ) => {
    "main thread";
    runOnBackground(flashBT)(key);
  };

  function handleOuterTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("outer");
  }

  function handleMiddleTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("middle");
  }

  function handleInnerTap(e: MainThread.TouchEvent) {
    "main thread";
    e.stopPropagation(); // ✋ stop event bubbling
    flash("inner");
  }

  return (
    <view
      main-thread:bindtap={handleOuterTap}
      className={`box outer ${active.outer ? "active" : ""}`}
    >
      <text>Outer {active.outer ? "(active)" : "(inactive)"}</text>
      <view
        main-thread:bindtap={handleMiddleTap}
        className={`box middle ${active.middle ? "active" : ""}`}
      >
        <text>Middle {active.middle ? "(active)" : "(inactive)"}</text>
        <view
          main-thread:bindtap={handleInnerTap}
          className={`box inner ${active.inner ? "active" : ""}`}
        >
          <text>Inner (click me, stops propagation) {active.inner ? "(active)" : "(inactive)"}</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In the above example, click the inner will not trigger the `tap` event of the outer.

## Cross-component event listening no Web
Generally speaking, when a node is not on the event response chain, the event cannot be monitored. Lynx provides a way to monitor cross-component events, allowing developers to register event monitoring on any node and receive corresponding events.

For example, developers can set the event handler property of the `global-bind` type on a node to listen to the `tap` event. When any node is clicked, the node can listen to the `tap` event, thereby realizing the function of counting the number of page clicks.

**Example 5:**

**This is an example below: event**

**Entry:** `src/event_global_bind`
**Bundle:** `dist/event_global_bind.lynx.bundle` | Web: `dist/event_global_bind.web.bundle`

```tsx {8-10,12-14,19-20,47-48}
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export function ComponentA() {
  const [scrollContainer, setScrollContainer] = useState<string>("");
  const [cnt, setCnt] = useState<number>(0);

  function handleScroll(e: TouchEvent) {
    setScrollContainer(e.target.id);
  }

  function handleTap(e: TouchEvent) {
    setCnt(cnt + 1);
  }

  return (
    <view
      style={{ width: "100%", height: "100%", justifyContent: "center", alignItems: "center" }}
      global-bindscroll={handleScroll}
      global-bindtap={handleTap}
    >
      <text>
        Counts the number of clicks on a page: <text style={{ color: "red" }}>{cnt}</text>
      </text>
      <text>
        Current scroll container: <text style={{ color: "green" }}>{scrollContainer}</text>
      </text>
    </view>
  );
}

export function ComponentB() {
  return (
    <view
      style={{
        width: "calc(100% - 10px)",
        height: "calc(100% - 45px)",
        marginTop: "40px",
        marginLeft: "5px",
        marginRight: "5px",
        marginBottom: "5px",
      }}
    >
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "50%", borderWidth: "2px" }}
        id="scroll-1"
        bindscroll={(e) => {}}
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "200px",
                margin: "5px",
                backgroundColor: "orange",
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
            >
              <text>scroll-1-item-{item + 1}</text>
            </view>
          );
        })}
      </scroll-view>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "calc(50% - 10px)", marginTop: "10px", borderWidth: "2px" }}
        id="scroll-2"
        bindscroll={(e) => {}}
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "200px",
                margin: "5px",
                backgroundColor: "purple",
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
            >
              <text>scroll-2-item-{item + 1}</text>
            </view>
          );
        })}
      </scroll-view>
    </view>
  );
}

export default function App() {
  return (
    <view style={{ width: "100%", height: "90%" }}>
      <view style={{ width: "100%", height: "150px", backgroundColor: "yellow" }}>
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentA</text>
        </view>
        <ComponentA />
      </view>
      <view style={{ width: "100%", height: "calc(100% - 165px)", marginTop: "15px", backgroundColor: "#ccc" }}>
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentB</text>
        </view>
        <ComponentB />
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



It should be noted that for non-[touch events](/api/lynx-api/event/touch-event.md), the event handler property of the non-cross-component event listening type needs to be set on the monitored node. In addition, developers can also set `global-target` on the node to specify that only events with a specific value of the node [`id`](/api/elements/built-in/view.md#id) are listened (type is `string`, multiple [`id`](/api/elements/built-in/view.md#id) can be specified, separated by commas).

## Event aspect interface

Sometimes, developers may need to uniformly listen to and handle events of a specific type somewhere, and do not rely on component registration event listeners. For example, count all triggered `tap` events on the page. At this time, developers can use the event aspect interface ([`beforePublishEvent`](/api/lynx-api/lynx/lynx-before-publish-event.md)) provided by Lynx to implement the corresponding function.

**Example 6:**

**This is an example below: event**

**Entry:** `src/event_aop`
**Bundle:** `dist/event_aop.lynx.bundle` | Web: `dist/event_aop.web.bundle`

```tsx {7-12,65}
import { root, useMemo, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export default function App() {
  const [cnt, setCnt] = useState<number>(0);

  useMemo(() => {
    "background-only";
    lynx.beforePublishEvent.add("tap", () => {
      setCnt((cnt) => cnt + 1);
    });
  }, []);

  return (
    <view
      style={{ width: "100%", height: "90%" }}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        <text>
          Counts the number of clicks on a page: <text style={{ color: "red" }}>{cnt}</text>
        </text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "calc(100% - 150px)" }}
      >
        {[0, 1].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: "yellow",
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
            >
              <text>{"Don't listen tap event-" + (item + 1)}</text>
            </view>
          );
        })}
        {[0, 1, 2, 3].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: "orange",
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
              bindtap={(e: TouchEvent) => {}}
            >
              <text>{"Listen tap event-" + (item + 1)}</text>
            </view>
          );
        })}
      </scroll-view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



The event aspect interface is a type of aspect programming. By injecting the corresponding interface at the event trigger point, the event is forwarded to a certain place when a specific event is triggered. This interface is only implemented in the BTS context. Therefore, it can only be used in the background thread, and the corresponding event can only be listened to when the event processing function is triggered.

## `GlobalEventEmitter`

Sometimes, developers may need to pass events between different elements and components, or need to pass events between the client and the front end, and do not rely on the element to register event listeners. At this time, developers can use `GlobalEventEmitter` to achieve global scope transmission of events in a page.

Developers can obtain the `GlobalEventEmitter` object through [`lynx.getJSModule`](/api/lynx-api/lynx/lynx-get-js-module.md), which provides the following interfaces:

| Function name        | Function description                                                                        | Function parameter                |
| -------------------- | ------------------------------------------------------------------------------------------- | --------------------------------- |
| `addListener`        | Subscribe to events and register event listeners.                                           | `(eventName, listener, context?)` |
| `removeListener`     | Remove the specified listener for a specific event.                                         | `(eventName, listener)`           |
| `removeAllListeners` | Remove all listeners for a specific event.                                                  | `(eventName)`                     |
| `toggle`             | Broadcast an event with a specified event name, supporting multiple transparent parameters. | `(eventName, ...data)`            |
| `trigger`            | Broadcasts an event with a specified event name, supporting a transparent parameter.        | `(eventName, params)`             |

Note that `GlobalEventEmitter` is only supported in the BTS context, so it can only be used in background threads.

### Event broadcast

Developers can broadcast events through `GlobalEventEmitter` to send events to the front end.

In the following example, when the user clicks on the page, the developer broadcasts the event by calling the `toggle` method of `GlobalEventEmitter`, so that the click event is propagated from component `ComponentA` to `ComponentB`.

**Example 7:**

**This is an example below: event**

**Entry:** `src/event_emitter_toggle`
**Bundle:** `dist/event_emitter_toggle.lynx.bundle` | Web: `dist/event_emitter_toggle.web.bundle`

```tsx {8-10,22-24,41}
import { root, useState } from "@lynx-js/react";
import { useLynxGlobalEventListener } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";

export function ComponentA() {
  const [eventLog, setEventlog] = useState<string>("");

  useLynxGlobalEventListener("tapitem", (e) => {
    setEventlog((e as TouchEvent).target.dataset.item);
  });

  return (
    <view style={{ width: "100%", height: "100%", justifyContent: "center", alignItems: "center" }}>
      <text>
        Tap on item-<text style={{ color: "red" }}>{eventLog}</text>
      </text>
    </view>
  );
}

export function ComponentB() {
  function handleTap(e: TouchEvent) {
    lynx.getJSModule("GlobalEventEmitter").toggle("tapitem", e);
  }

  return (
    <scroll-view
      scroll-orientation="vertical"
      style={{ width: "100%", height: "calc(100% - 40px)", marginTop: "40px" }}
    >
      {[0, 1, 2, 3, 4, 5, 6].map((item) => {
        return (
          <view
            style={{
              width: "calc(100% - 10px)",
              height: "200px",
              margin: "5px",
              backgroundColor: "orange",
              borderRadius: "5px",
              justifyContent: "center",
              alignItems: "center",
            }}
            data-item={item + 1}
            bindtap={handleTap}
          >
            <text user-interaction-enabled={false}>item-{item + 1}</text>
          </view>
        );
      })}
    </scroll-view>
  );
}

export default function App() {
  return (
    <view style={{ width: "100%", height: "90%" }}>
      <view
        style={{ width: "100%", height: "150px", backgroundColor: "yellow" }}
      >
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentA</text>
        </view>
        <ComponentA />
      </view>
      <view
        style={{
          width: "100%",
          height: "calc(100% - 165px)",
          marginTop: "15px",
          backgroundColor: "#ccc",
        }}
      >
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentB</text>
        </view>
        <ComponentB />
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



For the client, the example is as follows:

iOSAndroidHarmonyOS```objective-c
// You can call the sendGlobalEvent function of LynxContext
// The first parameter is the event name monitored by the front end, and the second parameter is the data received by the front end
[LynxContext sendGlobalEvent:@"eventName" withParams:args];
// Or call the sendGlobalEvent function of LynxView
[LynxView sendGlobalEvent:@"eventName" withParams:args];
```
```java
// You can call the sendGlobalEvent function of LynxContext
// The first parameter is the event name monitored by the front end, and the second parameter is the data received by the front end
LynxContext.sendGlobalEvent("eventName", args);
// Or call the sendGlobalEvent function of LynxView
LynxView.sendGlobalEvent("eventName", args);
```
```js
// You can call the sendGlobalEvent function of LynxContext
// The first parameter is the event name monitored by the front end, and the second parameter is the data received by the front end
LynxContext.sendGlobalEvent('eventName', args);
```
## 


### Event subscribe

Developers can also subscribe to events through the `addListener` method of `GlobalEventEmitter` to receive events from the front end and client.

In the following example, users can receive the [`onWindowResize`](/api/lynx-api/event/global-event.md#onwindowresize) event sent by Lynx, which is triggered when the Lynx page size changes.

**Example 8:**

**This is an example below: event**

**Entry:** `src/event_emitter_listen`
**Bundle:** `dist/event_emitter_listen.lynx.bundle` | Web: `dist/event_emitter_listen.web.bundle`

```tsx {7-9}
import { root, useState } from "@lynx-js/react";
import { useLynxGlobalEventListener } from "@lynx-js/react";

export default function App() {
  const [eventLog, setEventLog] = useState<string>("");
  useLynxGlobalEventListener("onWindowResize", (e) => {
    setEventLog("" + e);
  });

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        borderWidth: "1px",
        borderColor: "red",
        justifyContent: "center",
        alignItems: "center",
      }}
    >
      <text>Listen onWindowResize Event:</text>
      <text>
        LynxView's width has changed to: <text style={{ color: "red" }}>{eventLog}</text>
      </text>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```





---
url: /guide/interaction/event-handling/manipulating-element.react.md
---

# Direct Manipulation of Elements

In daily development, modern front-end frameworks handle most element tree and node property updates for us. However, there are times when you need to manipulate elements directly, such as controlling media players, manipulating view behavior, getting element information, or directly modifying styles.

These functionalities are typically implemented by components on the client side, and you need to access them through element references.

## Manipulating Elements in Background Thread

### Example: Auto-scrolling

Let's try a simple requirement - auto-scrolling the page. We need to call the [`autoScroll`] method of the `<scroll-view />` element:

**This is an example below: element-manipulation**

**Entry:** `src/ref-background`
**Bundle:** `dist/ref-background.lynx.bundle`

```tsx {7,10-18,28}
import { useRef } from "@lynx-js/react";
import type { NodesRef } from "@lynx-js/types";

import { ScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  const scrollRef = useRef<NodesRef>(null);

  const handleTap = () => {
    scrollRef.current
      ?.invoke({
        method: "autoScroll",
        params: {
          rate: 120,
          start: true,
        },
      })
      .exec();
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        padding: "10px",
        display: "linear",
        marginTop: "20px",
      }}
    >
      <view bindtap={handleTap}>
        <text
          style={{
            fontSize: "20px",
            height: "40px",
            paddingLeft: "10px",
            marginTop: "10px",
          }}
        >
          Tap me to enable auto-scroll
        </text>
      </view>
      <scroll-view
        ref={scrollRef}
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => (
          <ScrollItem width="calc(100% - 10px)" height="100px" index={index} />
        ))}
      </scroll-view>
    </view>
  );
};

```



This example demonstrates two steps for manipulating elements: creating a reference using `useRef` and binding it to the target element using `ref={scrollRef}`, then calling the element method using `invoke()` in the event handler.

### Obtaining a Reference to an Element Using `ref`

If you're familiar with React, you'll find that using `ref` is very similar:

```tsx
const nodeRef = useRef<NodesRef>(null);
// ...
<text ref={nodeRef} />;
```

However, note that in Lynx, the type of node reference is [`NodesRef`], which is different from React. If you want to learn more about using references, you can refer to [Manipulating the Element with Refs](https://react.dev/learn/manipulating-the-dom-with-refs).

### Manipulating an Element via Its Reference

After obtaining a node reference, let's see how to use it. [`NodesRef`] provides a series of useful APIs.

For example, you can use [`NodesRef.invoke()`](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) to call the element's methods. Each component provides specific methods that are implemented on the client side and exposed for front-end use.

When calling a method, you can pass required parameters through `params`, handle successful results using the `success` callback, and handle potential errors using the `fail` callback. Remember to call [`exec()`](/api/lynx-api/selector-query/selector-query-exec.md) at the end to submit the operation for actual execution:

```tsx
ref
  .invoke({
    method: 'boundingClientRect',
    params: {
      relativeTo: 'screen',
    },
    success: (res) => {
      // Handle successful result
      const { left, top, width, height } = res;
    },
    fail: (err) => {
      // Handle potential errors
      console.error('Failed to get element position:', err);
    },
  })
  .exec();
```

## Manipulating Elements in Main Thread

If you want better performance and more intuitive code, you can consider manipulating elements in the main thread. It offers lower operation latency with faster UI response and more natural API calls.

Let's see how to implement the same functionality in the main thread:

**This is an example below: element-manipulation**

**Entry:** `src/ref-main-thread`
**Bundle:** `dist/ref-main-thread.lynx.bundle`

```tsx {7,10-14,19,25}
import { useMainThreadRef } from "@lynx-js/react";
import { MainThread } from "@lynx-js/types";

import { ScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  const scrollRef = useMainThreadRef<MainThread.Element>(null);

  const handleTap = () => {
    "main thread";
    scrollRef.current?.invoke("autoScroll", {
      rate: 120,
      start: true,
    });
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        padding: "10px",
        display: "linear",
        marginTop: "20px",
      }}
    >
      <view main-thread:bindtap={handleTap}>
        <text
          style={{
            fontSize: "20px",
            height: "40px",
            paddingLeft: "10px",
            marginTop: "10px",
          }}
        >
          Tap me to enable auto-scroll
        </text>
      </view>
      <scroll-view
        main-thread:ref={scrollRef}
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => (
          <ScrollItem width="calc(100% - 10px)" height="100px" index={index} />
        ))}
      </scroll-view>
    </view>
  );
};

```



The main changes here are: node operations need to be written in [main thread functions](/api/react/Document.directives.md#main-thread); using [`useMainThreadRef`] and `main-thread:ref` to get the main thread node reference; the node reference type becomes [`MainThread.Element`], which provides various methods for manipulating nodes; and we used [`MainThread.Element.invoke()`] to call the node's [`autoScroll`] method.

## Obtaining Element References via Selectors

In certain scenarios, such as when you need to batch operate on elements or dynamically find elements, using selectors can be particularly useful.

### Background Thread

In the background thread, we can use the [`SelectorQuery`] API to find elements. Let's look at an example:

**This is an example below: element-manipulation**

**Entry:** `src/selector-query-background`
**Bundle:** `dist/selector-query-background.lynx.bundle`

```tsx {5-6}
import { ScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  const handleTap = () => {
    lynx
      .createSelectorQuery()
      .select("scroll-view")
      .invoke({
        method: "autoScroll",
        params: {
          rate: 120,
          start: true,
        },
      })
      .exec();
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        padding: "10px",
        display: "linear",
        marginTop: "20px",
      }}
    >
      <view bindtap={handleTap}>
        <text
          style={{
            fontSize: "20px",
            height: "40px",
            paddingLeft: "10px",
            marginTop: "10px",
          }}
        >
          Tap me to enable auto-scroll
        </text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => (
          <ScrollItem width="calc(100% - 10px)" height="100px" index={index} />
        ))}
      </scroll-view>
    </view>
  );
};

```



Using selectors is simple: first create a query object using [`lynx.createSelectorQuery()`], then use methods like [`select()`] to find elements. To learn about all supported selectors, you can check our [API documentation](/api/lynx-api/selector-query.md).

### Main Thread

When manipulating elements in the main thread, things become even simpler. You can use the browser-like [`lynx.querySelector()`] API:

**This is an example below: element-manipulation**

**Entry:** `src/selector-query-main-thread`
**Bundle:** `dist/selector-query-main-thread.lynx.bundle`

```tsx {6-9}
import { ScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  const handleTap = () => {
    "main thread";
    lynx.querySelector("scroll-view")?.invoke("autoScroll", {
      rate: 120,
      start: true,
    });
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        padding: "10px",
        display: "linear",
        marginTop: "20px",
      }}
    >
      <view main-thread:bindtap={handleTap}>
        <text
          style={{
            fontSize: "20px",
            height: "40px",
            paddingLeft: "10px",
            marginTop: "10px",
          }}
        >
          Tap me to enable auto-scroll
        </text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => (
          <ScrollItem width="calc(100% - 10px)" height="100px" index={index} />
        ))}
      </scroll-view>
    </view>
  );
};

```



## Obtaining a Reference to the Event Target Element

When handling events, we often need to manipulate the element that triggered the event.

### Main Thread

In the main thread, you can get the element reference directly from the event object. Similar to browsers, we provide [`target`] and [`currentTarget`] properties:

**This is an example below: element-manipulation**

**Entry:** `src/event-main-thread`
**Bundle:** `dist/event-main-thread.lynx.bundle`

```tsx {6-9}
import type { MainThread } from "@lynx-js/types";

export const App = () => {
  function handleTap(e: MainThread.TouchEvent) {
    "main thread";
    e.currentTarget.setStyleProperty(
      "color",
      "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))",
    );
  }

  return (
    <view>
      <text
        style={{
          fontSize: "20px",
          height: "40px",
          paddingLeft: "10px",
          marginTop: "10px",
        }}
        main-thread:bindtap={handleTap}
      >
        Tap me to change my color!
      </text>
    </view>
  );
};

```



Here we used [`MainThread.Element.setStyleProperty()`] to modify styles.

## Using `getElementById` API

[`getElementById`] is currently our main API for handling animations and CSS variables. Although this is a traditional interface, it's still the best choice when you need to execute JavaScript animations or dynamically modify CSS variable values.

To learn more about usage, you can check [Animation API documentation](/api/lynx-api/lynx/lynx-animate-api.md) and [CSS Variables Operation Guide](/api/css/properties/css-variable.md). We are developing more modern APIs to replace [`getElementById`], stay tuned.

[`autoScroll`]: /api/elements/built-in/scroll-view.md#autoscroll

[`currentTarget`]: /api/lynx-api/event/event.md#currentTarget

[`getElementById`]: /api/lynx-api/lynx/lynx-get-element-by-id.md

[`lynx.createSelectorQuery()`]: /api/lynx-api/lynx/lynx-create-selector-query.md

[`lynx.querySelector()`]: /api/lynx-api/main-thread/lynx-query-selector.md

[`MainThread.Element`]: /api/lynx-api/main-thread/main-thread-element.md

[`MainThread.Element.invoke()`]: /api/lynx-api/main-thread/main-thread-element.md#elementinvoke

[`MainThread.Element.setStyleProperty()`]: /api/lynx-api/main-thread/main-thread-element.md#elementsetstyleproperty

[`NodesRef`]: /api/lynx-api/nodes-ref.md

[`select()`]: /api/lynx-api/selector-query/selector-query-select.md

[`SelectorQuery`]: /api/lynx-api/selector-query.md

[`target`]: /api/lynx-api/event/event.md#target

[`useMainThreadRef`]: /api/react/Function.useMainThreadRef.md



---
url: /guide/interaction/visibility-detection.md
---

# Visibility detection

Lynx provides two capabilities for detecting node visibility. One is Lynx's unique exposure capability, which allows developers to easily monitor whether a node is exposed. The other is a Web-like intersection observer, which is a more atomic capability that allows developers to monitor the intersection positions of nodes.

## Detect whether a node is exposed

When developers are mainly concerned about whether multiple nodes are on the screen and not the intersection of nodes, and want to write code quickly, they can use [exposure ability](/guide/interaction/visibility-detection/exposure-ability.md).

[Exposure ability](/guide/interaction/visibility-detection/exposure-ability.md) is a declarative interface. Developers can specify the nodes that need to monitor exposure through the [`exposure-id`](/api/elements/built-in/view.md#exposure-id) attribute. When the node appears, the exposure event `exposure` is triggered, and when the node disappears, the anti-exposure event `disexposure` is triggered.

In the following example, the developer monitors whether the node is exposed/anti-exposed and displays the node [`exposure-id`](/api/elements/built-in/view.md#exposure-id) visible on the screen in real time.

**Example 2:**

**This is an example below: event**

**Entry:** `src/visibility_expose`
**Bundle:** `dist/visibility_expose.lynx.bundle` | Web: `dist/visibility_expose.web.bundle`

```tsx {8-12,14-21,62}
import { root, useState } from "@lynx-js/react";
import { useLynxGlobalEventListener } from "@lynx-js/react";

export default function App() {
  const [eventLog, setEventLog] = useState<string>("");

  useLynxGlobalEventListener("exposure", (e) => {
    (e as { "exposure-id": string }[]).forEach((item) => {
      setEventLog((log) => log + (log === "" ? "" : ", ") + item["exposure-id"]);
    });
  });

  useLynxGlobalEventListener("disexposure", (e) => {
    let log = eventLog.split(", ");
    (e as { "exposure-id": string }[]).forEach((item) => {
      log = log.filter(id => id !== item["exposure-id"]);
    });
    log.sort();
    setEventLog(log.join(", "));
  });

  return (
    <view
      style={{ width: "100%", height: "90%" }}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
        }}
      >
        <text>Exposed node:</text>
        <text style={{ color: "red" }}>{eventLog}</text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{
          width: "100%",
          height: "calc(100% - 165px)",
          backgroundColor: "yellow",
          marginTop: "15px",
          paddingTop: "40px",
        }}
        id="container"
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
                  Math.floor(Math.random() * 256)
                })`,
                borderRadius: "5px",
                alignItems: "center",
              }}
              exposure-id={`scroll-item-${item + 1}`}
            >
              <text>scroll-item-{item + 1}</text>
            </view>
          );
        })}
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>scroll container</text>
        </view>
      </scroll-view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Since the exposure capability focuses on whether the node is visible, the node visibility requirement here is more stringent. In addition, since [exposure capability](/guide/interaction/visibility-detection/exposure-ability.md) is a declarative interface, when developers need to monitor the exposure of multiple nodes, they only need to add the [`exposure-id`](/api/elements/built-in/view.md#exposure-id) attribute to the node.

## Detect whether nodes intersect

When developers only need to check whether nodes intersect, and do not care whether the nodes are on the screen, they can use the [intersection observer](/guide/interaction/visibility-detection/intersection-observer.md).

The [intersection observer](/guide/interaction/visibility-detection/intersection-observer.md) is used to detect whether the target node intersects with the reference node and the target node intersects with the ancestor node. Developers can flexibly specify the reference node, reference node boundary scaling value, node intersection ratio threshold, etc., to achieve a more flexible definition of node visibility.

In the following example, the developer monitors whether the parent node and the child node intersect, and outputs the intersecting child node [`id`](/api/elements/built-in/view.md#id) and the intersection position when they intersect.

**Example 1:**

**This is an example below: event**

**Entry:** `src/visibility_intersection`
**Bundle:** `dist/visibility_intersection.lynx.bundle` | Web: `dist/visibility_intersection.web.bundle`

```tsx {8-24}
import { root, useState } from "@lynx-js/react";
import type { IntersectionObserver, ObserveCallbackResult, TouchEvent } from "@lynx-js/types";

export default function App() {
  const [eventLog, setEventLog] = useState<string>("");
  let observer: IntersectionObserver | null = null;

  function handleTap(e: TouchEvent) {
    "background only";
    setEventLog("");
    if (observer == null) {
      observer = lynx.createIntersectionObserver({ componentId: "" }, { thresholds: [] });
      observer.relativeTo("#container");
      for (let i = 1; i <= 7; i++) {
        observer.observe("#view-item-" + i, (res: ObserveCallbackResult) => {
          if (res.isIntersecting) {
            let rect = res.intersectionRect;
            let rect_str = ", location: [" + rect.left + ", " + rect.top + ", " + rect.right + ", " + rect.bottom + "]";
            setEventLog((log) => log + (log === "" ? "node: " : "\nnode: ") + res.observerId + rect_str);
          }
        });
      }
    }
  }

  return (
    <view
      style={{ width: "100%", height: "90%", overflow: "hidden" }}
      bindtap={(e) => {
        handleTap(e);
      }}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
        }}
      >
        <text>Click the page to get intersected nodes:</text>
        <text style={{ color: "red" }}>{eventLog}</text>
      </view>
      <view
        style={{
          width: "100%",
          height: "calc(100% - 165px)",
          paddingTop: "40px",
          marginTop: "15px",
          backgroundColor: "yellow",
        }}
        id="container"
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                borderRadius: "5px",
                backgroundColor: `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
                  Math.floor(Math.random() * 256)
                })`,
                alignItems: "center",
              }}
              id={`view-item-${item + 1}`}
            >
              <text>view-item-{item + 1}</text>
            </view>
          );
        })}
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>view container</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



The node visibility here only requires the target node and the reference node to intersect, without requiring the target node to be on the screen, and there is no need to specify the reference node as a scroll container. In addition, since the [intersection observer](/guide/interaction/visibility-detection/intersection-observer.md) is an imperative interface, when developers need to monitor the intersection of multiple nodes, redundant code needs to be written.

## Summary

So far, you have learned how to detect whether nodes are intersecting or whether nodes are exposed.

For developers, when the focus is on whether a node is on the screen and you want to easily write exposure monitoring code for multiple nodes, you can use [Exposure Ability](/guide/interaction/visibility-detection/exposure-ability.md). when the focus is on whether nodes intersect and where they intersect, or when you need to flexibly define the visibility of nodes, you can use [Intersection Observer](/guide/interaction/visibility-detection/intersection-observer.md).



---
url: /guide/interaction/visibility-detection/exposure-ability.md
---

# Exposure Ability

The exposure capability provides a capability to observe changes in the visibility of a target node. When a target node changes from invisible to visible, an exposure event is triggered. Otherwise, an anti-exposure event is triggered.

Developers can monitor the exposure/anti-exposure events of nodes by setting relevant properties for the target nodes to be observed, thereby achieving requirements such as point reporting and `UI` lazy loading.

The exposure capability observes changes in node visibility through timed exposure detection tasks. The visibility of a node depends on the following factors:

- Visibility of the target node: The target node itself has width and height and is opaque, and the parent node has no clipping with zero width or height.
- Viewport intersection of the target node: The target node intersects with the parent scroll container, `Lynxview`, and the viewport of the screen.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/exposure-ability.png)
## Monitor exposure of the entire page

When developers need to monitor exposure/anti-exposure events of nodes in the entire page, they can subscribe to the exposure event [`exposure`](/api/lynx-api/event/global-event.md#exposure) and anti-exposure event [`disexposure`](/api/lynx-api/event/global-event.md#disexposure) of the node with the [`exposure-id`](/api/elements/built-in/view.md#exposure-id) attribute set through [`GlobalEventEmitter`](/guide/interaction/event-handling/event-propagation.md#globaleventemitter).

In the following example, the developer uses [`GlobalEventEmitter`](/guide/interaction/event-handling/event-propagation.md#globaleventemitter) to monitor whether the node in `ComponentA` is exposed, and outputs the exposed node [`exposure-id`](/api/elements/built-in/view.md#exposure-id) when it is exposed.

**Example 1:**

**This is an example below: event**

**Entry:** `src/visibility_expose_global`
**Bundle:** `dist/visibility_expose_global.lynx.bundle` | Web: `dist/visibility_expose_global.web.bundle`

```tsx {8-12,14-21,56}
import { root, useState } from "@lynx-js/react";
import { useLynxGlobalEventListener } from "@lynx-js/react";

export function ComponentA() {
  const [eventLog, setEventLog] = useState<string>("");

  useLynxGlobalEventListener("exposure", (e) => {
    (e as { "exposure-id": string }[]).forEach((item) => {
      setEventLog((log) => log + (log === "" ? "" : ", ") + item["exposure-id"]);
    });
  });

  useLynxGlobalEventListener("disexposure", (e) => {
    let log = eventLog.split(", ");
    (e as { "exposure-id": string }[]).forEach((item) => {
      log = log.filter(id => id !== item["exposure-id"]);
    });
    log.sort();
    setEventLog(log.join(", "));
  });

  return (
    <view style={{ width: "100%", height: "100%", justifyContent: "center", alignItems: "center" }}>
      <text>Exposed nodes:</text>
      <text style={{ color: "red" }}>{eventLog}</text>
    </view>
  );
}

export function ComponentB() {
  return (
    <view
      style={{
        width: "calc(100% - 10px)",
        height: "calc(100% - 45px)",
        marginTop: "40px",
        marginLeft: "5px",
        marginRight: "5px",
        marginBottom: "5px",
      }}
    >
      <scroll-view scroll-orientation="vertical" style={{ width: "100%", height: "100%", borderWidth: "2px" }}>
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: "orange",
                borderRadius: "5px",
                justifyContent: "center",
                alignItems: "center",
              }}
              exposure-id={`scroll-item-${item + 1}`}
            >
              <text>scroll-item-{item + 1}</text>
            </view>
          );
        })}
      </scroll-view>
    </view>
  );
}

export default function App() {
  return (
    <view style={{ width: "100%", height: "90%" }}>
      <view style={{ width: "100%", height: "150px", backgroundColor: "yellow" }}>
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentA</text>
        </view>
        <ComponentA />
      </view>
      <view style={{ width: "100%", height: "calc(100% - 165px)", marginTop: "15px", backgroundColor: "#ccc" }}>
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>ComponentB</text>
        </view>
        <ComponentB />
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



The format of the exposure/anti-exposure event is an array, which contains the target node information of each triggering exposure/anti-exposure event.

```json
[
  {
    "exposure-id": string,        // exposure-id set on the target node
    "exposure-scene": string,     // exposure-scene set on the target node
    "sign": string,               // uid of the target node
    "dataset": object,            // "data-" field set on the target node
    //......
  },
  //......
]
```

## Monitor the exposure of a certain node

When the developer only needs to listen to the exposure/anti-exposure events of a certain node, you can set the \[event handler]\(../event-handling/event-listening.mdx#Event handler properties) to listen to the node's [`uiappear`](/api/elements/built-in/view.md#binduiappear) and [`uidisappear`](/api/elements/built-in/view.md#binduidisappear) events.

In the following example, the developer sets the \[event handler]\(../event-handling/event-listening.mdx#Event handler properties) to listen to whether the node is exposed, and outputs the exposed node [`id`](/api/elements/built-in/view.md#id) when it is exposed.

**Example 2:**

**This is an example below: event**

**Entry:** `src/visibility_expose_custom`
**Bundle:** `dist/visibility_expose_custom.lynx.bundle` | Web: `dist/visibility_expose_custom.web.bundle`

```tsx {7-9,11-16,57-59}
import { root, useState } from "@lynx-js/react";
import type { Target, UIAppearanceDetailEvent } from "@lynx-js/types";

export default function App() {
  const [eventLog, setEventLog] = useState<string>("");

  function handleUIAppear(e: UIAppearanceDetailEvent<Target>) {
    setEventLog((log) => log + (log === "" ? "" : ", ") + e.detail.dataset.item);
  }

  function handleUIDisappear(e: UIAppearanceDetailEvent<Target>) {
    let log = eventLog.split(", ");
    log = log.filter(item => item !== e.detail.dataset.item);
    log.sort();
    setEventLog(log.join(", "));
  }

  return (
    <view
      style={{ width: "100%", height: "90%" }}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
        }}
      >
        <text>Exposed node:</text>
        <text style={{ color: "red" }}>{eventLog}</text>
      </view>
      <scroll-view
        scroll-orientation="vertical"
        style={{
          width: "100%",
          height: "calc(100% - 165px)",
          backgroundColor: "yellow",
          marginTop: "15px",
          paddingTop: "40px",
        }}
        id="container"
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                backgroundColor: `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
                  Math.floor(Math.random() * 256)
                })`,
                borderRadius: "5px",
                alignItems: "center",
              }}
              data-item={`scroll-item-${item + 1}`}
              binduiappear={handleUIAppear}
              binduidisappear={handleUIDisappear}
            >
              <text>scroll-item-{item + 1}</text>
            </view>
          );
        })}
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>scroll container</text>
        </view>
      </scroll-view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



The event parameter `e.detail` contains the node information.

```json
{
  "type": string                    // event name
  "detail":
    {
      "exposure-id": string,        // exposure-id set on the target node
      "exposure-scene": string,     // exposure-scene set on the target node
      "unique-id": string,          // uid of the target node
      "dataset": object,            // "data-" field set on the target node
      //......
    },
  //......
}
```

## Control exposure detection

Lynx also provides some properties and methods to control the execution of exposure detection tasks.

For example, developers can use the following methods to control whether the exposure detection task is started, stopped, and the execution frequency.

- [`lynx.stopExposure [BTS]`](/api/lynx-api/lynx/lynx-stop-exposure.md) or [`lynx.stopExposure [MTS]`](/api/lynx-api/main-thread/lynx-stop-exposure.md): Called in the main thread or background thread to stop exposure detection, that is, no longer detect the visibility of the target node, and no exposure/anti-exposure events will be triggered later.
- [`lynx.resumeExposure [BTS]`](/api/lynx-api/lynx/lynx-resume-exposure.md) or [`lynx.resumeExposure [MTS]`](/api/lynx-api/main-thread/lynx-resume-exposure.md): Called in the main thread or background thread to start exposure detection, that is, restart the visibility detection of the target node, and then trigger the exposure/anti-exposure events normally.
- [`lynx.setObserverFrameRate`](/api/lynx-api/lynx/lynx-set-observer-frame-rate.md): used to set the frequency of exposure detection.

In addition, developers can also control the exposure detection logic of the node by setting exposure-related properties on the node, such as [`exposure-screen-margin-*`](/api/elements/built-in/view.md#exposure-screen-margin-), [`exposure-ui-margin-*`](/api/elements/built-in/view.md#exposure-ui-margin-), [`exposure-area`](/api/elements/built-in/view.md#exposure-area), etc.



---
url: /guide/interaction/visibility-detection/intersection-observer.md
---

# Intersection Observer

The intersection observer provides a method to observe the intersection status between the target node and the reference node and between the target node and the ancestor node. When the intersection status changes, the corresponding callback is triggered.

Developers can observe the changes in the intersection status between the target node and the reference node through the following three steps:

1. Call [`lynx.createIntersectionObserver`](/api/lynx-api/lynx/lynx-create-intersection-observer.md) to create an [`IntersectionObserver`](/api/lynx-api/intersection-observer.md) object and specify the threshold list of intersection status changes.
2. Call the [`relativeTo`](/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/api/lynx-api/intersection-observer/intersection-observer-relative-to.md) object to specify the reference node.
3. Call the [`observe`](/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/api/lynx-api/intersection-observer.md) object to specify the target node and callback.
4. Call the [`disconnect`](/api/lynx-api/intersection-observer.md) method of the [`IntersectionObserver`](/api/lynx-api/intersection-observer/intersection-observer-disconnect.md) object to clear the target node and callback.

In the following example, the developer monitors whether the parent node and the child node intersect, and outputs the intersecting child node [`id`](/api/elements/built-in/view.md#id) and the intersection position when they intersect.

**This is an example below: event**

**Entry:** `src/visibility_intersection`
**Bundle:** `dist/visibility_intersection.lynx.bundle` | Web: `dist/visibility_intersection.web.bundle`

```tsx {8-24}
import { root, useState } from "@lynx-js/react";
import type { IntersectionObserver, ObserveCallbackResult, TouchEvent } from "@lynx-js/types";

export default function App() {
  const [eventLog, setEventLog] = useState<string>("");
  let observer: IntersectionObserver | null = null;

  function handleTap(e: TouchEvent) {
    "background only";
    setEventLog("");
    if (observer == null) {
      observer = lynx.createIntersectionObserver({ componentId: "" }, { thresholds: [] });
      observer.relativeTo("#container");
      for (let i = 1; i <= 7; i++) {
        observer.observe("#view-item-" + i, (res: ObserveCallbackResult) => {
          if (res.isIntersecting) {
            let rect = res.intersectionRect;
            let rect_str = ", location: [" + rect.left + ", " + rect.top + ", " + rect.right + ", " + rect.bottom + "]";
            setEventLog((log) => log + (log === "" ? "node: " : "\nnode: ") + res.observerId + rect_str);
          }
        });
      }
    }
  }

  return (
    <view
      style={{ width: "100%", height: "90%", overflow: "hidden" }}
      bindtap={(e) => {
        handleTap(e);
      }}
    >
      <view
        style={{
          width: "calc(100% - 10px)",
          height: "150px",
          margin: "5px",
          borderWidth: "2px",
        }}
      >
        <text>Click the page to get intersected nodes:</text>
        <text style={{ color: "red" }}>{eventLog}</text>
      </view>
      <view
        style={{
          width: "100%",
          height: "calc(100% - 165px)",
          paddingTop: "40px",
          marginTop: "15px",
          backgroundColor: "yellow",
        }}
        id="container"
      >
        {[0, 1, 2, 3, 4, 5, 6].map((item) => {
          return (
            <view
              style={{
                width: "calc(100% - 10px)",
                height: "150px",
                margin: "5px",
                borderRadius: "5px",
                backgroundColor: `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
                  Math.floor(Math.random() * 256)
                })`,
                alignItems: "center",
              }}
              id={`view-item-${item + 1}`}
            >
              <text>view-item-{item + 1}</text>
            </view>
          );
        })}
        <view style={{ position: "absolute" }}>
          <text style={{ color: "blue" }}>view container</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



For the specific syntax of the intersection observer, please refer to [`IntersectionObserver`](/api/lynx-api/intersection-observer.md).



---
url: /guide/interaction/networking.md
---

# Networking

Many mobile apps need to load resources from remote URLs. You might want to make a POST request to a REST API or fetch a large amount of static content from another server.

## Using Fetch

:::tip

This feature depends on the HTTP service provided by the integrated [Lynx Service](/guide/start/integrate-with-existing-apps.md).

:::

Lynx provides a [Fetch API](/api/lynx-api/global/fetch.md) that is compatible with the standard Web API. You can refer to the MDN guide on [Using Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) for more information.

This example app fetches and displays user posts from the [JSONPlaceholder API](https://jsonplaceholder.typicode.com/). It initializes with a loading state and triggers a Fetch API request to retrieve posts upon mounting. The fetched data is then displayed in a scrollable list, showing each post's ID and title. A "Loading..." message appears if the request is still in progress.

**This is an example below: networking**

**Entry:** `src/fetch`
**Bundle:** `dist/fetch.lynx.bundle`

```tsx
import { root, useEffect, useState } from "@lynx-js/react";
import "./index.scss";

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

const App = () => {
  const [isFetching, setFetching] = useState(true);
  const [posts, setPosts] = useState<Post[]>([]);

  const getPosts = async () => {
    try {
      const json = await fetch(
        "https://jsonplaceholder.typicode.com/posts",
      ).then((res) => res.json());
      setPosts(json);
    } catch (error) {
      console.error(error);
    } finally {
      setFetching(false);
    }
  };

  useEffect(() => {
    getPosts();
  }, []);

  return (
    <scroll-view scroll-y className="scroll-view">
      {isFetching ? <text className="scroll-view__loading">Loading...</text> : (
        posts.map((post) => (
          <view id={`${post.id}`} className="scroll-view__post">
            <text>{`${post.id} : ${post.title}`}</text>
          </view>
        ))
      )}
    </scroll-view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Making Requests

To fetch content from an arbitrary `URL`, you can pass the `URL` to `fetch`:

```typescript
fetch('https://jsonplaceholder.typicode.com/todos/1');
```

`fetch` also takes an optional second argument that allows you to customize the HTTP request. You may want to specify additional `headers`, make a `POST` request, or provide a JSON `body`:

```typescript
fetch('https://jsonplaceholder.typicode.com/todos/1', {
  method: 'POST',
  headers: {
    'some-header': 'header',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    firstParam: 'yourValue',
    secondParam: 'yourOtherValue',
  }),
});
```

Take a look at the [Fetch Request](/api/lynx-api/global/fetch.md#request) for the properties supported by Lynx.

### Handling the Response

The above examples show how you can make a request. In many cases, you will want to do something with the response.

Networking is an inherently asynchronous operation. The `fetch` method returns a `Promise`, which makes it straightforward to write code that works asynchronously. You can use the `async/await` syntax to await the promise's resolution:

```typescript
const getDataFromApiAsync = async () => {
  try {
    const response = await fetch(
      'https://jsonplaceholder.typicode.com/todos/1',
    );
    const json = await response.json();
    return json;
  } catch (error) {
    console.error(error);
  }
};
```

Take a look at the [Fetch Response](/api/lynx-api/global/fetch.md#response) for the properties supported by Lynx.

Don't forget to catch any errors that `fetch` may throw; otherwise, they will be silently ignored.

## Using Streaming Fetch

When transmitting large amounts of data, the server typically uses Streaming HTTP to send data incrementally. In such cases, the client can leverage the streaming capabilities of the `fetch` interface to receive and process data in batches in real time, thereby significantly improving data processing efficiency.

```typescript
fetch('https://sse.dev/test').then((response) => {
  const reader = response.body.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    } else {
      const text = TextCodecHelper.decode(value);
      setData(text);
    }
  }
});
```

You can refer to the MDN documentation [Response: body](https://developer.mozilla.org/en-US/docs/Web/API/Response/body)
to learn how to handle a streaming body.

:::tip
This is an experimental feature. To enable the streaming reading capability of the fetch interface, you need to set the specific PageConfig `enableFetchAPIStandardStreaming = true` in the page.
:::

## Using EventSource

Lynx provides the [EventSource](/api/lynx-api/global/fetch.md) with the same usage as the Web.

You can refer to the MDN guides on [Using server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) for more information.

```typescript
const url = 'https://sse.dev/test';
const eventSource = new lynx.EventSource(url2);

eventSource.onmessage = (event) => {
  console.log('Received message:', event.data);
};

eventSource.onerror = (error) => {
  console.error('EventSource failed:', error);
};
```

## Using TextCodecHelper

Due to the lack of `TextEncoder`/`TextDecoder` support in `PrimJS`, Lynx provides
`TextCodecHelper` for basic encoding and decoding operations. This class
supports `UTF-8` conversions between `string` and `arraybuffer`.

Usage:

Convert `arraybuffer` to `string`:

```typescript
const str = TextCodecHelper.decode(arraybuffer);
```

Convert `string` to `arraybuffer`:

```typescript
const arraybuffer = TextCodecHelper.encode(str);
```

## Using Other Networking Libraries

The Fetch API is built into Lynx, which means you can use third-party libraries that rely on it.

It is important to note that Lynx's Fetch API has subtle differences compared to the [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). You can check the [Fetch API Reference - Compatibility](/api/lynx-api/global/fetch.md#compatibility) section to learn more about these differences. As a result, you may need to adapt libraries from the web ecosystem to ensure compatibility. If you encounter any issues with the Lynx Fetch API, you are welcome to submit feature requests or [contribute](https://github.com/lynx-family/lynx/blob/develop/CONTRIBUTING.md) to help Lynx better support the web ecosystem.

For front-end framework-specific data fetching solutions, such as using [TanStack Query (React Query)](https://tanstack.com/query/latest) in ReactLynx, you can refer to the [Data Fetching](/react/data-fetching.md) chapter of the ReactLynx guide.



---
url: /guide/interaction/ifr.md
---

# Instant First-Frame Rendering (IFR)

Lynx supports "Instant First-Frame Rendering", which means that your page can display content directly when it is loaded, without a white screen or other intermediate states.

Remind you of SSR?This is usually achieved on the Web in a way similar to SSR, but Lynx's
innovate dual-thread architecture makes it much easier. Your application code
runs in Lynx's [JavaScript runtime](/guide/scripting-runtime/index.md), and will run
simultaneously on two threads: the [main
thread](/guide/spec.md#main-thread-or-lynx-main-thread) and the [background
thread](/guide/spec.md#background-thread-aka-off-main-thread). If the data
is ready at the beginning, your application code should be able to render the
first screen content directly on the main thread.

:::tip No magic
"Instant First-Frame Rendering" is not magic, Lynx sometimes cannot achieve "Instant First-Frame Rendering":

- When the Bundle of your page cannot be loaded synchronously, Lynx cannot achieve "Instant First-Frame Rendering" (for example, when using asynchronous file I/O, the main reason for your page to have a white screen is the asynchronous file I/O)
- When the main content of your page needs to be loaded asynchronously, Lynx cannot achieve "Instant First-Frame Rendering" (for example, your page needs to request network data, the main reason for your page to have a white screen is the asynchronous network request)

:::

## Basic Example

In the following example, we simulate a complex rendering through an intensive mathematical calculation (calculating the Fibonacci sequence).
Although the rendering takes some time (obviously longer than the interval of frames), Lynx completes the rendering synchronously on the main thread, avoiding the UI intermediate state, and achieves "Instant First-Frame Rendering" without any white screen.

**This is an example below: ifr**

**Entry:** `src/fib`
**Bundle:** `dist/fib.lynx.bundle` | Web: `dist/fib.web.bundle`

```tsx {34}
import JSBI from "jsbi";

import "./App.css";

const JSBI_ZERO = /* @__PURE__ */ JSBI.BigInt(0);
const JSBI_ONE = /* @__PURE__ */ JSBI.BigInt(1);
const JSBI_TWO = /* @__PURE__ */ JSBI.BigInt(2);

function fib(n: JSBI): JSBI {
  if (JSBI.lessThan(n, JSBI_ZERO)) {
    throw new Error("n must be non-negative");
  }
  if (JSBI.equal(n, JSBI_ZERO)) return JSBI_ZERO;
  if (JSBI.equal(n, JSBI_ONE)) return JSBI_ONE;

  let a = JSBI_ZERO, b = JSBI_ONE;
  for (let i = JSBI_TWO; JSBI.lessThanOrEqual(i, n); i = JSBI.add(i, JSBI_ONE)) {
    const next = JSBI.add(a, b);
    a = b;
    b = next;
  }

  return JSBI.BigInt(b);
}

export function App() {
  const n = JSBI.BigInt(10000);

  return (
    <view style="padding: 32rpx; display: flex; flex-direction: column; justify-content: center; align-items: center; width: 100%; height: 100%;">
      <text>fib({n.toString()})</text>
      <text>is</text>
      <scroll-view style="width: 100%; height: 50%;" scroll-y>
        <text>{fib(n).toString()}</text>
      </scroll-view>
    </view>
  );
}

```



## Do IFR with Data from Host Platform

Using static or preset data for "Instant First-Frame Rendering" is the simplest way, but it can only be used in scenes such as Showcase or Demo.
In actual applications, we usually need to use the data of the host platform for "Instant First-Frame Rendering". Go to [Using Data from Host Platform](/guide/use-data-from-host-platform.md) to learn more.

:::info
The following code uses `initData.mockData`, which is the data we set in LynxExplorer in advance to simulate the data of the host platform, so as to show you how to use the data of the host platform for "Instant First-Frame Rendering".
:::

**This is an example below: ifr**

**Entry:** `src/initData`
**Bundle:** `dist/init_data.lynx.bundle` | Web: `dist/init_data.web.bundle`

```tsx {17}
import { useInitData } from "@lynx-js/react";

import "./App.css";

declare module "@lynx-js/react" {
  interface InitData {
    mockData: string;
  }
}

export function App() {
  const initData = useInitData();

  return (
    <view style="display: flex; flex-direction: column; justify-content: center; align-items: center; width: 100%; height: 100%;">
      <text>Hello World</text>
      <text>{initData.mockData}</text>
    </view>
  );
}

```



## IFR is one of the advantages of Lynx

Your end users may easily notice the difference brought by "Instant First-Frame Rendering", which is one of the advantages of Lynx.

:::info
Video below is slowed down to 0.3x speed for better observation.
:::

Other cross-platform solutions (No IFR)Lynx (IFR)
It can be seen that when there is no "Instant First-Frame Rendering", opening the App will present the change process of "Splash Screen → White Screen → Content", while Lynx's "Instant First-Frame Rendering" makes the transition after the splash screen ends more natural and provides a better user experience.



---
url: /guide/styling/appearance.md
---

# Visual Appearance

## Background and Borders

You can do a lot creative things with background and borders. Using [`background-image`](/api/css/properties/background-image.md) to
apply network image or gradient effects to the background area of an element, using [`border-radius`](/api/css/properties/border-radius.md) to add a rounded corner, using [`box-shadow`](/api/css/properties/box-shadow.md) to create a shadow effect.

In the following example, we add a background with gradient effect, two styles of borders at top and left sides, a black shadow to an element with the top right corner rounded.

**This is an example below: css**

**Entry:** `src/border_background_shadow`
**Bundle:** `dist/border_background_shadow.lynx.bundle` | Web: `dist/border_background_shadow.web.bundle`

```tsx {8-12}
import { root } from "@lynx-js/react";

function App() {
  return (
    <view
      style={{
        flexDirection: "column",
        background: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))",
        borderRadius: "0 50% 0 0",
        boxShadow: "3px 5px 5px black",
        borderLeft: "2px rgb(0,235,235) dotted",
        borderTop: "2px rgb(255,53,26) dashed",
        marginTop: "50%",
        transform: "translate(-50%, -50%)",
        marginLeft: "50%",
        width: "150px",
        height: "150px",
      }}
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



:::info

[`border-image`](https://developer.mozilla.org/en-US/docs/Web/CSS/border-image) and related properties are under development.

:::

## Colors

With Lynx CSS, you can apply color values to various properties to create the look you want.

### Properties that can have color

#### Text

- [`color`](/api/css/properties/color.md): The color to use when drawing the text.
- [`-x-handle-color`](): The color of selection handlers (the cursor on the two ends of the selected text) when text is selected.
- [`text-shadow`](/api/css/properties/text-shadow.md): The color of the shadow in the shape of text.
- [`text-decoration-color`](/api/css/properties/text-decoration.md#text-decoration-color): The color to use when drawing the decoration line on the text.

#### Background and Border

- [`background-color`](/api/css/properties/background-color.md): The background color of the element.
- [`box-shadow`](/api/css/properties/box-shadow.md): The color of shadow.
- [`border-color`](/api/css/properties/border-color.md): The color to use when drawing the border. Can be set separately for the foursides via [`border-top-color`](/api/css/properties/border-color.md), [`border-top-color`](/api/css/properties/border-color.md), [`border-top-color`](/api/css/properties/border-color.md) or [`border-top-color`](/api/css/properties/border-color.md) as well.

Colors can be set to the property via [`selectors`](/api/css/selectors.md) or the `style` property of the element directly.
The color value should be a hex number start with a '#', or a value calculated by function `rgb()`, `rgba()` or `hsl()`. View the specification for [`<color>`](/api/css/data-type/color.md) value for more details.

## Gradient

You can use [`<gradient>`](/api/css/data-type/gradient.md) value to define a gradient effect and apply it to the following properties:

- [`color`](/api/css/properties/color.md): Drawing the text with a gradient effect.
- [`background-image`](/api/css/properties/background-image.md): Fill the background area with a gradient effect.
- [`mask-image`](/api/css/properties/mask-image.md): Use the gradient effect to create a alpha mask.

| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/color-gradient.png)
Text with a gradient 
`color
` | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-radial-gradient.png)
Filling background with 
`radial-gradient
` | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-fading-edge.gif)
 Create a 'fading edge' effect by adding 
`linear-gradient
` to 
`mask-image
`property |


## Clipping and Masking

In Lynx, besides [`overflow`](/api/css/properties/overflow.md), you can show content of an element in the area you want using [`clip-path`](/api/css/properties/clip-path.md) and [`mask-image`](/api/css/properties/mask-image.md).

**This is an example below: css**

**Entry:** `src/clip_path_super_ellipse`
**Bundle:** `dist/clip_path_super_ellipse.lynx.bundle` | Web: `dist/clip_path_super_ellipse.web.bundle`

```tsx {14}
import { root } from "@lynx-js/react";

function App() {
  return (
    <view
      style={{
        flexDirection: "column",
        background: "radial-gradient(circle at top left, rgb(255,53,26), rgb(0,235,235))",
        marginTop: "50%",
        transform: "translate(-50%, -50%)",
        marginLeft: "50%",
        width: "150px",
        height: "150px",
        clipPath: "inset(5px super-ellipse 3 3 50px/50px)",
      }}
    >
      <text
        style={{
          fontSize: "32px",
          fontWeight: "bold",
          alignSelf: "center",
          color: "white",
          marginTop: "50%",
          transform: "translateY(-50%)",
        }}
      >
        LYNX
      </text>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Using <code>clip-path</code> to clip out a super-elliptical area

**This is an example below: css**

**Entry:** `src/mask_image_circle_gradient`
**Bundle:** `dist/mask_image_circle_gradient.lynx.bundle` | Web: `dist/mask_image_circle_gradient.web.bundle`

```tsx {14}
import { root } from "@lynx-js/react";

function App() {
  return (
    <view
      style={{
        marginTop: "50%",
        transform: "translate(-50%, -50%)",
        marginLeft: "50%",
        width: "150px",
        height: "150px",
      }}
    >
      <view
        style={{
          flexDirection: "column",
          background: "radial-gradient(circle at top left, rgb(255,53,26), rgb(0,235,235))",
          width: "100%",
          height: "100%",
          maskImage: "radial-gradient(circle 75px, black 75%, transparent)",
          position: "absolute",
        }}
      >
        <text
          style={{
            fontSize: "32px",
            fontWeight: "bold",
            alignSelf: "center",
            color: "white",
            marginTop: "50%",
            transform: "translateY(-50%)",
          }}
        >
          LYNX
        </text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Using <code>mask-image</code> to create a circle area with fading edge



---
url: /guide/styling/animation.md
---

# Motion

Lynx offers extensive motion capabilities, allowing developers to create more modern, smooth, and intuitive user interfaces. Utilizing these features, developers can produce stunning transition effects and natural motion feedback, thereby enhancing user experience.

## Add transitions for layout and style changes.

If you need to smoothly apply new property values when the layout or style changes, you can use transitions.

Transitions provide a way to control the speed of animation changes when altering CSS properties. Instead of having changes take effect immediately, you can have the changes happen gradually over a period of time. For example, when you change an element's color from white to black, normally the change happens instantaneously. With transitions enabled, the change takes place over an interval that follows an easing curve, all of which can be customized.

Transitions are automatically triggered, non-repetitive, and easy to use. They can be defined using the shorthand [`transition`](/api/css/properties/transition.md) to set animation properties and duration, or you can specify them individually with [`transition-property`](/api/css/properties/transition-property.md) and [`transition-duration`](/api/css/properties/transition-duration.md), among others.

### Implement Collapse and Expand Effect for List Items

You can use transitions to add an animation effect for expanding and collapsing a list item in a list:

**This is an example below: animation**

**Entry:** `src/transition_toggle`
**Bundle:** `dist/toggle_transition_demo.lynx.bundle` | Web: `dist/toggle_transition_demo.web.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import type { ReactNode } from "@lynx-js/react";
import "./index.scss";

const AccordionItem = ({ title, content }: { title: ReactNode; content: ReactNode }) => {
  const [isActive, setIsActive] = useState(false);

  const toggleItem = () => {
    setIsActive(!isActive);
  };
  return (
    <view className={`accordion-item ${isActive ? "active" : ""}`}>
      <view className="accordion-header" bindtap={toggleItem} style={{ transition: "background-color 0.5s" }}>
        <text>{title}</text>
        <text className={`icon ${isActive ? "rotate" : ""}`} style={{ transition: "transform 0.5s" }}>▼</text>
      </view>
      <view
        className="accordion-content"
        // use 200px to estimate the height
        style={{ maxHeight: isActive ? "200px" : "14px", transition: "max-height 2s linear" }}
      >
        <text className="content">{content}</text>
      </view>
    </view>
  );
};

const Accordion = () => {
  const items = [
    {
      title: "Item 1",
      content: "This is the content of item 1. ".repeat(10),
    },
    {
      title: "Item 2",
      content: "This is the content of item 2. ".repeat(10),
    },
    {
      title: "Item 3",
      content: "This is the content of item 3. ".repeat(10),
    },
  ];

  return (
    <view className="accordion">
      {items.map((item, index) => <AccordionItem key={index} title={item.title} content={item.content} />)}
    </view>
  );
};
root.render(<Accordion />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Achieve stunning effects with keyframes.

If you need multiple sets of styles to transition in sequence, you can use keyframe animations.

Keyframe animations are defined in CSS using the [`@keyframes`](/api/css/at-rule/keyframes.md) rule, which specifies the style changes at various stages of the animation. The [`animation`](/api/css/properties/animation.md) property is then used to apply the defined animation to elements, allowing you to set parameters such as animation name, duration, delay, and number of iterations.

Keyframe animations are more flexible and controllable compared to transitions, as they allow you to specify the process and provide finer control over timing curves. You can define them in CSS with [`@keyframes`](/api/css/at-rule/keyframes.md) and specify them using the shorthand [`animation`](/api/css/properties/animation.md) property, or define them with individual properties such as [`animation-name`](/api/css/properties/animation-name.md), [`animation-duration`](/api/css/properties/animation-duration.md), and others.

### To achieve a rotation effect

Keyframe animations can be used to achieve the effect of a bounding box rotation.

**This is an example below: animation**

**Entry:** `src/keyframe_rotate`
**Bundle:** `dist/keyframe_rotate.lynx.bundle` | Web: `dist/keyframe_rotate.web.bundle`

```scss
page {
  background-color: #f7f7f7;
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
}

.container {
  border: 1px solid red;
}

.title-name-wrapper-border {
  position: relative;
  z-index: 0;
  width: 100%;
  height: 100%;
  border-radius: 10px;
  overflow: hidden;
  padding: 2rem;
}

@keyframes rotate {
  0% {
    transform: rotate(0deg);
  }

  100% {
    transform: rotate(1turn);
  }
}

@keyframes opacityChange {
  50% {
    opacity: 1;
  }

  100% {
    opacity: 0.5;
  }
}

.container {
  position: relative;
  z-index: 0;
  width: 80%;
  height: 300px;
  border-radius: 10px;
  overflow: hidden;
}

.title-name-wrapper-border-before {
  position: absolute;
  z-index: -2;
  left: -50%;
  top: -50%;
  width: 200%;
  height: 200%;
  background-color: red;
  background-repeat: no-repeat, no-repeat, no-repeat, no-repeat;
  background-size: 50% 50%, 50% 50%;
  background-position: 0px 0px, 100% 0px, 100% 100%, 0px 100%;
  background-image:
    linear-gradient(#399953, #399953),
    linear-gradient(#fbb300, #fbb300),
    linear-gradient(#d53e33, #d53e33),
    linear-gradient(#377af5, #377af5);
  animation: rotate 4s linear infinite;
}

.title-name-wrapper-border-after {
  position: absolute;
  z-index: -1;
  left: 6px;
  top: 6px;
  width: calc(100% - 12px);
  height: calc(100% - 12px);
  background: white;
  border-radius: 5px;
  animation: opacityChange 3s infinite alternate;
}

```



### To achieve a spring effect

Keyframe animations can add spring-like physics to element motion.

**This is an example below: animation**

**Entry:** `src/keyframe_spring`
**Bundle:** `dist/keyframe_spring.lynx.bundle` | Web: `dist/keyframe_spring.web.bundle`

```scss
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background-color: #f5f5f5;
}

.spring-box {
  width: 200px;
  height: 200px;
  background-color: #4a90e2;
  border-radius: 8px;
  display: flex;
  justify-content: center;
  align-items: center;
}

.box-text {
  color: white;
  font-size: 24px;
}

.animate {
  animation: kf-anim-spring 4s linear forwards;
}

@keyframes kf-anim-spring {
  0% {
    transform: scale(0, 0);
  }

  0.999% {
    transform: scale(0.306, 0.306);
  }

  1.998% {
    transform: scale(0.967, 0.967);
  }

  2.997% {
    transform: scale(1.586, 1.586);
  }

  3.996% {
    transform: scale(1.825, 1.825);
  }

  4.995% {
    transform: scale(1.586, 1.586);
  }

  5.994% {
    transform: scale(1.046, 1.046);
  }

  6.993% {
    transform: scale(0.529, 0.529);
  }

  7.992% {
    transform: scale(0.319, 0.319);
  }

  9.09% {
    transform: scale(0.54, 0.54);
  }

  10.089% {
    transform: scale(0.993, 0.993);
  }

  11.088% {
    transform: scale(1.409, 1.409);
  }

  12.087% {
    transform: scale(1.561, 1.561);
  }

  13.086% {
    transform: scale(1.389, 1.389);
  }

  14.085% {
    transform: scale(1.018, 1.018);
  }

  15.084% {
    transform: scale(0.671, 0.671);
  }

  16.083% {
    transform: scale(0.537, 0.537);
  }

  17.082% {
    transform: scale(0.67, 0.67);
  }

  18.081% {
    transform: scale(0.973, 0.973);
  }

  19.08% {
    transform: scale(1.263, 1.263);
  }

  20.079% {
    transform: scale(1.381, 1.381);
  }

  21.178% {
    transform: scale(1.258, 1.258);
  }

  22.177% {
    transform: scale(1.003, 1.003);
  }

  23.176% {
    transform: scale(0.77, 0.77);
  }

  24.175% {
    transform: scale(0.685, 0.685);
  }

  25.174% {
    transform: scale(0.781, 0.781);
  }

  26.173% {
    transform: scale(0.989, 0.989);
  }

  27.172% {
    transform: scale(1.184, 1.184);
  }

  28.171% {
    transform: scale(1.259, 1.259);
  }

  29.17% {
    transform: scale(1.185, 1.185);
  }

  30.169% {
    transform: scale(1.015, 1.015);
  }

  31.168% {
    transform: scale(0.852, 0.852);
  }

  32.167% {
    transform: scale(0.785, 0.785);
  }

  33.266% {
    transform: scale(0.855, 0.855);
  }

  34.265% {
    transform: scale(0.997, 0.997);
  }

  35.264% {
    transform: scale(1.128, 1.128);
  }

  36.263% {
    transform: scale(1.176, 1.176);
  }

  38.261% {
    transform: scale(1.006, 1.006);
  }

  40.259% {
    transform: scale(0.854, 0.854);
  }

  42.257% {
    transform: scale(0.991, 0.991);
  }

  44.255% {
    transform: scale(1.12, 1.12);
  }

  46.353% {
    transform: scale(1.001, 1.001);
  }

  48.351% {
    transform: scale(0.9, 0.9);
  }

  52.347% {
    transform: scale(1.081, 1.081);
  }

  56.343% {
    transform: scale(0.932, 0.932);
  }

  60.439% {
    transform: scale(1.055, 1.055);
  }

  64.435% {
    transform: scale(0.954, 0.954);
  }

  68.431% {
    transform: scale(1.037, 1.037);
  }

  72.527% {
    transform: scale(0.968, 0.968);
  }

  76.523% {
    transform: scale(1.025, 1.025);
  }

  80.519% {
    transform: scale(0.978, 0.978);
  }

  84.615% {
    transform: scale(1.017, 1.017);
  }

  88.611% {
    transform: scale(0.985, 0.985);
  }

  92.607% {
    transform: scale(1.011, 1.011);
  }

  96.703% {
    transform: scale(0.99, 0.99);
  }

  100% {
    transform: scale(1.006, 1.006);
  }
}

```



## Create flexible keyframe animations in JS.

Additionally, our [animate api](/api/lynx-api/lynx/lynx-animate-api.md) extends CSS keyframe animations, allowing for more flexible and dynamic creation and control of animations in JavaScript. Developers can dynamically generate and modify animations at runtime based on interactions or logic, offering users a more vibrant and interactive experience.

### To achieve a variable speed transform motions

By using the animate api, we can add a motion to the original that changes its rate in real time.

**This is an example below: animation**

**Entry:** `src/animate`
**Bundle:** `dist/animate.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const AnimateAnimationExample = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <view
        id="view1"
        className="box"
        bindtap={() => {
          const ani = lynx.getElementById("view1").animate(
            [
              {
                transform: "translate(0%, 0%) rotate(0deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(200px, 0%) rotate(90deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(200px, 100%) rotate(180deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(0%, 100%) rotate(270deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(0%, 0%) rotate(360deg)",
              },
            ],
            {
              name: "js-animation-1",
              duration: 5000,
              iterations: Infinity,
              easing: "linear",
            },
          );
        }}
      >
      </view>
    </view>
  );
};
root.render(<AnimateAnimationExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```





---
url: /guide/styling/custom-theming.md
---

# Theming

Lynx supports a wide range of [CSS properties](/api/css/properties.md), enabling seamless integration with [CSS selectors](/api/css/selectors.md), [CSS variables](/api/css/properties/css-variable.md), and opt-in CSS inheritance. By defining and managing different theme variables, developers can easily switch between various color schemes, font styles, and other visual elements, ensuring an optimal visual experience and interaction for users.

## Using CSS Descendant Selectors to Switch Themes

Similar to web development, using descendant selectors by toggling the class of a parent element can affect the styles of all its descendant nodes, thus enabling the switching of multiple theme styles.

### Defining CSS Themes

First, multiple theme CSS styles need to be defined, with different themes having different properties such as colors and backgrounds. For example, we can define both light and dark theme styles, with the light mode defined using `.theme-light .content` and the dark mode defined using `.theme-dark .content`.

```css
/* light theme */
.theme-light .content {
  color: black;
  background-color: white;
}

/* dark theme */
.theme-dark .content {
  color: white;
  background-color: black;
}
```

### Applying CSS Styles

In the page, set the class of the ancestor node (can be defined in the [`page`](/api/elements/built-in/page.md#using-page-element-explicitly)) to `theme-dark` or `theme-light`, and set the class of the descendant nodes to `content`. In this way, the descendant nodes can be styled with `.theme-light .content` or `.theme-dark .content` styles.

```tsx
function App() {
  return (
    <view className="theme-dark">
      <view>
        <text className="content">text</text>
      </view>
    </view>
  );
}
```

### Switching Theme Styles

When the theme changes, switch the class of the ancestor node to `theme-dark` or `theme-light`, which will update the styles of the descendant nodes. In the Lynx development scenario, the front-end themes can be notified by the native client. For example, the native client can notify the front-end of theme changes by updating [globalProps](/api/lynx-api/lynx/lynx-global-props.md).

The corresponding front-end implementation:

```tsx
import { useMemo } from '@lynx-js/react';
import './App.css';

export function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    //themeClass's value is 'theme-dark' or 'theme-light'
    <view className={themeClass}>
      <view>
        ...
        <text className="content">Hello Theme</text>
        ...
      </view>
    </view>
  );
}
```

### Example

**This is an example below: css**

**Entry:** `src/descendant_selectors_theme`
**Bundle:** `dist/descendant_selectors_theme.lynx.bundle` | Web: `dist/descendant_selectors_theme.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { useState } from "react";
import "./index.scss";

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    setIsDark(prev => !prev);
  };

  return (
    <view className={themeClass}>
      <view className="container">
        <view className="theme-card" bindtap={toggleTheme}>
          <text className="theme-icon">
            {isDark ? "🌙" : "☀️"}
          </text>
          <text className="title">
            {isDark ? "Dark Mode" : "Light Mode"}
          </text>
          <text className="subtitle">
            Tap to switch theme
          </text>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Using CSS Variables to Switch Themes

When using descendant selectors for theme switching, we need to predefine selectors for different theme styles, which lacks flexibility when dealing with multiple themes.

Using [CSS Variable](/api/css/properties/css-variable.md) to define theme styles and achieve theme switching by directly modifying the variable values.

### Defining CSS Themes

Similarly, we define the theme style variables that need to change and assign different values to the same variables.

For example, under different themes, `color` and `background-color` need to change with the theme. Therefore, two CSS variables `--color` and `--bg` need to be defined.

The descendant nodes can obtain the values of these variables in the stylesheet using `var(--color)` and `var(--bg)`.

```css
.theme-light {
  --color: black;
  --bg: white;
}

.content {
  color: var(--color);
  background-color: var(--bg);
}
```

### Applying CSS Styles

Note that CSS variables need to be mounted on the ancestor node (can be defined in the [`page`](/api/elements/built-in/page.md#using-page-element-explicitly)) so that their descendant nodes can use these variables in their respective stylesheets.

The descendant nodes can apply the values of these variables in `.content` using the `var(--*)` syntax.

```tsx
function App() {
  return (
    <view id="root" className="theme-light">
      <view>
        <text className="content">text</text>
      </view>
    </view>
  );
}
```

### Switching Theme Styles

#### Directly Changing CSS Variable Values with JS

Use JS API ([`setProperty`](/api/css/properties/css-variable.md#modifying-css-variables-via-javascript-api)) to directly modify CSS variable values, allowing flexible batch updates of CSS variables.

```tsx
import './App.css';

export function App() {
  const handleClick = () => {
    lynx.getElementById('root').setProperty({
      '--color': 'white',
      '--bg': 'black',
    });
  };

  return (
    <view id="root" className="theme-light" bindtap={handleClick}>
      <text className="content">Hello Variable</text>
    </view>
  );
}
```

#### Indirectly Changing Variable Values by Switching Classes

Alternatively, you can indirectly modify variable values by switching classes on the ancestor node that define different [CSS variables](/api/css/properties/css-variable.md#modifying-the-selector-that-declares-css-variables), triggering style updates for all child nodes using these variables when theme switching is needed.

For example, use `.theme-light` and `.theme-dark` to define CSS variable values for different themes:

```css
.theme-light {
  --color: black;
  --bg: white;
}

.theme-dark {
  --color: white;
  --bg: black;
}

.content {
  color: var(--color);
  background-color: var(--bg);
}
```

Switching between `.theme-light` or `.theme-dark` on the ancestor node changes the values of `--color` and `--bg`, which updates the styles for corresponding `.content` elements.

```tsx
import { useMemo } from '@lynx-js/react';

import './App.css';

export function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    //themeClass's value is 'theme-dark' or 'theme-light'
    <view className={themeClass}>
      <text id="test" className="content">
        Hello Variable
      </text>
    </view>
  );
}
```

### Example

**This is an example below: css**

**Entry:** `src/css_variable_theme`
**Bundle:** `dist/css_variable_theme.lynx.bundle` | Web: `dist/css_variable_theme.web.bundle`

```tsx {23-43}
import { root } from "@lynx-js/react";
import { useState } from "react";
import "./index.scss";

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const [useJS, setUseJS] = useState(false);
  const [showError, setShowError] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    if (useJS) {
      setShowError(true);
      setTimeout(() => setShowError(false), 3000);
      return;
    }

    setIsDark(prev => !prev);
  };

  const toggleThemeByJS = () => {
    setUseJS(true);
    const rootElement = lynx.getElementById("root");
    const newTheme = isDark ? "light" : "dark";

    if (rootElement) {
      if (isDark) {
        rootElement.setProperty({
          "--bg-primary": "#ffffff",
          "--bg-secondary": "#f5f5f5",
          "--text-primary": "#1a1a1a",
          "--text-secondary": "#666666",
          "--shadow": "rgba(0, 0, 0, 0.1)",
        });
      } else {
        rootElement.setProperty({
          "--bg-primary": "#2d2d2d",
          "--bg-secondary": "#1a1a1a",
          "--text-primary": "#ffffff",
          "--text-secondary": "#cccccc",
          "--shadow": "rgba(0, 0, 0, 0.3)",
        });
      }
      setIsDark(prev => !prev);
    }
  };

  return (
    <view id="root" className={themeClass}>
      <view className="container">
        <view className="theme-switchers">
          <view className="theme-card" bindtap={toggleTheme}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme by className</text>
          </view>
          <view className="theme-card" bindtap={toggleThemeByJS}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme through JS</text>
          </view>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
      {showError && (
        <view className="error-message-container">
          <text className="error-message">
            Cannot change variables through the class after modifying them in JS!
          </text>
        </view>
      )}
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Leveraging CSS Inheritance As Needed

In pages with complex styles, using CSS inheritance can simplify development. However, implementing inheritance logic adds complexity to the style processing flow and can introduce some performance overhead. To optimize performance, Lynx does not enable inheritance for ordinary CSS properties by default, developers must enable it as needed. CSS custom properties (also known as CSS variables) are inherited by descendant nodes by default.

### Inheritance of CSS Custom Properties

[CSS Custom Properties](/api/css/properties/css-variable.md) (CSS variables, e.g., `--primary-color`) adhere to Web standards and are inherited by descendant nodes by default without additional configuration. Developers can define CSS custom properties in ancestor nodes to achieve dynamic style management.

### Inheritance of Regular (Non-Custom) Properties

To enable inheritance, configure[`enableCSSInheritance`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md).

#### Default-Inheritable Properties

After enabling `enableCSSInheritance`, these properties can be inherited:

[`direction`](/api/css/properties/direction.md),[`color`](/api/css/properties/color.md),[`font-family`](/api/css/properties/font-family.md),[`font-size`](/api/css/properties/font-size.md),[`font-style`](/api/css/properties/font-style.md),[`font-weight`](/api/css/properties/font-weight.md),[`letter-spacing`](/api/css/properties/letter-spacing.md),[`line-height`](/api/css/properties/line-height.md),[`text-align`](/api/css/properties/text-align.md),[`text-decoration`](/api/css/properties/text-decoration.md),[`text-shadow`](/api/css/properties/text-shadow.md)

Default inherited properties inherit behavior alignment with [🌐W3C definition](https://www.w3.org/TR/css-cascade-3/#inheriting)

#### Custom-Inheritable Properties

In addition to the default inheritable properties, you can configure the page with [`customCSSInheritanceList`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)to define custom inheritable CSS properties. When there are custom inheritance declarations, only the CSS properties listed in the `customCSSInheritanceList` will be inheritable.

Example:

```json
"customCSSInheritanceList":["font-size","flex-direction"]
```

#### Limitations of CSS Inheritance

1. Elements with `position: fixed` will always inherit properties only from the page.
2. The keyword "inherit" is not supported.
3. In addition to the default inheritable properties, only CSS properties with types enum or boolean support custom inheritance.



---
url: /guide/styling/text-and-typography.md
---

# Typography

## Text in Lynx

In Lynx, the text content needs to be written inside the [`<text>`](/api/elements/built-in/text.md) element. This is different from HTML, where text can be directly written inside a `<div>`. Let's look at a simple example:

```tsx
//❌ This won't work
<view>hello world</view>

//✅ Use the <text> component
<text>hello world</text>
```

You can add styles to the `<text>` element to change the text effect. For example, to change the text color:

```tsx
<text style={{ color: 'red' }}>hello world</text>
```

Similarly, to change the text size and make the text italic:

```tsx
<text style={{ fontSize:"30px" }}>hello world</text>
<text style={{ fontStyle:"italic" }}>hello world</text>
```

Lynx also supports adding shadows or strokes to the text by setting the [`text-shadow`](/api/css/properties/text-shadow.md) and [`text-stroke`](/api/css/properties/text-stroke.md) properties to enrich the display effect:

**This is an example below: text**

**Entry:** `src/shadow_and_stroke`
**Bundle:** `dist/shadow_and_stroke.lynx.bundle` | Web: `dist/shadow_and_stroke.web.bundle`

```tsx {15-20}
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";

export default class TextShadowAndStrokeExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          width: "100%",
          alignItems: "center",
        }}
      >
        <text style={{ textShadow: "2px 2px 4px green", fontSize: "30px" }}>
          Text Shadow
        </text>
        {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
        <text style={{ textStroke: "1px red", fontSize: "30px" }}>
          Text Stroke
        </text>
      </view>
    );
  }
}
root.render(<TextShadowAndStrokeExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Mixing Text with Different Styles

In daily text layout, it is often necessary to highlight some parts of the text, such as making keywords bold and changing their color. Suppose we want to make "important word" in the text "This is an important word" bold and red. We can put "important word" into an nested `<text>` and set the `color` and `font-weight` properties.

```tsx
<view>
  <text>
    This is an
    <text style={{ color: 'red', fontWeight: 'bold' }}>important word</text>
  </text>
</view>
```

You can use the properties in the CSS text module to control how text is displayed, such as line-breaking, alignment, and whitespace handling, to achieve more diverse text layout effects. For example, use [`text-indent`](/api/css/properties/text-indent.md) to control the first-line indentation of text, [`word-break`](/api/css/properties/word-break.md) to control the line-breaking behavior of words, and [`text-align`](/api/css/properties/text-align.md) to control the horizontal alignment of text content.

The following is an example of the comprehensive use of properties. You can also refer to [text-related properties](/api/elements/built-in/text.md#text-related-css-properties).

**This is an example below: text**

**Entry:** `src/text_layout`
**Bundle:** `dist/text_layout.lynx.bundle` | Web: `dist/text_layout.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";

export default class TextLayoutExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          width: "100%",
        }}
      >
        <text
          style={{
            fontSize: "30px",
            color: "linear-gradient(to right, red,orange,yellow,green,blue,indigo,violet)",
          }}
        >
          Text Gradient Title
        </text>
        <text
          style={{ fontSize: "20px", textIndent: "20px", lineHeight: "30px" }}
        >
          You can
          <text style={{ fontWeight: "bold", fontSize: "20px" }}>
            {" "}
            bold
          </text>{" "}
          the text that needs to be emphasized.
          <text
            style={{
              backgroundImage: "linear-gradient(360deg, rgba(74, 170, 159, 0.2) 0%, rgba(74, 170, 159, 0) 100%)",
              backgroundSize: "100% 8px",
              backgroundPosition: "0 100%",
              backgroundRepeat: "no-repeat",
              fontSize: "20px",
            }}
          >
            You can add a gradual change to the background color of the text.
          </text>
          <text style={{ textDecoration: "underline", fontSize: "20px" }}>
            You can underline the sentence.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<TextLayoutExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Implementing Text-Image Mixing Layout

To create more colorful pages, it is often necessary to embed images in text. The following describes how to mix text and images in layout. Take the following figure as an example:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/inline-image-demo.png)


The first step is to use the `<text>` and `<image>` elements to build the page structure. They cooperate with each other to construct the basic framework.

```tsx
<text>
  <image />
  <text>
    This is a warning message.This is a warning message.This is a warning
    message.
  </text>
</text>
```

The second step is to set the style of the `<image>` element. The key is to set the width and height to ensure that the image is presented appropriately on the page and is compatible with the text. At the same time, set the `text-align` property on the `<text>` element to center the text horizontally.

**This is an example below: text**

**Entry:** `src/inline_image`
**Bundle:** `dist/inline_image.lynx.bundle` | Web: `dist/inline_image.web.bundle`

```tsx {8-18}
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
export default class Index extends Component {
  render() {
    return (
      <view style={{ width: "200px" }}>
        <text style={{ fontSize: "20px", textAlign: "center" }}>
          <image
            style={{
              width: "20px",
              height: "20px",
              border: "1px solid red",
              borderRadius: "50%",
              verticalAlign: "middle",
            }}
            src={ExclamationCircle}
          />
          <text style={{}}>
            This is a warning message.This is a warning message.This is a warning message.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<Index />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



The third step is to adjust the vertical position of the image within the line. By default, the bottom of the `<image>` element aligns with the text baseline. You can use the [`vertical-align`](/api/css/properties/vertical-align.md) property to precisely adjust the vertical position of the `<image>` element within the line.

**This is an example below: text**

**Entry:** `src/inline_image`
**Bundle:** `dist/inline_image.lynx.bundle` | Web: `dist/inline_image.web.bundle`

```tsx {15}
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
export default class Index extends Component {
  render() {
    return (
      <view style={{ width: "200px" }}>
        <text style={{ fontSize: "20px", textAlign: "center" }}>
          <image
            style={{
              width: "20px",
              height: "20px",
              border: "1px solid red",
              borderRadius: "50%",
              verticalAlign: "middle",
            }}
            src={ExclamationCircle}
          />
          <text style={{}}>
            This is a warning message.This is a warning message.This is a warning message.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<Index />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



In addition to images, you can also nest `<view>` within the `<text>` component to create more complex pages.

**This is an example below: text**

**Entry:** `src/inline_view`
**Bundle:** `dist/inline_view.lynx.bundle` | Web: `dist/inline_view.web.bundle`

```tsx {11-26}
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
import "./index.scss";

const InlineView = () => {
  return (
    <view
      style="flex-direction:column;align-items:center;border:1px red solid;"
      lynx-test-tag="container"
    >
      <text
        style="text-align:center;font-size:25px;text-overflow:ellipsis;"
        text-maxline="2"
      >
        <view
          style={{ flexDirection: "column", verticalAlign: "center" }}
          className="container"
          clip-radius="true"
        >
          <view className="title-name-wrapper-border">
            <view className="title-name-wrapper-border-before"></view>
            <view className="title-name-wrapper-border-after"></view>
          </view>
        </view>
        This is a paragraph containing animation.This is a paragraph containing animation.
      </text>
    </view>
  );
};

export default InlineView;
root.render(<InlineView />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Text Truncation and Ellipsis

When the text content is long and the space is limited, it is necessary to use ellipsis techniques to make the page concise and avoid information clutter. In Lynx, the [`text-overflow`](/api/css/properties/text-overflow.md) property can be used to add an ellipsis effect at the text truncation point. You can choose `ellipsis` to automatically add an ellipsis, or use `clip` to truncate according to the rules.

In specific implementation, first limit the number of lines or height of the `<text>` element. When the text exceeds the range, the ellipsis effect will be triggered. Then set the `text-overflow` property to control the presentation method:

```tsx
<text text-maxline={'1'} style={{ textOverflow: 'ellipsis' }}>
  This is an extremely long text.
</text>
```

Although `text-overflow` cannot directly specify the content displayed at the truncation point, the `<inline-truncation>` element provided by Lynx has strong customization capabilities and can display various contents such as images and `<view>` at the truncation point.

**This is an example below: text**

**Entry:** `src/inline_truncation`
**Bundle:** `dist/inline_truncation.lynx.bundle` | Web: `dist/inline_truncation.web.bundle`

```tsx
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import RightArrow from "@assets/image/rightarrow.png?inline";
import { root } from "@lynx-js/react";

const InlineTruncation = () => {
  return (
    <view style={{ width: "200px" }}>
      <text style={{ height: "30px", lineHeight: "20px" }} text-maxline="1">
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text>...See More</text>
          <image src={RightArrow} style={{ width: "10px", height: "10px" }} />
        </inline-truncation>
      </text>

      <text
        style={{ lineHeight: "20px", marginTop: "30px" }}
        text-maxline={"2"}
      >
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text style={{ color: "grey" }}>...See More</text>
          <view style={{ verticalAlign: "center" }} flatten={false}>
            <image
              src={ExclamationCircle}
              style={{ width: "15px", height: "15px" }}
            />
          </view>
        </inline-truncation>
      </text>
    </view>
  );
};

export default InlineTruncation;
root.render(<InlineTruncation />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Custom Font Settings

You can directly use [`@font-face`](/api/css/at-rule/font-face.md) to specify custom font resources (the [client needs to support the font resource loader](/api/elements/built-in/text.md#loading-custom-fonts)). At the same time, set the corresponding `font-family` on the `<text>` element.

In addition, if you need to load a font file in JS, you can refer to the addFont API designed based on Web Font Loading. This module provides the FontFace class and the [addFont](/api/lynx-api/lynx/lynx-add-font.md) method on the global object `lynx`.

**This is an example below: text**

**Entry:** `src/custom_font`
**Bundle:** `dist/custom_font.lynx.bundle` | Web: `dist/custom_font.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
import fontFile from "../../assets/font/Doto-Regular.ttf";

import "./index.scss";

export default class CustomFontExample extends Component<{}, { fontName: string }> {
  constructor(props: {}) {
    super(props);
    this.state = { fontName: "PingFang" };
  }
  componentDidMount() {
    lynx.addFont(
      {
        "font-family": "Doto",
        "src": `url(${fontFile})`,
      },
      () => {
        console.log("load Doto font");
        this.setState({ fontName: "Doto" });
      },
    );
  }
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          width: "100%",
        }}
      >
        <text>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Inter" }}>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: this.state.fontName }}>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Icon" }}>&#xEA01;</text>
      </view>
    );
  }
}
root.render(<CustomFontExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```





---
url: /guide/inclusion/accessibility.md
---

# Accessibility

Accessibility (A11y) refers to the design concept of building accessibility through technical means to ensure that mobile applications can be equally accessed by all kinds of people.

Its core goal is to break down usage barriers, allowing users with different physical conditions, perceptual abilities, and cognitive levels to smoothly obtain information and services.

Mainstream mobile platforms provide a complete accessibility support system: iOS and Android not only natively integrate APIs for users with disabilities but also come equipped with standardized assistive technology toolchains, such as screen readers (VoiceOver / TalkBack) designed specifically for visually impaired users.

On this basis, the Lynx framework encapsulates cross-platform accessibility interfaces, enabling developers to integrate accessibility features in their apps and build an information-accessible mobile ecosystem.

:::info
Different platforms have distinct designs and norms regarding accessibility; therefore, implementation and experience with Lynx may vary across platforms.
:::

## Default Accessibility Behavior

Only one accessibility element can be successfully accessed and focused by screen readers (VoiceOver on iOS and TalkBack on Android).

However, `<text>` and `<image>` are default accessibility elements and can be recognized without any further action.

**This is an example below: accessibility**

**Entry:** `src/Default.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {4-5}
export const Default = ({ src }: { src: string }) => {
  return (
    <view>
      <text>Hello world</text>
      <image auto-size style="width:100px" src={src} />
    </view>
  );
};

```



## Tagging Accessibility Elements

Sometimes, you might want to control the size of accessibility elements or aggregate some accessibility information, requiring control over which elements are accessibility nodes.

Use [`accessibility-element`](/api/elements/built-in/view.md#accessibility-element) to tag an element as an accessibility element; nested elements are allowed.

In the example below, there will be only one accessibility focus point and it will be read as "Hello world".

**This is an example below: accessibility**

**Entry:** `src/Customized.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {5,8,9}
export const Customized = ({ src }: { src: string }) => {
  return (
    <view
      style={{ padding: "10px" }}
      accessibility-element={true}
      accessibility-label={"Hello world"}
    >
      <text accessibility-element={false}>Hello</text>
      <text accessibility-element={false}>world</text>
    </view>
  );
};

```



:::info
On `<text>` and `<image>`, this property is set to `true` by default.
:::

## Specifying the Characteristics and Content of Accessibility Elements

Use [`accessibility-trait`](/api/elements/built-in/view.md#accessibility-trait) to mark the characteristics of an accessibility element, which can be any of image, button, or text.

Use [`accessibility-label`](/api/elements/built-in/view.md#accessibility-label) to adjust the content that screen readers will read for an accessibility element.

:::info
On `<text>`, the default is to read the content of the text.
:::

In the example below, the elements will be read as "Hello lynx" and "I am an image displaying the Lynx icon," respectively.

**This is an example below: accessibility**

**Entry:** `src/LabelAndTraits.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {6,7,16,17}
export const LabelAndTraits = ({ src }: { src: string }) => {
  return (
    <view
      style={{ padding: "10px" }}
      accessibility-element={true}
      accessibility-trait="button"
      accessibility-label={"Hello world"}
    >
      <text accessibility-element={false}>Hello</text>
      <text accessibility-element={false}>world</text>
      <image
        auto-size
        style={{ width: "100px" }}
        src={src}
        accessibility-element={true}
        accessibility-trait="image"
        accessibility-label="I am an image displaying the Lynx icon"
      />
    </view>
  );
};

```



## Adjusting the Reading Order of Accessibility Elements

iOS and Android systems default to arranging accessibility elements from top to bottom and left to right so they can be accessed sequentially by screen readers.

Use [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) to manually adjust this order. Note that each id should be separated by a comma.

Furthermore, if a parent node sets the [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) property, only child nodes specified by the [`accessibility-elements`](/api/elements/built-in/view.md#accessibility-elements) attribute can be accessed, while other child nodes cannot be focused.

In the example below, the order of accessibility elements will be adjusted, and they will be read as "Lynx" and "Hello" sequentially.

**This is an example below: accessibility**

**Entry:** `src/ReOrder.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {3,5,6}
export const ReOrder = ({ src }: { src: string }) => {
  return (
    <view style={{ padding: "10px" }} accessibility-element={true} accessibility-elements="second,first">
      <view>
        <text id="first">Hello</text>
        <text id="second">Lynx</text>
      </view>
    </view>
  );
};

```



## Listening to Focus Changes of Accessibility Elements

When the focus of accessibility elements changes, a global event `activeElement` notifies the information of the newly focused node.

```tsx
export default class App extends Component<Props, State> {
  componentDidMount() {
    // Listen for focus changes
    this.getJSModule('GlobalEventEmitter').addListener(
      'activeElement',
      this.handleActiveElement,
      this,
    );
  }

  handleActiveElement(info: any) {
    this.setState({
      activeElementJsonStr: JSON.stringify(info),
    });
  }
}
```

## Actively Focusing on an Accessibility Element

Use [`requestAccessibilityFocus`](/api/elements/built-in/view.md#requestaccessibilityfocus) to provide the capability to actively focus on an accessibility element.

```ts
lynx
  .createSelectorQuery()
  .select('#customId')
  .invoke({
    method: 'requestAccessibilityFocus',
    params: {},
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res);
    },
  })
  .exec();
```

## Make Screen Readers Announce Specified Text Content

Use [`accessibilityAnnounce`](/api/lynx-api/lynx/lynx-accessibility-announce.md#accessibilityAnnounce) to make screen readers announce the specified text content, helping visually impaired users perceive interface state changes or operation results.

```jsx
lynx.accessibilityAnnounce(
  {
    content: 'hello lynx',
  },
  (res) => {
    console.log('test: ' + JSON.stringify(res));
  },
);
```



---
url: /guide/inclusion/internationalization.md
---

# Internationalization

**Internationalization** (i18n) refers to the design and development of products and applications to enable **localization**, making them suitable for users from different cultures, regions, or languages. You can use i18n libraries like `i18next` to achieve internationalization and provide an accessible experience for users.

## Intl API

The [`Intl`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl) object is a namespace for the ECMAScript Internationalization API, providing a set of methods for handling internationalization and localization. With the `Intl` API, you can handle issues related to numbers, dates, and times, such as number formatting and date and time formatting.

Currently, the `Intl` API is not implemented in Lynx but will be supported in future versions. If you need to use the `Intl` API in Lynx, you can install the corresponding polyfills, such as [@formatjs/intl-numberformat](https://www.npmjs.com/package/@formatjs/intl-numberformat), [@formatjs/intl-datetimeformat](https://www.npmjs.com/package/@formatjs/intl-datetimeformat), and [intl-pluralrules](https://www.npmjs.com/package/intl-pluralrules).

## Using `i18next`

[`i18next`](https://www.i18next.com/) is an internationalization-framework written in and for JavaScript. Using it in ReactLynx gives you:

1. **Simplicity**: `i18next` provides an easy-to-use API, making it simple to implement internationalization in ReactLynx applications.
2. **Dynamic Loading**: Supports on-demand loading of language resources, reducing initial load time.
3. **Wide Support**: Compatible with various formats and backends, allowing easy integration with different translation storage solutions such as JSON files, remote APIs, etc.
4. **Caching**: Built-in caching mechanism speeds up the loading of language resources, enhancing user experience.
5. **Rich Community Support**: A vast community and a wealth of plugins available to meet diverse internationalization needs.
6. **Reliability**: Proven in numerous projects, offering stability and reliability.
7. **Hot Reloading**: Changes to language resources can take effect immediately without needing to republish the application.

### Installation

You need to install the `i18next` package:


```sh [npm]
npm install i18next@^23.16.8
```

```sh [yarn]
yarn add i18next@^23.16.8
```

```sh [pnpm]
pnpm add i18next@^23.16.8
```

```sh [bun]
bun add i18next@^23.16.8
```

```sh [deno]
deno add npm:i18next@^23.16.8
```

:::tip

Since the version [24.0.0+](https://www.i18next.com/misc/migration-guide#v23.x.x-to-v24.0.0) of i18next, the running environment is required to have the [`Intl.pluralRules`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) API. However, this implementation is currently not available on Lynx.

This means that you need to:

1. Use v23 and must enable [`compatibilityJSON: 'v3'`](https://www.i18next.com/misc/json-format#i18next-json-v3).
2. Use v24 and need to [polyfill](https://github.com/eemeli/intl-pluralrules) the `Intl.PluralRules` API.

:::

### Create the first translation

Imagine we have a locale file `src/locales/en.json` like this:

```json title="src/locales/en.json"
{
  "world": "World"
}
```

Creating the translation function is as simple as these 3 steps:

1. Import the locale JSON file `./locales/en.json`.
2. Create an i18next instance with the [`createInstance()`](https://www.i18next.com/overview/api#createinstance) function.
3. [Initialize](https://www.i18next.com/overview/api#init) the i18n with the locale resource.


```typescript title="src/i18n.ts"
import i18next from 'i18next';
import type { i18n } from 'i18next';

import enTranslation from './locales/en.json';

const localI18nInstance: i18n = i18next.createInstance();

localI18nInstance.init({
  lng: 'en',
  // The default JSON format needs `Intl.PluralRules` API, which is currently unavailable in Lynx.
  compatibilityJSON: 'v3',
  resources: {
    en: {
      translation: enTranslation, // `translation` is the default namespace
    },
  },
});

export { localI18nInstance as i18n };
```

:::tip

If you import `*.json` in TypeScript file, you may need to set `compilerOptions.resolveJsonModule` to `true` in your `tsconfig.json` file.

```json title="tsconfig.json"
{
  "compilerOptions": {
    "resolveJsonModule": true
  }
}
```

:::

Then, the `i18n.t` function can be used for translations:

```tsx title="src/App.tsx"
import { useEffect } from '@lynx-js/react';

import { i18n } from './i18n.js'; // [!code highlight]

export function App() {
  useEffect(() => {
    console.log(`Hello, ReactLynx x i18next!`);
  }, []);

  return (
    <view>
      <text>Hello, {i18n.t('world')}</text>
    </view>
  );
}
```

### Load resources synchronously

In a real world project, there are usually multiple resource files for different languages.

Instead of static import them one-by-one,
you may use the [`import.meta.webpackContext`](https://rspack.rs/api/runtime-api/module-variables#importmetawebpackcontext) API of Rspack to statically import all the JSON files.

import one-by-one```js
// Static-imported locales that can be shown at first screen
import enTranslation from './locales/en.json';
import zhTranslation from './locales/zh.json';
import itTranslation from './locales/it.json';
import jpTranslation from './locales/jp.json';
import deTranslation from './locales/de.json';
import esTranslation from './locales/es.json';
import frTranslation from './locales/fr.json';
import idTranslation from './locales/id.json';
import ptTranslation from './locales/pt.json';
```
```js
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /\.json$/,
});
const enTranslation = localesContext('en.json');
```

These resources can be added to `i18next.init()` to make translation work at the first screen.

```typescript title="src/i18n.ts"
import i18next from 'i18next';
import type { i18n } from 'i18next';

// Localizations imported statically, available at the initial screen
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /\.json$/,
});

const localI18nInstance: i18n = i18next.createInstance();

localI18nInstance.init({
  lng: 'en',
  // The default JSON format needs Intl.PluralRules API, which is currently unavailable in Lynx.
  compatibilityJSON: 'v3',
  // Add all statically imported localizations to i18next resources.
  resources: Object.fromEntries(
    localesContext.keys().map((key) => [
      key.match(/\/([^/]+)\.json$/)?.[1] || key,
      {
        translation: localesContext(key) as Record<string, string>,
      },
    ]),
  ),
});

export { localI18nInstance as i18n };
```

:::tip
You may need [Rspeedy Type Declaration](/rspeedy/typescript.md#rspeedy-type-declaration) for `import.meta.webpackContext`.
:::

### Load resources asynchronously and lazily

Instead of bundling all the locales, we can use dynamic imports (`import()`) to load the locales lazily and asynchronously.

You need to install the [`i18next-resources-to-backend`](https://github.com/i18next/i18next-resources-to-backend) package:


```sh [npm]
npm install i18next-resources-to-backend
```

```sh [yarn]
yarn add i18next-resources-to-backend
```

```sh [pnpm]
pnpm add i18next-resources-to-backend
```

```sh [bun]
bun add i18next-resources-to-backend
```

```sh [deno]
deno add npm:i18next-resources-to-backend
```

Then add the following code to `src/i18n.ts`:

```typescript title="src/i18n.ts" {3,14-23,38}
import i18next from 'i18next';
import type { i18n } from 'i18next';
import resourcesToBackend from 'i18next-resources-to-backend';

// Localizations imported statically, available at the initial screen
const localesContext = import.meta.webpackContext('./locales', {
  recursive: false,
  regExp: /(en|zh)\.json$/,
});

const localI18nInstance: i18n = i18next.createInstance();

// We can only loading resources on a background thread
if (__JS__) {
  localI18nInstance.use(
    // See: https://www.i18next.com/how-to/add-or-load-translations#lazy-load-in-memory-translations
    resourcesToBackend(
      (language: string) =>
        // Dynamic-imported locales can be used with `i18n.loadLanguages`
        import(`./locales/${language}.json`),
    ),
  );
}

localI18nInstance.init({
  lng: 'en',
  // The default JSON format needs Intl.PluralRules API, which is currently unavailable in Lynx.
  compatibilityJSON: 'v3',
  // Add all statically imported localizations to i18next resources.
  resources: Object.fromEntries(
    localesContext.keys().map((key) => [
      key.match(/\/([^/]+)\.json$/)?.[1] || key,
      {
        translation: localesContext(key) as Record<string, string>,
      },
    ]),
  ),
  partialBundledLanguages: true,
});

export { localI18nInstance as i18n };
```

1. An `i18next` backend `i18next-resources-to-backend` has been added to the background thread with `localI18nInstance.use`.

2. The languages can be loaded asynchronously (with some of them being loaded synchronously).

You will see two async JS chunks are created in the output:

```js title=src_locales_it-IT_json.js
'use strict';
exports.ids = ['src_locales_it-IT_json'];
exports.modules = {
  './src/locales/it-IT.json': function (module) {
    module.exports = JSON.parse('{"world": "Mondo"}');
  },
};
```
```js title=src_locales_ja-JP_json.js
'use strict';
exports.ids = ['src_locales_ja-JP_json'];
exports.modules = {
  './src/locales/ja-JP.json': function (module) {
    module.exports = JSON.parse('{"world": "世界"}');
  },
};
```

:::tip 💡 Why is there no async chunk generated by src/locales/en.json

This is because this module is already included in the main chunk. Webpack/Rspack will remove it automatically.
See: [`optimization.removeAvailableModules`](https://webpack.js.org/configuration/optimization/#optimizationremoveavailablemodules) and [`optimization.removeEmptyChunks`](https://webpack.js.org/configuration/optimization/#optimizationremoveemptychunks) for details.

You may also see that these two chunks are not loaded. This is why it is called lazily. The request to the resources is only sent when needed.
:::

You may also see that these two chunks are not loaded. This is why it is called lazily. The request to the resources is only sent when needed.

### Change between languages

The `i18next.changeLanguage` API can be used for changing between languages.

```jsx title="src/App.tsx"
import { useEffect, useState } from '@lynx-js/react';

import { i18n } from './i18n.js';

export function App() {
  const [locale, setLocale] = useState('en');

  useEffect(() => {
    console.log('Hello, ReactLynx3 x i18next!');
  }, []);

  const getNextLocale = (locale: string) => {
    // mock locales
    const locales = ["en", "zh-CN"];
    const index = locales.indexOf(locale);
    return locales[(index + 1) % locales.length];
  };
  return (
    <view>
      <text style={{ color: 'red' }}>Current locale: {locale}</text>
      <text
        bindtap={async () => {
          const nextLocale = getNextLocale(locale);
          await i18n.changeLanguage(nextLocale);
          setLocale(nextLocale);
        }}
      >
        Tap to change locale
      </text>
      <text>Hello, {i18n.t('world')}</text>
    </view>
  );
}
```

**This is an example below: i18n**

**Entry:** `src/index.tsx`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useState } from "@lynx-js/react";
import { i18n } from "./i18n.js";

import "./App.css";

export function App() {
  const [locale, setLocale] = useState("en");
  const getNextLocale = (locale: string) => {
    // mock locales
    const locales = ["en", "zh-CN"];
    const index = locales.indexOf(locale);
    return locales[(index + 1) % locales.length];
  };
  return (
    <view className="root">
      <text className="content">Hello, {i18n.t("world")}</text>
      <text
        bindtap={async () => {
          const nextLocale = getNextLocale(locale);
          await i18n.changeLanguage(nextLocale);
          setLocale(nextLocale);
        }}
        className="btn"
      >
        Change Language
      </text>
    </view>
  );
}

```



## Extracting Translations

If you downloaded many translations but your project only uses some of them, you may need to extract the translations to reduce the bundle size.

There are two ways to extract the translations used in your source code.

### Plugin (Recommended)

You can use the [`rsbuild-plugin-i18next-extractor`](https://github.com/rstackjs/rsbuild-plugin-i18next-extractor) to extract the translations used in the source code. This plugin is based on [i18next-cli](https://github.com/i18next/i18next-cli), and uses the Rspack module graph to extract i18n messages from modules that are actually imported by the current build. This allows it to extract translations on demand, avoid bundling unused messages, and reduce the risk of missing translations that are used through imported dependencies.

:::tip
This plugin requires Node.js 22 or above.
:::

First, install the plugin and its `i18next-cli` peer dependency:


```sh [npm]
npm install rsbuild-plugin-i18next-extractor i18next-cli -D
```

```sh [yarn]
yarn add rsbuild-plugin-i18next-extractor i18next-cli -D
```

```sh [pnpm]
pnpm add rsbuild-plugin-i18next-extractor i18next-cli -D
```

```sh [bun]
bun add rsbuild-plugin-i18next-extractor i18next-cli -D
```

```sh [deno]
deno add npm:rsbuild-plugin-i18next-extractor npm:i18next-cli -D
```

Enable the plugin in `lynx.config.ts` and specify the `localesDir` option, which is the directory path of the raw translations:

The examples below assume your raw translations live in `src/locales/`.

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginI18nextExtractor } from 'rsbuild-plugin-i18next-extractor';

export default defineConfig({
  plugins: [
    pluginI18nextExtractor({
      localesDir: './src/locales',
    }),
  ],
});
```

You should import the translations from the `localesDir` which you specify above:

```ts title="src/i18n.ts"
import i18next from 'i18next';
import type { i18n } from 'i18next';

import enTranslation from './locales/en.json';

const localI18nInstance: i18n = i18next.createInstance();

localI18nInstance.init({
  lng: 'en',
  resources: {
    en: {
      translation: enTranslation,
    },
  },
});
```

:::tip
After running `DEBUG=rsbuild:i18next rspeedy dev` or `DEBUG=rsbuild:i18next rspeedy build`, you can view the extracted translations in the `node_modules/.rsbuild-plugin-i18next-extractor` directory.
:::

#### Configuration Options

The plugin scans `node_modules` by default. You can exclude files using the `i18nextToolkitConfig.extract.ignore` option:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginI18nextExtractor } from 'rsbuild-plugin-i18next-extractor';

export default defineConfig({
  plugins: [
    pluginI18nextExtractor({
      localesDir: './src/locales',
      i18nextToolkitConfig: {
        extract: {
          ignore: ['node_modules/**'],
        },
      },
    }),
  ],
});
```

You can also provide a callback for missing translation keys:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginI18nextExtractor } from 'rsbuild-plugin-i18next-extractor';

export default defineConfig({
  plugins: [
    pluginI18nextExtractor({
      localesDir: './src/locales',
      onKeyNotFound: (key, locale, localeFilePath, entryName) => {
        console.warn(`Missing translation key: ${key} for locale: ${locale}`);
      },
    }),
  ],
});
```

#### Advanced: Dedupe translations in Lynx bundles

For Lynx apps, it is recommended to use [`@lynx-js/i18next-translation-dedupe`](https://github.com/lynx-family/lynx-stack/tree/main/packages/i18n/i18next-translation-dedupe) together with `rsbuild-plugin-i18next-extractor` to avoid bundling the same translations twice.

`@lynx-js/i18next-translation-dedupe` reads the translations extracted by `rsbuild-plugin-i18next-extractor`, skips the extractor's default rendered asset, and writes the translations into the Lynx bundle `customSections` for runtime loading.

First, install the package:


```sh [npm]
npm install @lynx-js/i18next-translation-dedupe -D
```

```sh [yarn]
yarn add @lynx-js/i18next-translation-dedupe -D
```

```sh [pnpm]
pnpm add @lynx-js/i18next-translation-dedupe -D
```

```sh [bun]
bun add @lynx-js/i18next-translation-dedupe -D
```

```sh [deno]
deno add npm:@lynx-js/i18next-translation-dedupe -D
```

Then add `pluginLynxI18nextTranslationDedupe()`:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginLynxI18nextTranslationDedupe } from '@lynx-js/i18next-translation-dedupe';
import { pluginI18nextExtractor } from 'rsbuild-plugin-i18next-extractor';

export default defineConfig({
  plugins: [
    pluginI18nextExtractor({
      localesDir: './src/locales',
    }),
    pluginLynxI18nextTranslationDedupe(),
  ],
});
```

At runtime, load the extracted translations from the Lynx bundle `customSections`:

```ts title="src/i18n.ts"
import i18next from 'i18next';
import type { i18n } from 'i18next';
import { loadI18nextTranslations } from '@lynx-js/i18next-translation-dedupe';

const localI18nInstance: i18n = i18next.createInstance();

localI18nInstance.init({
  lng: 'en',
  resources: loadI18nextTranslations(),
});
```

### CLI

You can also use the [i18next-cli](https://github.com/i18next/i18next-cli) to extract translations.

:::tip
The i18next-cli requires Node.js 22 or above.
:::

First, install the CLI:


```sh [npm]
npm install i18next-cli -D
```

```sh [yarn]
yarn add i18next-cli -D
```

```sh [pnpm]
pnpm add i18next-cli -D
```

```sh [bun]
bun add i18next-cli -D
```

```sh [deno]
deno add npm:i18next-cli -D
```

Add an `i18next.config.ts` file at the project root. For example:

```ts title="i18next.config.ts"
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'zh'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'src/locales/{{language}}.json',
  },
});
```

You can adjust `locales`, `extract.input`, and `extract.output` to match your project structure. If you use multiple namespaces, include `{{namespace}}` in the output pattern.

Then run the following command to extract translations:


```sh [npm]
npm i18next-cli extract
```

```sh [yarn]
yarn i18next-cli extract
```

```sh [pnpm]
pnpm i18next-cli extract
```

```sh [bun]
bun i18next-cli extract
```

```sh [deno]
deno i18next-cli npm:extract
```



---
url: /guide/devtool.md
---

# Lynx DevTool

Lynx DevTool is a collection of performance and debugging tools for Lynx apps.

You need to [integrate DevTool](/guide/start/integrate-lynx-devtool.md) into your Lynx pages, and then connect to the device via the [DevTool Desktop Application](#run-lynx-devtool-desktop-application) to debug the page.


## Experience Lynx DevTool

### Run Lynx Explorer

Please visit [Lynx Explorer](/guide/start/quick-start.md) and follow the documentation to run Lynx Explorer app locally.

### Enable Debugging Feature in Lynx Explorer

![Lynx DevTool Switch Page](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-ios.png)
Ensure that the Lynx Debug and Lynx DevTool switches are enabled in the Switch page of Lynx Explorer.

### Run Lynx DevTool Desktop Application

:::tip Get Lynx DevTool Desktop Application
You can visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to get the latest version of Lynx DevTool desktop application.
:::

Launch Lynx DevTool Desktop Application.

### Use Data Cable to Connect Debugging Device

Use a data cable to connect the debugging device, and Lynx DevTool Desktop Application will automatically recognize the debugging device and display the Lynx app information on the debugging device.

## View Device Connection Status

![View Device Connection Status](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-using-devtool-toolbar-connection.png)
In the toolbar, you can view the connection status of the current device.

- USB represents that the device is connected via USB cable.
- Time represents the delay of communication with the device.

## Choose Debugging Device

![Choose Debugging Device](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-using-devtool-toolbar-choose-device.png)
In the toolbar, you can click this button, and select other connected devices from the pop-up menu.

![Choose Debugging Device](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-device-menu.png)
:::tip Tip
After switching devices, please ensure that the Lynx app on the device is running in the foreground.
:::

## Common Issues and Troubleshooting

**Question**: Why can't Lynx DevTool desktop application recognize my debugging device?

**Answer**: Make sure you have connected your development device (e.g., your MacBook) and the device running the Lynx application (e.g., your phone) using a data cable.

For iOS devices, ensure that you have installed Xcode and iOS SDK with matching versions on your development device.

For Android devices, in addition to ensuring a data cable connection, you also need to enable Developer Mode and USB debugging on your Android device:

1. Enable Developer Mode on your Android device - specific steps may vary between devices, please refer to the [Android Developer Documentation](https://developer.android.com/studio/debug/dev-options)
2. Enable "USB Debugging" in the developer options
3. When the device is connected to your computer, an authorization prompt will appear, click "Allow"

You can try launching Xcode or Android Studio to compile and run an application to verify that you can connect to the device properly.

## Compatibility

**Error:** No compatibility data found for `devtool.integration.connection`
## Provide Feedback

Welcome to experience Lynx DevTool. If you need a hand, please file an issue in [Lynx Issues](https://github.com/lynx-family/lynx-devtool/issues). Thank you!



---
url: /guide/devtool/panels.md
---

# Panels

## Choose Page and Debugging Options

![Choose Page and Debugging Options](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-using-devtool-toolbar-card-settings.png)
There may be multiple Lynx page instances at the same time in a page.
For debugging between different page instances,
you need to select the current page instance to be debugged.

![Debugging Options](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-setting-menu.png)
At the bottom of the debugging options page, you can select the page to be debugged.
Move the mouse over the page path, and the page thumbnail will be displayed on the right.

In the debugging options menu, there are App Info for displaying application and Lynx information,
and Settings for setting debugging options.

## Debugging Panels

Dive into the debugging functions.

### Elements

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-elements.png)

The **Elements** panel allows you to inspect and modify elements.

- [View Element Nodes](/guide/devtool/panels/elements-panel.md#view-dom-nodes)
- [Edit the Element](/guide/devtool/panels/elements-panel.md#edit-the-dom)
- [View and Change CSS](/guide/devtool/panels/elements-panel.md#view-and-change-css)
- [Find Invalid, Overridden, and Other CSS](/guide/devtool/panels/elements-panel.md#find-invalid-overridden-and-other-css)

### Console

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-console.png)

Use the **Console** panel to view logged messages and run JavaScript.

- [View Logged messages](/guide/devtool/panels/console-panel.md#view-logged-messages)
- [Run JavaScript](/guide/devtool/panels/console-panel.md#run-javascript)
- [Clear the Console](/guide/devtool/panels/console-panel.md#clear-the-console)

### Sources

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-sources.png)

Use the **Sources** panel to debug JavaScript.

- [File Navigation](/guide/devtool/panels/sources-panel.md#file-navigation)
- [Pause Code with Breakpoints](/guide/devtool/panels/sources-panel.md#pause-code-with-breakpoints)
- [Debug JavaScript](/guide/devtool/panels/sources-panel.md#debug-javascript)
- [Debug Original Code with Source Maps](/guide/devtool/panels/sources-panel.md#debug-original-code-with-source-maps)
- [Debug the Main Thread](/guide/devtool/panels/sources-panel.md#debug-the-main-thread)

### Layers

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-panel-layers.png)

Helps you understand the composition of Lynx pages and how the framework presents content, analyzing its 3D layers to discover rendering issues.

- [View page Layers](/guide/devtool/panels/layers-panel.md#view-page-layers)
- [Inspect page Layers](/guide/devtool/panels/layers-panel.md#inspect-page-layers)



---
url: /guide/devtool/panels/elements-panel.md
---


.full_image {
  width: 800px;
  margin: 20px;
}

# Elements Panel

The **Elements** panel allows you to inspect and modify element and element tree.

## Overview

The **Elements** panel provides a powerful interface for inspecting and manipulating the element and the element tree. You can select specific element using the element tree and use other tools to make modifications.

The **Elements** panel also includes tabs for the following related tools:

- **Styles**:
  - [View and debug](#viewing-and-changing-css) CSS rules applied to an element from all stylesheets.
  - Find any [invalid, overridden, or otherwise not working CSS](#invalid-and-declarations-with-invalid-values).
  - Modify elements by [adding declarations](#adding-css-declarations-to-an-element), and [interacting with the Box model](#interacting-with-elements-in-the-lynx-page-preview-window-via-the-box-model).
- **Computed**: Lists the resolved properties applied to an element.

### Open the Elements Panel

By default, when you open the Lynx DevTool desktop application and connect to a device to debug Lynx pages, the **Elements** panel will open.

To manually open or switch back to the **Elements** panel from another panel, click on the **Elements** tab in the main panel of the DevTool window.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-drawer.png)
### Preview Panel

The left side of the **Elements** panel is the Lynx Page Preview Window, showing the Lynx page content for mobile devices in real-time.

#### Introduction to the Preview Panel

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast.png)
As shown in the above figure:

1. Click the reload icon in the upper left corner to refresh the Lynx page.
2. SD/HD toggle switch, adjust current debugging screen mirroring clarity.
3. Switch current screen mirroring mode, there are two modes: LynxView and FullScreen.
   - When there are multiple Lynx pages on the current screen, it is recommended to use the LynxView screen mirroring mode, so that you can focus on the currently selected debugging page.
   - If the Lynx page has an overlay component (this component is in a separate window and may be outside the LynxView display area), it is recommended to use the FullScreen mode, and the entire screen content of the mobile phone will be captured at this time.
4. The border that separates the Elements panel and the preview window can be dragged to adjust their size.
5. Displays the JS engine used by the current page.

#### Open/Close the Preview Panel

Click on this icon to open/close the preview window.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast-switch.png)
After closing, it will be displayed as follows:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/screencast-close.png)
At this time, if an element that can generate UI is selected in the Elements panel (not all nodes on the element tree will eventually generate platform UI), the Lynx page on the mobile phone will highlight the corresponding element.

## View Element Nodes

### Inspect Nodes

1. Click on the **Inspect** icon in the upper left corner of the developer tools.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-inspect.png)
2. Click on the logo in the upper left corner of the preview window.

![Click Inspect](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-click1.png)
3. Now, the corresponding `<image></image>` node is highlighted in the element tree.

![Click Inspect](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-click2.png)
### Navigate the Element Tree with a keyboard

After selecting a node in the element tree, you can use the keyboard to browse the element tree.

1. After clicking on the **Inspect** icon in the upper left corner of the developer tools, click on the input box in the middle of the Lynx page preview window.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-key1.png)
Now, the `<input>` node is selected in the element tree.

2. Press the Up arrow key twice. `<view class="input-card-url__light">` has been selected.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/elements-key2.png)
3. Press the left arrow key. All child nodes of `<view class="input-card-url__light">` will be collapsed.

4. Press the left arrow key again, and the parent `<view class="input-card-url__light">` of `<view class="page__light">` will be selected.

5. Press the Down arrow key twice to reselect the `<view class="input-card-url__light">` node that you just collapsed. The displayed content should be as follows: `<view class="input-card-url__light">...</view>`.

6. Press the right arrow key. At this time, the `<view class="input-card-url__light">` node will be expanded.

## Edit the Element

You can dynamically modify the element and see how these changes affect the Lynx page.

### Edit Content

To modify the content of a node, double-click on the corresponding content in the element tree.

As shown above:

1. After clicking on the **Inspect** icon, click on the text **Lynx Explorer** in the Lynx page preview window. Now the `<text class="home-title__light">...</text>` node is selected in the element tree.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify1.png)
2. Press the right arrow key on the keyboard to expand the `<text class="home-title__light">...</text>` node.

3. Press the down arrow key on the keyboard, and the `<raw-text text="Lynx Explorer"><raw-text>` node is selected in the element tree.

4. Double-click on the **Lynx Explorer** on `<raw-text>`.

5. Modify the content to **Hello world**.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify2.png)
6. Press the Enter key, and you can see that the text change has taken effect both in the element tree and on the left preview window.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/text-modify3.png)
### Edit Attributes

To modify attributes, double-click on the attribute name or value. Follow the instructions below to learn how to modify the style attribute of a node.

1. Select the `<view clip-radius="true" flatten="false" style="height:100px">` node in the element tree that you want to modify.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify1.png)
2. Double-click on the part that displays `style="height:100px;"`, and the text will be highlighted.

3. Modify the **style** content to `style="width:70%;height:100px;"`.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify2.png)
4. Press the Enter key, and you can see that the width change of the view has taken effect both in the element tree and on the left preview window.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/style-modify3.png)
## View and Change CSS

### View CSS for an Element

1. Click on the **Inspect** icon, and click on the text **Lynx Explorer** in the preview window.

2. The `<text class="home-title__light">...</text>` node is selected in the element tree.

3. At this time, you can see that the **Styles** tab shows all the styles applied to the currently selected node.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-check.png)
4. Switch to the **Computed** tab in the upper tab bar, and you can see the box model of the selected node, as well as all the resolved styles finally applied to the node.

### Add CSS Declarations to an Element

If you want to change or add CSS declarations to an element, use the **Styles** tab.

1. Selected `<view clip-radius="true"...>...</text>` in the element tree.

2. On the right side of the **Styles** tab, click on the top `element.style`.

3. After clicking, enter the property name `border` and press the Enter key. A second input box will pop up, enter `black 20px`.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-modify1.png)
4. Press the Enter key again. At this time, whether it is the UI effect on the preview window or the element tree, the style change has taken effect.
   {' '}

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-style-modify2.png)
### Interact with Elements in the Lynx Page preview window via the Box Model

1. Click on the **Inspect** icon, and hover over the Go button in the preview window.

2. At this time, you can see that all the box models are highlighted in the left preview window, from the inside to the outside are **content-box**/ **padding-box** / **border-box** / **margin-box**.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/box-model.png)
3. Click Go button, then corresponding `<view ...>...</view>` node is selected in the element tree.

4. Click on the box model in the **Styles** tab on the right side, and click one by one from the inside to the outside, you can see that the left preview window is highlighted one by one in turn. Using content-box as an example, as shown in the image below:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/box-model2.png)
## Find Invalid, Overridden, and Other CSS

### Check the CSS You Wrote

Suppose you added some CSS to an element and want to make sure the new styles are applied correctly. When you refresh the page, the element looks the same as before. Something went wrong.

The first thing to do is to inspect the element and make sure the new CSS is actually applied to the element.

Sometimes, you will see the new CSS in the **Elements** > **Styles** pane, but the new CSS appears as faded text, cannot be modified, is crossed out, or a warning or hint icon is displayed next to it.

### Understand CSS in the **Styles** Pane

The Styles pane can identify various CSS issues and highlight them in different ways.

#### Invalid and Declarations with Invalid Values

The **Styles** pane will cross out the following and display a warning icon next to the following:

- When the CSS property is invalid or unknown, the entire CSS declaration (property and value).
- When the CSS property is valid but the value is invalid, the entire CSS declaration (property and value).

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check1.png)
#### Overridden

The **Styles** pane will cross out properties that are overridden by other properties according to the cascade order.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check2.png)
In this example, the `color:red;` style property on the element will override the `color:linear-gradient(120deg,#0095ff 30%,#42d392 100%);` on the `.banner.title` class.

#### Inherited and Non-Inherited

The **Styles** pane will list properties in the `Inherited from <element-name>` section based on the default inheritance relationship of the property:

- Inherited content will be shown in regular text by default.
- Non-inherited content will be shown in light text by default.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/elements/css-check3.png)
## Compatibility

### View and Edit

**Error:** No compatibility data found for `devtool.panels.elements.view-and-edit`
### Preview

**Error:** No compatibility data found for `devtool.panels.elements.preview`


---
url: /guide/devtool/panels/console-panel.md
---


.inline-content {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}
.inline-content img {
  margin: 0 5px;
  height: 2rem;
}
.margin {
  margin-top: 1rem;
  margin-bottom: 1rem;
}
.margin2 {
  margin-top: 0.5rem;
}

# Console Panel

## Overview

Use the **Console** panel to [view logged messages](#view-logged-messages) and [run JavaScript](#run-javascript). Before you start debugging, please take some time to familiarize yourself with the [Lynx JavaScript Runtime](/guide/scripting-runtime/index.md#javascript-runtime).

![Console panel](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-panel.png)
### Open the Console Panel

The Console can be opened as a panel or as a tab in the Drawer.

#### Open in the Drawer

If you want to view the Console panel while using other panels, you can open the Console in the Drawer.

Please refer to [Open the Console in the Drawer | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#drawer).

### Console Settings

Click 
**Console Settings**
 
![Console settings](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-settings.png) in the top-right corner of the 
**Console**
 panel.

![Console settings pane](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/console-settings-pane.png)
The following links explain each setting:

- [Selected context only](#filter-messages-from-different-contexts)
- [Group similar messages in console](#disable-message-grouping)
- [Eager evaluation](#disable-eager-evaluation)
- [Autocomplete from history](#disable-autocomplete-from-history)

### Console Sidebar

Please refer to [Open the Console Sidebar | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#sidebar).

## View Logged messages

The types of logs currently can be viewed include:

1. **JavaScript logs**. Including the main thread and the background thread.
   - By default, logs from the background thread are displayed in full format, while logs from the main thread are serialized as strings with the `[main-thread.js]` prefix.
   - When [Main Thread Debugging](/guide/devtool/panels/sources-panel.md#debug-the-main-thread) is enabled, logs from the main thread will also be displayed in full format.

2. **Some client logs**.

   Currently, client runtime errors and some other client logs are serialized as strings and displayed in the Console panel.

![Log type](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/log-type.png)
### Log Sources

For JavaScript logs, the `App.tsx:11` on the right side of the log represents where it logged. Clicking it will open the [Sources](/guide/devtool/panels/sources-panel.md) panel and highlight the line of code that caused the message to get logged to the Console.

![Call stack](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/call-stack.png)
### Disable Message Grouping

DevTool enables **Group similar messages in console** by default, which aggregates similar messages logged consecutively.

![Group similar log](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/group-similar-log.png)
Open [Console Settings](#console-settings) and disable this option to expand the logs that were originally grouped.

![Disable group similar log](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/disable-group-similar-log.png)
### View Stack Traces

For JavaScript errors and warnings, click 
**Expand**
 
![Stack trace expand](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/stack-trace-expand.png) to view the stack trace.

![Stack trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/stack-trace.png)
### Filter messages

#### Filter by Log Level

Please refer to [Filter by log level | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#level).

:::tip
When the sidebar is open, you cannot click the log level drop-down.
:::

#### Filter by Text

Please refer to [Filter by text | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/log#text).

#### Filter by Regular Expressions

Please refer to [Filter by regular expression | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/log#regex).

#### Filter by URL

Please refer to [Filter messages by URL | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#url).

#### Filter Messages from Different [Contexts](/guide/spec.md#scripting-runtime-enviroment①)

By default, all logs are displayed within the context of the background thread. When [Main thread debugging](/guide/devtool/panels/sources-panel.md#debug-the-main-thread) is enabled, an additional context of the main thread will be added.

As shown in the figure, `Background:-1` represents the background thread, and `Main` represents the main thread.

![Filter by context](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/filter-by-context.png)
When you [run JavaScript in the Console](#run-javascript), it will execute only within the currently selected context.

Open [Console Settings](#console-settings) and enable **Selected context only** checkbox to display logs only from the currently selected context.

![Filter by context](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/selected-context-only.png)
### Search for Text

Please refer to [Search for text in logs | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#search).

## Run JavaScript

The Console is a **REPL**, which stands for "Read, Evaluate, Print, and Loop." It reads the JavaScript you enter, evaluates your code, outputs the result of the expression, and then loops back to the first step.

You can enter expressions related to the current page in the Console, such as `this`.

You can also enter expressions unrelated to the current page, such as `1+2`.

Press Enter to get the result, and the Console will output the result of the expression below the code.

![Run script](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/run-script.png)
### String Copy Options

Please refer to [String copy options | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#string-copy-options).

![Copy string](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/copy-string.png)
For example, in this case, the results of copying are as follows:

```javascript
{"a":123,"b":"string"}
'{"a":123,"b":"string"}'
"{\"a\":123,\"b\":\"string\"}"
```

### Re-run Expressions from History

Please refer to [Re-run expressions from history | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#history).

### Watch Expression Values in Real-Time

Please refer to [Watch JavaScript values in real time with Live Expressions | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/live-expressions).

### Disable Eager Evaluation

Please refer to [Disable Eager Evaluation | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#eagereval).

### Disable Autocomplete from History

Please refer to [Disable autocomplete from history | Chrome DevTools](https://developer.chrome.com/docs/devtools/console/reference#autocomplete).

## Clear the Console

You can use any of the following workflows to clear the Console:

- <div class="inline-content margin2">
    <span>
      Click 

      **Clear Console**
    </span>

    <img
      src={
      'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/clear-console-button.png'
    }
      alt="Clear console button"
    />

    <span>
      .
    </span>
  </div>
- Right-click a log and select **Clear Console**.
- When the Console is in focus, press Control+L or Command+K.
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/console/clear-console.png" alt="Clear console" style={{ width: 800 }} />

## Compatibility

**Error:** No compatibility data found for `devtool.panels.console`


---
url: /guide/devtool/panels/sources-panel.md
---


.inline-content {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
}
.inline-content img {
  margin: 0 5px;
  height: 2rem;
}
.margin {
  margin-top: 1rem;
  margin-bottom: 1rem;
}
.margin2 {
  margin-top: 0.5rem;
}

# Sources Panel

Use the **Sources** panel to debug JavaScript. Before you start debugging, please take some time to familiarize yourself with the [Lynx JavaScript Runtime](/guide/scripting-runtime/index.md#javascript-runtime).

After DevTool is enabled, the background thread uses the PrimJS engine for debugging by default. On Android, you can also switch to the V8 engine for a more comprehensive debugging experience.

To switch to the V8 engine, open the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch), toggle the "**V8 Engine**" switch to "**On**" and restart the application. You can check the current engine type in the lower-left corner of the [Preview Window](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel).

## Overview

The **Sources** panel has three sections:

1. **File Navigation Pane**. All JavaScript files of the page are listed here.
2. **Code Editor Pane**. After selecting a file in the **File Navigation Pane**, the contents of the file are displayed here.
3. **Debugger Pane**. Various tools for inspecting the page's JavaScript.

![Sources panel](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sources-panel.png)
## File Navigation

### Open File

You can use the **File Navigation Pane** or the **Open file** feature to open the file of interest.

Click 
**More Options**
 
![More options](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/more-options.png)and select 
**Open file**
. A dialog will display.

![Open file](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/open-file.png)
You can enter the file URL here or select a file from the drop-down list.

![Open file dialog](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/open-file-dialog.png)
The bottom status bar of the **Code Editor Pane** will display the line and column number of the current mouse position.

Click 
**Show navigator**
 
![Watch Add](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-navigator.png)button to collapse/expand the 
**File Navigation Pane**
.

![File editor](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/file-editor.png)
### Close File

You can close a file in the following ways:

- Hover the mouse over the file name tab at the top of the **Code Editor Pane** and click the **close** button.
  <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/close-file-button.png" alt="Close file button" style={{ width: 400 }} />
- Right-click the file name tab at the top of the **Code Editor Pane**:
  - Close: Close the current file.
  - Close others: Close other files.
  - Close all: Close all files.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/close-file.png" alt="Close file" style={{ height: 300 }} />

### Locate File

To locate the file currently displayed in the **Code Editor Pane**:

1. Right-click anywhere in the **Code Editor Pane** or right-click the file name tab at the top of the **Code Editor Pane**.
2. Select **Reveal in sidebar**.

![Reveal in sidebar](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/reveal-in-sidebar.png)
### Search Code

To search a code segment:

1. Click **Customize And Control DevTools** <InlineIcon src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/more-options.png" alt="More options" /> > **Search** to open the **Search** panel.

   <Figure src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/search.png" alt="Search" height={300} />

2. Enter text and press Enter to search.

3. Click search results to jump to the corresponding file and the code will be highlighted.

   <Figure src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/search-panel.png" alt="Search panel" height={400} />

You can also:

- Click **Match Case** <InlineIcon src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/match-case.png" alt="Match Case" /> to make the query case-sensitive.
- Click **Use Regular Expression** <InlineIcon src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/use-regular.png" alt="Use Regular Expression" /> to search using a RegEx.
- Click **Refresh** <InlineIcon src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/refresh.png" alt="Refresh" /> to search again.
- Click **Clear** <InlineIcon src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/clear.png" alt="Clear" /> to clear the input contents.

## Pause Code with Breakpoints

By adding breakpoints, you can pause the code execution and inspect all relevant values at that moment.

Currently supported breakpoint types are as follows:

|                                Type                               | Description                                                                   |
| :---------------------------------------------------------------: | ----------------------------------------------------------------------------- |
|             [Line-of-code](#line-of-code-breakpoints)             | Pause on an exact region of code.                                             |
| [Conditional line-of-code](#conditional-line-of-code-breakpoints) | Pause on an exact region of code, but only when some other condition is true. |
|             [Logpoint](#log-line-of-code-breakpoints)             | Log a message to the Console without pausing the execution.                   |
|               [First line](#first-line-breakpoints)               | Pause on the first line of every executed JavaScript file.                    |
|                [Exception](#exception-breakpoints)                | Pause on the line of code that is throwing a caught or uncaught exception.    |

### Line-of-Code Breakpoints

Please refer to [Line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#loc).

#### Line-of-Code Breakpoints in Code

Please refer to [Line-of-code breakpoints in your code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#debugger).

#### Conditional Line-of-Code Breakpoints

Please refer to [Conditional line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#conditional-loc).

#### Log Line-of-Code breakpoints

Please refer to [Log line-of-code breakpoints | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#log-loc).

#### Manage Line-of-Code Breakpoints

Right-click the breakpoint icon or use the **Breakpoints** pane to manage line-of-code breakpoints.

- Right-click the breakpoint icon and select **Edit breakpoint** to edit it. You can also change its type from the drop-down list in the inline editor.
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/edit-bp.png" alt="Edit breakpoint" style={{ height: 200 }} />

- Click the breakpoint icon again to delete the breakpoint.

- In the **Breakpoints** pane, click the checkbox next to the breakpoint entry to enable or disable the breakpoint. When disabled, the marker next to the line number will become transparent.

  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/disable-bp.png" alt="Disable breakpoint" style={{ height: 300 }} />

- Right-click the breakpoint icon to see the options menu:
  - Remove breakpoint.
  - Edit breakpoint.
  - Disable/Enable breakpoint.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/bp-action.png" alt="Breakpoint action" style={{ height: 300 }} />

- Right-click the breakpoint entry in the **Breakpoints** pane to see the options menu:
  - Remove breakpoint.
  - Reveal location.
  - Deactivate/Activate breakpoints.
    <div class="inline-content margin2">
      <span>
        You can also use 

        **Deactivate breakpoints**

         
      </span>

      <img
        src={
        'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/deactivate-bp.png'
      }
        alt="Step out"
      />

      <span>
        button to deactivate breakpoints.
      </span>
    </div>
    When breakpoints are deactivated, DevTool will ignore all line-of-code
    breakpoints, and they will not be triggered. All breakpoints will remain in
    the same state after being reactivated.
  - Disable/Enable all breakpoints.
  - Disable/Enable breakpoints in file.
  - Remove all breakpoints.
  - Remove other breakpoints.
    <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/bp-pane-action.png" alt="Breakpoint pane action" style={{ height: 300 }} />

#### Skip Breakpoints with 'Never Pause Here' Background V8 Only

Please refer to [Skip breakpoints with 'Never pause here' | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/breakpoints#never-pause-here).

### First-Line Breakpoints Background Only

Use first-line breakpoints to pause at the entry of every executed JavaScript file.

![First line breakpoint example](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/first-line-bp-example.png)
Hover your mouse over the position shown in the image, then enable **First-Line Breakpoints**. This is a non-persistent global switch that takes effect for all pages during a single APP run. The switch state will be reset after closing and restarting the APP.

![First line breakpoint](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/first-line-bp.png)
You can debug first-line breakpoints in two ways:

1. Turn on the switch, then open the page you want to debug.
2. Open the page you want to debug, turn on the switch, and then [reload](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel) the page.

### Exception Breakpoints

Use exception breakpoints when you want to pause on the line of code that's throwing a caught or uncaught exception.

1. In the **Breakpoints** pane, click the **Pause on exceptions** button, which turns blue when enabled.
2. By default, it only pause on uncaught exceptions. If you also want to pause on caught exceptions, check the **Pause On Caught Exceptions** checkbox.

![Pause on exceptions](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/pause-on-exceptions.png)
:::warning

Currently, the PrimJS engine does not distinguish between caught and uncaught
exceptions, and all exceptions will cause a pause. In contrast, the V8 engine
distinguishes between caught and uncaught exceptions.

:::

## Debug JavaScript

By default, you can only debug the background thread. If you need to debug the main thread, please refer to the section [Debug the Main Thread](#debug-the-main-thread).

### Step Through Code

Once your code is paused, step through it, one expression at a time, investigating control flow and property values along the way.

![Pause](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/pause.png)
#### Step Over

Please refer to [Step over line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-over).

#### Step Into

Please refer to [Step into line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-into).

#### Step Out

Please refer to [Step out of line of code | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#step-out).

#### Run All Code Up to a Certain Line Background V8 Only

Please refer to [Run all code up to a certain line | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#continue-to-here).

#### Resume

Please refer to [Resume script execution | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#resume).

##### Terminate Execution Background V8 Only

To stop your script's execution after a pause, click and hold the **Resume** button and then select **Terminate script execution** button.

![Terminate script execution example](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/terminate-execution-example.png)
For example, in this case, select **Terminate script execution**, DevTool will
stop executing the script, the rest of the code in `add` will not be executed,
and you will see that the value of `count` will not change.

### View and Edit Properties

Please refer to [View and edit local, closure, and global properties | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#scope).

### View the Current Call Stack

When paused on a line of code, you can use the **Call Stack** pane to view the call stack that got you to this point.

Select an entry in the pane to jump to the line of code where the function was called. A blue arrow icon represents the currently highlighted code.

![Call stack](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/call-stack.png)
#### Copy Stack Trace

Right-click anywhere in the **Call Stack** pane and select **Copy stack trace** to copy the current call stack to the clipboard.

![Copy stack trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/copy-stack-trace.png)
For example, in this case, the copied stack trace is as follows:

```
add (App.tsx:11)
publishEvent (tt.js:148)
```

### Ignore Scripts Background V8 Only

Ignore certain scripts during debugging to skip them. When ignored, scripts will be hidden in the **Call stack** pane, and you will never step into functions from ignored scripts while stepping through code.

#### Ignore a Script from the Editor Pane

Please refer to [Ignore a script from the Editor pane | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#editor-ignore-list).

#### Ignore a Script from the Call Stack Pane

Please refer to [Ignore a script from the Call Stack pane | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#call-stack-ignore-list).

#### Show ignore-listed frames

If you need to view the complete call stack, click **Show ignore-listed frames** in the **Call Stack** pane. The ignored frames will be expanded but displayed in gray.

![Show ignore1](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-ignore1.png)


![Show ignore2](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/show-ignore2.png)
#### Unignore Scripts

To unignore scripts, follow the same steps as above and select **Remove from ignore list**.

You can also unignore scripts through the prompt at the top of the **Code Editor Pane**.

![Remove ignore](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/remove-ignore.png)
### Watch the Values of Custom JavaScript Expressions

Please refer to [Watch the values of custom JavaScript expressions | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#watch).

### Inspect and Edit Scripts

In the **Code Editor Pane**, you can browse and edit code.

#### Make Minified Files Readable

Click the `{}` button in the bottom status bar of the editor, and the **Sources** panel will present the minified file in a more readable format to improve readability.

![Format before](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/format-before.png)


![Format after](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/format-after.png)
#### Edit Scripts Background V8 Only

Please refer to [Edit a script | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#edit).

:::warning
You can only modify compiled JavaScript files. The original files reversed through SourceMap cannot be modified, and changes will not be saved after reloading the page.
:::

#### Search and Replace Text in Scripts

Please refer to [Search and replace text in a script | Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript/reference#search).

After replacing, you need to manually save the script, as referenced in [Edit Scripts](#edit-scripts).

## Debug Original Code with Source Maps Background Only

After [configuring SourceMap](/api/rspeedy/rspeedy.output.sourcemap.md), you can directly debug the original code you author in the Sources panel.

### Check If Source Maps Loaded Successfully

#### Check Load Status

When you open DevTool, it attempts to load source maps, if any.

After loading successfully, the files in the **File Navigator Pane** with orange folders are the original source files.

![Original files](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/original-files.png)
If loading fails, the **Console** logs an error similar to the following.

![Sourcemap fail](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-fail.png)
When you open any compiled file, DevTool will notify you if it found the source map.

![Sourcemap detected](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-detected.png)
#### Load a Source Map Manually

You can manually load a source map:

1. Open the compiled file, right-click anywhere in the **Code Editor Pane**, and select **Add source map**.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/add-sourcemap1.png" alt="Add sourcemap1" style={{ width: 500 }} />
2. Enter the source map URL in the textbox, then click **Add**.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/add-sourcemap2.png" alt="Add sourcemap2" style={{ width: 500 }} />

### Debug with Source Maps

1. In the original file, you can [set breakpoints](#pause-code-with-breakpoints) as you normally would, or you can set breakpoints in the compiled file, and DevTool will automatically jump to the original file.
2. After triggering a breakpoint and pausing, the **Call Stack** pane will display the name of the original file.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/original-file-stack.png" alt="Original file stack" style={{ height: 400 }} />
3. The bottom status bar of the **Code Editor Pane** will show a link to the compiled file it points to. Click it to jump to the corresponding file.
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/sourcemap-from.png" alt="Sourcemap from" style={{ width: 500 }} />

## Debug the Main Thread

Debugging the main thread is similar to debugging the background thread, but it requires some additional steps to enable.

### Preparation

To debug the main thread, you need to start the project in **dev** mode using rspeedy.

You can check the following two items to ensure preparation is done:

1. A `debug-info.json` file is generated in the [intermediate output directory](/api/rspeedy/rspeedy.distpath.intermediate.md).
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/debug-info.png" alt="Debug info" style={{ height: 200 }} />
2. In the `tasm.json` file of the [intermediate output directory](/api/rspeedy/rspeedy.distpath.intermediate.md), the `templateDebugUrl` field is a valid URL pointing to the `debug-info.json` file mentioned in step one. Refer to [rspeedy.dev.assetprefix](/api/rspeedy/rspeedy.dev.assetprefix.md).
   <img class="margin" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/template-debug-url.png" alt="Template debug url" style={{ width: 600 }} />

### Enable Main Thread Debugging

Hover over the position shown in the image below, then enable **Main Thread Debugging**. This is a non-persistent global switch that takes effect for all pages during a single APP run. The switch state will be reset after closing and restarting the APP.

![Main thread debugging](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/main-thread-debugging.png)
To enable main thread debugging:

1. Turn on the switch, then open the page you want to debug. Or open the page you want to debug, turn on the switch, and then [reload](/guide/devtool/panels/elements-panel.md#introduction-to-the-preview-panel) the page.
2. The `main-thread.js` file of the main thread will be displayed in the **File Navigator Pane** (formerly known as `lepus.js`).
3. In the **Threads** pane, switch to **Main** to start debugging.

![Main target](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/sources/main-target.png)
In the **Threads** pane, you can switch between debugging the main thread or the background thread. The blue arrow icon represents which context is selected. The currently paused thread will be marked as **paused**.

## Compatibility

### Breakpoints

**Error:** No compatibility data found for `devtool.panels.sources.breakpoints`
### JS Engine

**Error:** No compatibility data found for `devtool.panels.sources.JSEngine`


---
url: /guide/devtool/panels/layers-panel.md
---


.full_image {
  width: 800px;
  margin: 20px;
}

# Layers Panel

The **Layers** panel helps you understand the composition of Lynx pages and how the framework presents content, analyzing its 3D layers to discover rendering issues.

## Overview

Use the **Layers** panel to perform the following operations:

- View page layers
- Inspect page layers

### Open the Layers Panel

To open the Layers panel, follow these steps:

1. Press **Command+Shift+P** to open the command menu.
2. Start typing **Layers**, select **Show Layers**, and then press **Enter**.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/open-layers.png)
Or, select the More options in the upper right corner -> **More tools** -> **Layers**.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/open-layers2.png)
## View page Layers

The leftmost part of the **Layers** panel lists all the rendered layers of the Lynx page in an expandable tree. This tree structure is updated as the mobile **Lynx** page is updated. Layers are identified by their **CSS** selector or a number (followed by the layer size in pixels).

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/view-layers.png)
Hover the mouse over a layer to highlight it on the Lynx page preview window. A tooltip will be displayed on the page preview, which contains the following information:

- The selector of the layer
- The size of the layer (in pixels)

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/view-layers-screen.png)
## Inspect page Layers

Click on a layer to view more information in the **Details** pane.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/check-layer-details.png)
Depending on the layer, the following information will be displayed:

- Size
- Compositing reason
- Memory estimate
- Number of draws

The following figure shows the stacking and arrangement of the layers of this **Lynx** page.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/layer-3d-view.png)
To move the chart, do the following:

- Use **WASD** to move the chart. Press W to pan up, A to pan left, S to pan down, and D to pan right.
- Click the **Pan Mode** icon to move along the X and Y axes.
- Click the **Rotate Mode** icon to rotate along the Z axis.
- Click **Reset Transform** to reset the chart to its original position.
- Scroll the mouse wheel up to zoom in.
- Scroll the mouse wheel down to zoom out.

To view the element corresponding to the layer in the **Elements** panel, right-click on the corresponding layer in the chart or layer tree, and then click **Reveal in Elements panel**.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/layers/layer-element.png)
## Compatibility

**Compatibility Table**
**Query:** `devtool.panels.layers`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.0 | - |

**Description:** View page layers




---
url: /guide/devtool/panels/preact-devtools-panel.md
---


.full_image {
  width: 800px;
  margin: 20px;
}

# Preact Devtools Panel

The **Preact Devtools** panel helps you inspect the hierarchy of ReactLynx components, displaying information such as component props, state, and file paths. The Preact Devtools panel is based on the [Preact Devtools](https://preactjs.github.io/preact-devtools/) web browser extension and offers the same user experience.

## Overview

With the **Preact Devtools** panel, you can:

- View the component hierarchy of ReactLynx
- Modify props or state and see real-time updates
- Use ClickToComponent to navigate to component source code
- Use the Profiler to analyze application performance

### Open the Preact Devtools Panel

In the DevTool window, click the Preact Devtools tab in the main panel to open it.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/open-preact-devtools.jpg)
Note: Before using the **Preact Devtools** panel, you need to import [`@lynx-js/preact-devtools`](https://www.npmjs.com/package/@lynx-js/preact-devtools) at the **first line** of your ReactLynx application's entry file:

```js
import '@lynx-js/preact-devtools';
```

## View Component Hierarchy

The left side of the **Preact Devtools** panel shows the complete hierarchy of the ReactLynx application, while the right side displays detailed information about the selected component, including its props, state, and file path.

Hover over a component to highlight its corresponding box model in the preview window on the left.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/component-hierarchy.jpg)
## View and Modify Props or State

On the right side of the **Preact Devtools** panel, you can directly modify the props or state of components, and the ReactLynx application's UI will update in real-time.

As shown below, we changed the state used for counting in the `Counter` component from `1` to `2`, and the counter UI on the page also changed from `1` to `2`.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/state-modify.jpg)
## ClickToComponent for Source Navigation

We integrated the [ClickToComponent](https://github.com/ericclemmons/click-to-component) into the **Preact Devtools** panel. By clicking the file path under **source location**, VSCode will automatically open the file containing the component and navigate to the corresponding line and column.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ClickToComponent.jpeg)
## Profiler

The Profiler panel supports performance analysis of ReactLynx component rendering time on background thread. Click the button in the top-left corner to start recording, let the application run for a while, and then click the button again to stop. You will then get information about all Preact commits during that time, as well as the rendering time of each component within the same commit.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/preact-devtools-profiler.jpg)


---
url: /guide/devtool/trace.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Trace

Trace is a performance analysis tool. With Trace, you can obtain a detailed rendering workflow of Lynx pages, making it easier to locate, analyze, and fix issues such as jank and long-running tasks.

## Core Capabilities of Trace

### 1. Visualizing the Rendering Pipeline

Trace provides a complete timeline view of the entire page process, detailing each stage: script execution, element construction, layout calculation, final rendering and others. With Trace, you can:

- Clearly see the time distribution for each key stage (such as layout and painting);
- Directly identify bottleneck nodes and performance issues;
- Detect redundant or repeated rendering tasks to optimize page performance.

This end-to-end visualization is especially valuable for page optimization and tuning complex page performance.

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace_render_pipeline_latest.png)
### 2. Tracing Engine Execution

Trace dives deep into the [Engine](/guide/spec.md#engine) and thoroughly records:

- The sequence of task scheduling and queue switching
- The full picture of event handling chains
- Precise timing and relationships for API calls

This information is useful for analyzing issues like asynchronous task congestion or event response delays.

![Trace Task Scheduling](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-scheduling.png)
### 3. Rich Performance Analysis Tools

Trace is a multidimensional performance analysis platform:

- **[Element](/guide/spec.md#element) Analysis**: Track changes in the Element tree structure, identify high-frequency or heavy node operations, and uncover performance risks in your page structure.

![Element](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/element-render-analysis-latest.png)
- **[NativeModules](/guide/spec.md#native-module) Call Analysis**: Monitor detailed NativeModules call processes, clearly display the timing and parameters of each NativeModule call, and pinpoint potential bottlenecks.

![NativeModules](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-flow.png)
- **Smoothness Analysis**: Use flame charts of task durations to quickly locate the root causes of jank, helping you optimize animations and interactions.

![Trace Frame](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-frame.png)
## Next Steps

[Record Trace

Learn how to record a trace

](/guide/devtool/trace/record-trace)
## Compatibility

**Compatibility Table**
**Query:** `devtool.trace`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |

**Description:** Trace Tool




---
url: /guide/devtool/trace/record-trace.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Record Trace

This article aims to help you use DevTool to record Trace for Lynx pages. By following these steps, you will be able to capture detailed information about the page rendering process and engine execution, enabling effective performance analysis and problem diagnosis.

## Setup

1. Install [DevTool Desktop Application](/guide/devtool/panels.md#run-lynx-devtool-desktop-application).
2. Use the latest [LynxExplorer app](https://github.com/lynx-family/lynx/releases) or [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md) into your application.
3. Use a data cable to connect your device to your computer.

## Record Trace

### Select Trace
Open the DevTool desktop application and choose `Trace` from the topbar.
![Select Trace Panel](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/select-lynx-trace-panel-latest2.png)### Select the app
Pick the target app you want to profile from the available device list.
![Select Target App](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/select-target-app-latest.png)### Start recording
Press the `Start` button to start recording trace.
![Start Trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/start-trace-latest.png)### Stop recording
Click the `Stop` button to stop recording trace.
![Stop Trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/stop-trace-latest.png)### Analyze
After stopping, the trace data will be displayed for analysis.
![Analyze Trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/analyze-trace-latest.png)### Download trace data(optional)
If needed, click the `Download` button to save the trace file to your computer.
![Download Trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/download-trace-latest.png)### View or manage historical trace data
Click **History** button to see previous trace data.
![Trace History](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/history-trace-latest.png)You can select a trace file to `view`, `download`, or `delete` as needed on Trace History panel.

### FAQ

##### After clicking `Start` button, the message "Current app does not integrate lynx and lynx-trace components with dev version, please integrate dev version first according to the following document" appears.

- Use the latest [LynxExplorer app](https://github.com/lynx-family/lynx/releases), or refer to [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md) to integrate the dev version of lynx.

##### After clicking `Start` button, the message "Tracing already started" appears.

- A trace recording is already in progress. Click `Stop` button to end it.

## Next Steps

[Advance Usage

Explore advanced features like recording startup trace, JavaScript profiling, and custom trace events

](/guide/devtool/trace/launch-trace)


---
url: /guide/devtool/trace/trace-ui-basic-usage-guide.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Trace UI Basic Usage Guide

This guide introduces the main UI structure and common operations to help you quickly get started with performance analysis.

## UI Structure Overview

![UI Structure Overview](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-ui-structure-overiview-3-5.png)
The Trace UI consists of the following key components:

- Topbar: Includes a search box, SourceMap Decode, Focus LynxView, and other features.
- Timeline: Displays the occurrence and duration of TraceEvents. Supports adding annotations (notes), measuring intervals, and more.
- TrackTreeView: Organizes TraceEvents by track (typically one or more per thread), making it easy to distinguish between different threads/tasks.
- DetailPanel: Shows detailed information about a selected TraceEvent, including parameters, duration, thread, process, and more.

## Common Operations

### Open a Trace File

- Drag and drop a trace file directly onto the page for automatic parsing and display of trace.

### Zoom and Pan the Timeline

- Zoom in/out: Use the `w` (zoom in) and `s` (zoom out) keys.
- Pan left/right: Use the `a` (left) and `d` (right) keys.

### Search for TraceEvents

![Search for TraceEvents](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/search-trace-event.PNG)
- Enter TraceEvent names, parameters, or keywords in the Topbar search box to quickly locate events.
- Press the `f` key to jump to the currently selected search result.
- Click the arrow at the end of the search box to jump to the previous/next result, or press Enter to move to the next result.
- The Timeline will highlight the currently selected search result for easy identification.

### View TraceEvent Details

- Click any TraceEvent in the Timeline to view its detailed parameters, duration, process, and thread information in the DetailPanel.

### Aggregate TraceEvents

![Aggregate TraceEvents](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/aggregate-trace-event.PNG)
- Select a range of TraceEvents by dragging with the left mouse button across one or more tracks. Events will be aggregated by name.
- Aggregated results are shown in the DetailPanel, including total duration, average duration, and occurrence count.
- Click the column headers in the aggregation results to sort by name, total duration, average duration, or count.

### Add Timeline Annotations

![Add Timeline Annotations](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/add-timeline-annotations-latest.png)
- Click on the Timeline to add a note at the corresponding position. Notes can be named for easier identification and navigation.

### Measure Time Intervals

![Measure Time Intervals](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/measure-time-intervals.png)
- Click and drag on the Timeline to measure the interval between two points. This is useful for precisely analyzing the duration of tasks or operations.

### Focusing LynxView

Trace data may contain events from multiple Lynx pages. Trace supports focusing on one or more specific Lynx pages, making it easier to locate and analyze performance issues for particular pages.

#### 1. Click Focus LynxView button
![Force LynxView Button](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-trace.png)#### 2. Select the Lynx page(s) by URL
![Force LynxView Choose](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-choose-trace-latest.png)After selecting the Lynx page(s), Trace events from unselected pages will be grayed out.
![Force LynxView After Choose](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/focus-lynxview-after-trace-latest.png)
### Querying Lynx Engine Version

Search for LynxEngineVersion or Version to find the Lynx Engine version.

![Lynx Engine Version](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/lynx-engine-version-trace.png)
### Querying the System Where the Trace Was Recorded

1. Enter a colon in the Topbar search box to enter SQL query mode;
2. Input the following SQL statement to query the system information where the Trace was recorded:

```sql
select name, str_value from metadata where name like "system%";
```

![Trace System](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/record-trace-system-machine-trace.png)
## Additional Resources

For a more detailed guide on using the Trace UI and its advanced features, please refer to the official Perfetto documentation: [perfetto-ui](https://perfetto.dev/docs/visualization/perfetto-ui)



---
url: /guide/devtool/trace/launch-trace.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Record Trace During App Startup

Trace supports recording trace during the app startup process, which is essential for analyzing and optimizing app's start performance.

### Click Startup Trace
In the topbar, click the `Startup Trace` button.
![Startup Trace Configuration](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/startup-trace-config-latest.png)### Set duration (seconds)
Enter the desired duration for recording trace during app startup. Press the `Enter` key to save your configuration.
![Startup Trace Duration](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/startup-trace-dur-latest.png)### Restart application
Close and relaunch your app. Trace will automatically record trace during the startup period.
### Load startup trace
After the app launches, choose target app, then click the `Load Trace` button in Lynx DevTool.
![Load Startup Trace](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/load-startup-trace-latest.png)### View the startup trace
Once the trace data has loaded, you will see a visualization of the app’s startup process for detailed analysis.
![Load Startup Trace Success](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/load-startup-trace-success-latest.png)
### FAQ

##### After clicking `Load Trace` button shows: "Startup tracing is not enabled, cannot pull trace data"

- Make sure to set a valid trace duration (greater than 0) in Startup Trace Configuration, then restart the app and click `Load Trace` button again.
- Ensure a Lynx page is opened during or after the app startup process before clicking `Load Trace` button.

##### Clicking `Load Trace` button shows: "Startup tracing is in progress, please try again later"

- The app startup trace is still being recorded. Please wait for the process to finish and try clicking `Load Trace` button again later.



---
url: /guide/devtool/trace/js-profile.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Analysis JavaScript

Trace supports recording detailed JavaScript profile data. A JavaScript Profile is a collection of stack traces sampled during execution, which is crucial for pinpointing performance hotspots and bottlenecks. This allows you to analyze [script](/guide/spec.md#javascript-script) execution performance.

### Click `JS Profile` and Select the correct scripts engine
Based on the background thread scripts engine used by your Lynx page, choose the appropriate value in the JS Profile selection.
- disable: Do not enable JavaScript profiling;
- [primjs](/guide/spec.md#primjs-vm): Enable profiling for the PrimJS JavaScript engine.
- [v8](/guide/spec.md#v8-javascript-core-quickjs-hermes-etc): Enable profiling for the V8 JavaScript engine.
![Choose JS Profile Type](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/choose-js-profile-type-latest.png)### Start recording
Click `Start` button to begin recording trace.
![Start Recording JavaScript Profile](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/start-js-profile-trace-latest.png)### Stop recording
When finished, click `Stop` button to end the recording.
![Stop Recording JavaScript Profile](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/stop-js-profile-trace-latest.png)### Decode JavaScript Profile Data using sourcemap (Optional)
If your scripts is [minified](/api/rspeedy/rspeedy.minify.md), you can use [sourcemap](/api/rspeedy/rspeedy.sourcemap.md) to decode profile data.
![Decode JavaScript Profile](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/sourcemap-decode-latest.gif)
### FAQ

##### No JavaScript profile data after recording trace

- Make sure you have selected the correct script engine before starting recording.
- On iOS, ensure both Lynx DevTool and [PrimJS Debugging](/guide/start/integrate-lynx-devtool-advanced.md) are enabled.

##### No scripting resource found after clicking SourceMap Decode

- Ensure you start trace recording before opening the Lynx page so that the script resource name can be captured.



---
url: /guide/devtool/recorder.md
---

# Recorder

Recorder is a tool designed for the Lynx framework to facilitate the recording and replay of page runtime states. Its core functionality involves precisely capturing the complete state of a page at a specific moment and serializing it into a portable recording file for subsequent high-fidelity replay.

## What it does？

Unlike traditional screen recording technologies, Recorder achieves "Deterministic Replay." During the replay process, the system not only reconstructs the complete UI hierarchy and rendering data from the time of recording but also preserves all page interactivity. Crucially, it achieves temporal consistency by hijacking and mocking time-related APIs, ensuring that time-sensitive operations within the replayed environment yield the same results as they did during the original session.

Recorder features cross-device replay capabilities. Through its integrated Replayer decoder, a recording file can be parsed and replayed on any device that supports the Lynx framework, regardless of hardware model or operating system. For instance, a session recorded on an iPad can be accurately reproduced on an iPhone, an Android device, or even on desktop and TV applications built with the same Lynx technology stack.

## What can you use it for?

As an application's feature set expands, Lynx pages often become tightly coupled with the native application environment. This includes dependencies on custom NativeModules or private cloud services for data and resource management.

![device-connect](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recorder_main_page.png)
When diagnosing complex issues, this strong coupling becomes a major impediment to external collaboration and debugging, leading to problems such as build failures, complex authentication procedures, and inaccessible backend services. In such scenarios, traditional methods like code review are inefficient, while source-level debugging is often impractical due to environmental discrepancies.
A core design objective of Recorder is to decouple the page from its private environment. A recording file encapsulates all information required for the page to run, including the view hierarchy, data state, and responses from asynchronous requests. During replay, all external dependencies are simulated using the data contained within the recording file, eliminating the need for any live network requests. This makes the debugging process entirely independent of the original production environment.
Technical Advantages:

- Environment-Agnostic: Debuggers do not need to compile the original application, configure complex authentication, or set up specific development environments.
- Self-Contained Context: A single recording file contains all the necessary context to reproduce an issue.
- Efficient Collaboration: The party reporting the issue simply provides a recording file, allowing the recipient to debug in a standardized replay environment. This significantly reduces communication overhead and the difficulty of issue reproduction.

## Try Recorder

Recorder's record and replay capabilities are already integrated by default in LynxExplorer. You can follow the steps below to experience them.

### Download and install LynxExplorer
Please visit [LynxExplorer](/guide/start/quick-start.md#prepare-lynx-explorer) and follow the documentation to run LynxExplorer app locally.
### Start record
1. Connect the device to your PC via USB, and select the target application in the Tab.
![device-connect](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recorder-device-connect.png)2. Enter the Recorder plugin dashboard and click the Start button to activate.
![start-record](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/start-record.png)3. Operate on your phone, navigate to the target page you want to record and interact with it until it reaches the desired state.
:::note
It is especially important to note that, in order to ensure the completeness of the recorded page data, please make sure to click Start **before** navigating to the target page.
:::
Here is a sample page that you can access by scanning the QR code or entering the link in LynxExplorer.
**This is an example below: gallery**

**Bundle:** `dist/GalleryComplete.lynx.bundle` | Web: `dist/GalleryComplete.web.bundle`

```tsx {6}
import { root } from "@lynx-js/react";
import { furnituresPictures } from "../Pictures/furnitures/furnituresPictures.jsx";
import Gallery from "./Gallery.jsx";

function GalleryComplete() {
  return <Gallery pictureData={furnituresPictures} />;
}

root.render(<GalleryComplete />);

```


5. Click the Stop button to end the record.
After stopping the record, the Recorder dashboard will automatically retrieve the recorded artifact from your device and provide a preview image to help you easily identify the target page.
![end-record](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/end-recordv2.png)### Page Replay
1. Artifact Hosting
The Lynx DevTool Application only provides local file hosting for each recorded artifact. If you need to share the record artifact or access it across devices, you will need to host the artifact separately.
2. Replay using LynxExplorer
Here is a sample recorded artifact that you can replay by scanning the QR code or entering the link in LynxExplorer.
copy-link
:::note
It is especially important to note that if you are using a self-hosted artifact URL for replay, you need to append the Recorder Header to the artifact URL to indicate that the artifact is from Recorder.
Original artifact URL:
```txt
https://lynx.recorder.artifacts/LynxRecorder.json
```
Append the Recorder Header:
```txt
file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json
```
:::
LynxExplorer can fully reproduce the recorded page.
![replay-show](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/replay.png)
## Integrate Recorder into your own application

### Switch to the dev version
Since the record and replay process of Recorder covers the entire rendering process of Lynx and requires support from the underlying Lynx engine, we have released a separate dev version apart from the official Lynx release to prevent these record-related codes from affecting production environments. If you want to integrate Recorder, you need to change the version numbers of both Lynx and LynxDevtool in your project to the corresponding dev versions. [integrate lynx dev version](/guide/start/integrate-lynx-dev-version.md)
### Record capability integration
The record capability can be integrated simply by using the dev version, with no additional adaptation required.
### Replay capability integration
Recorder provides a highly encapsulated replay module, which is integrated into your application together with LynxDevTool. You only need to provide a simple entry point as described below.
Choose your target platform to view the specific integration steps:
iOSAndroidHarmonyOS1. In the Podfile, additionally include LynxRecorder for the LynxDevtool module.
```ruby
pod 'LynxDevtool', lynxDevVersion, :subspecs => [
    'Framework',
    'LynxRecorder'
]
```
2. Use LynxRecorderViewController to replay the recorded page.
:::note Swift integration considerations
LynxRecorder is written in Objective-C. If you want to call its methods from a Swift project, you need to provide a corresponding bridge file as described in [Importing Objective-C into Swift](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift).
Add the following content to the bridge file:
```objective-c title="BridgeFile"
#import <LynxDevtool/LynxRecorderViewController.h>
```
:::

**Objective-C**

```objective-c
#import <LynxDevtool/LynxRecorderViewController.h>

LynxRecorderViewController *recorderVC = [[LynxRecorderViewController alloc] init];
recorderVC.url = @"file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json";
UINavigationController *nav = [[UINavigationController alloc] initWithRootViewController:recorderVC];
[self presentViewController:nav animated:YES completion:nil];
```


**Swift**

```swift
let recorderVC = LynxRecorderViewController()
recorderVC.url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
present(recorderVC, animated: true, completion: nil)

```

1. Add a Recorder page entry

**Java**

```java
import android.app.Activity;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import com.lynx.devtool.recorder.LynxRecorderActivity;
import com.lynx.devtool.recorder.LynxRecorderEnv;

public class MainActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        buildLynxRecorderView();
    }

    private LynxView buildLynxRecordView() {
        String url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
        Intent intent = new Intent(this, LynxRecorderActivity.class);
        intent.putExtra(LynxRecorderEnv.getInstance().mUriKey, url);
        startActivity(intent);
    }

}
```


**Kotlin**

```kotlin
import android.app.Activity
import android.content.Context
import android.content.Intent
import android.os.Bundle
import com.lynx.devtool.recorder.LynxRecorderActivity
import com.lynx.devtool.recorder.LynxRecorderEnv

class MainActivity :Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        buildLynxRecorderView()
    }

    private fun buildLynxRecordView() {
        val intent = Intent(this, LynxRecorderActivity::class.java)
        val url = "file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json"
        intent.putExtra(LynxRecorderEnv.getInstance().mUriKey, url)
        startActivity(intent)
    }

}
```

2. Register LynxRecorderActivity in the app manifest file.
```xml
// AndroidManifest.xml
<activity
    android:name="com.lynx.devtool.recorder.LynxRecorderActivity"
    android:exported="false" />
```
lynx\_devtool provides a highly encapsulated `LynxRecorderView` component that enables page replay by simply passing in the recorded artifact URL.
```tsx
import { LynxRecorderView } from '@lynx/lynx_devtool';

build() {
  Column() {
    LynxRecorderView({
      url: 'file://lynxrecorder?url=https://lynx.recorder.artifacts/LynxRecorder.json'
    })
  }.size({ width: '100%', height: '100%' })
}
```
## 


## Compatibility

**Compatibility Table**
**Query:** `devtool.recorder`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.5 | - |

**Description:** Lynx Recorder Support




---
url: /guide/devtool/handle-errors.md
---

# Handle Errors in Lynx

## Recognize Errors in Tools

When you are developing Lynx apps, you may encounter various types of errors that are designed to notify you the unexpected situations that have just happened.

For example, if the bundle file is broken, you'll see:

![Bundle is broken](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/error_invalid_bundle.png)
Also, sometimes when your JavaScript code contains an TypeError:

![Syntax error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/error_syntax.png)
Sometimes, a [native module](/guide/spec.md#nativemodules) is called with a wrong number of arguments:

![Wrong arguments](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/error_wrong_args.png)
With DevTool or LogBox, you shall easily recognize them.

## LogBox

You've already seen it above - the in-app tool that displays errors.

![LogBox notification](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/logbox_message.jpeg)![LogBox red](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/logbox_box.png)
It's convenient for a quick overview and lets you know what's happening.
However, for development purposes, we recommend using DevTool Desktop Application with more features and a better interactive experience.

## Handle Errors in Code

Now let's try to do something with the errors.

You may want to have an overall understanding of the [errors](/api/errors/lynx-error.md) first if you want to handle them in your code.

And then, here is an example of handling error [301](/api/errors/error-code.md#eb_resource_image-301) in code:

```tsx
const ImageErrorExample = () => {
  const [isImageError, setImageError] = useState(false);
  const handleImageError = (event: ErrorEvent) => {
    setImageError(true);
    console.log('Image loaded error:', JSON.stringify(event));
  };
  if (isImageError) {
    return <view />;
  }
  return (
    <view>
      <image
        className="my-image"
        src={'error url'}
        binderror={handleImageError}
      />
    </view>
  );
};
```

In order for developers to quickly categorize an error and figure out how to deal with it, we have summed up all of them and made a [list](/api/errors/error-code.md), including the error code, description, level, fix suggestion, etc.

Just help yourself!

## Compatibility

**Compatibility Table**
**Query:** `devtool.logbox`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.4 | - |

**Description:** Shows logbox details




---
url: /guide/performance/analysis-performance.md
---

# Performance Analysis

This section guides you through performance analysis methodologies, from diagnosing rendering latency and instrumenting business logic to optimizing page fluency and memory usage, enabling comprehensive smoothness and stability improvements.

## Rendering Latency Analysis

### Record Trace data

Use [Devtool](/guide/devtool/trace/record-trace.md) to record Trace data. The Trace is presented on a [timeline](/guide/performance/analysis-performance/trace-track.md), capturing the full Lynx rendering pipeline, which lays the foundation for subsequent analysis.

### Analyze rendering latency

On the [Rendering-time analysis](/guide/performance/analysis-performance/analysis-render-process.md) page, combine Trace data to review first-frame rendering and page update flows, pinpoint time-consuming stages and performance bottlenecks along the rendering path. The [NativeModule invocation](/guide/performance/analysis-performance/analysis-native-module.md) page explains the complete execution flow of NativeModule calls to help you analyze them efficiently.

### Add custom instrumentation

Trace allows developers to add [custom Trace instrumentation](/guide/performance/analysis-performance/trace-api.md). Insert Trace events into key business flows, component lifecycles, and asynchronous tasks to visualize them on the Trace UI timeline, enabling precise tracking and localization of potential bottlenecks.

## Memory Analysis

The [Memory analysis](/guide/performance/analysis-performance/analysis-memory.md) page describes how to use Trace and IDE tools to analyze memory peaks, growth trends, and abnormal leaks, helping developers discover and fix memory issues early to improve application stability.

## Fluency

The [Fluency analysis](/guide/performance/analysis-performance/analysis-fluency.md) page explains how to analyze dropped frames and jank, enabling developers to quickly locate and optimize page interaction performance.



---
url: /guide/performance/analysis-performance/analysis-render-process.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Render Time Analysis

This document aims to help developers master how to accurately locate each execution stage in a Trace, thereby enabling effective analysis of specific performance issues.

## Analyze render time with Trace

Frontend pages can [flag Pipeline](/guide/performance/monitor-performance/timing-flag.md) for key components. When the component finishes rendering on screen, the [Timing Track](/guide/performance/analysis-performance/trace-track.md) in Trace generates a bubble at the corresponding timestamp to mark the key stage.

A Lynx page generally has two render types: first-frame rendering and update rendering. Internally, the Lynx SDK produces [LoadBundleEntry](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) and [PipelineEntry](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) to describe stage durations in each process.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_overview.png)
Click a bubble to open a details panel showing the sub-stage timeline and the duration of each sub-stage in the render process.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_detail_panel.png)
The following sections detail both render types and their constituent stages, including the corresponding Trace event names, so you can locate and troubleshoot issues via Trace events.

## First-frame render time analysis

First-frame rendering primarily consists of LoadBundle and Paint:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_load_bundle.png)
### LoadBundle

This stage corresponds to `Timing::Mark.loadBundleStart` and `Timing::Mark.loadBundleEnd` in Trace. It mainly parses the bundle and performs the initial screen render. It can be broken down into six sub-stages:

#### Parse

This stage corresponds to `Timing::Mark.parseStart` and `Timing::Mark.parseEnd` in Trace. It parses the binary bundle into in-memory data structures. The bundle contains a header and multiple sections; the JS source section runs on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread), mapped to `Timing::Mark.loadBackgroundStart` and `Timing::Mark.loadBackgroundEnd` in Trace.

#### MTS Render

This stage corresponds to `Timing::Mark.mtsRenderStart` and `Timing::Mark.mtsRenderEnd` in Trace. It executes [Main Thread Script (MTS)](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree.

#### Resolve

This stage corresponds to `Timing::Mark.resolveStart` and `Timing::Mark.resolveEnd` in Trace. It traverses the element tree, computes a layout node tree from node attributes and styles, and generates [UI Paint OP](/guide/spec.md#platform-ui-paint-operations-or-ui-paint-op).

#### Layout

This stage corresponds to `Timing::Mark.layoutStart` and `Timing::Mark.layoutEnd` in Trace. It traverses the layout node tree produced during Resolve, computes node positions and sizes, and generates [UI Layout OP](/guide/spec.md#platform-ui-layout-operations-or-ui-layout-op).

#### Paint UI OP Execute

This stage corresponds to `Timing::Mark.paintingUiOperationExecuteStart` and `Timing::Mark.paintingUiOperationExecuteEnd` in Trace. It executes the UI Paint OP generated during Resolve.

#### Layout UI OP Execute

This stage corresponds to `Timing::Mark.layoutUiOperationExecuteStart` and `Timing::Mark.layoutUiOperationExecuteEnd` in Trace. It executes the UI Layout OP generated during Layout.

### Paint

The system drawing stage measures, lays out, and paints the platform UI tree. The end of painting maps to `Timing::Mark.paintEnd` in Trace.

## Update render time analysis

Update renders are primarily driven by the background thread to update and draw the UI tree. The main difference from first-frame rendering lies in [Framework Rendering](/guide/spec.md#framework-rendering). Using ReactLynx 3 as an example, we highlight the differing parts:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing_demo_trace_pipeline_entry.png)
### Diff Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.diffVdomStart` and `Timing::MarkFrameWorkTiming.diffVdomEnd` in Trace. It performs component diff on the background thread.

### Pack Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.packChangesStart` and `Timing::MarkFrameWorkTiming.packChangesEnd` in Trace. It serializes diff results and sends them to the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread).

### Parse Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.parseChangesStart` and `Timing::MarkFrameWorkTiming.parseChangesEnd` in Trace. It parses the serialized data on the main thread.

### Patch Changes

This stage corresponds to `Timing::MarkFrameWorkTiming.patchChangesStart` and `Timing::MarkFrameWorkTiming.patchChangesEnd` in Trace. It applies the diff results on the main thread and updates the Element Tree.

Subsequent render stages are similar to the first-frame process: Resolve, Layout, Paint UI OP Execute, Layout UI OP Execute, and Paint.

## Next Steps

[ReactLynx Render Pipeline

Understanding the ReactLynx Rendering Pipeline

](/guide/performance/analysis-performance/reactlynx-render-process)


---
url: /guide/performance/analysis-performance/analysis-fluency.md
---


.full_image {
  width: 750px;
  margin: 20px;
  }

# Fluency Analysis

When scrolling occurs, the system attempts to draw the next frame at a fixed cadence; any noticeably longer draw interval will be perceived by users as a “stutter” or “jitter.” These momentary long frames are the source of “dropped frames.” Scrolling is the most cadence-sensitive scenario, because backgrounds, text, and images are continuously moving; once the beat becomes unstable, the eye immediately notices.

## Offline Trace analysis

Offline Trace aims to reconstruct the frame timing of a scrolling interaction, tie “which segment dropped frames” to “why it dropped,” and produce actionable fixes. For Trace capture, see [Record Trace](/guide/devtool/trace/record-trace.md) and ensure the capture covers the full scrolling time window and realistic scroll speed.

### How Trace displays dropped frames

In the Trace webpage, frame render time labels were added at the start of `Choreographer#doFrame` (currently Android only). These labels display dropped-frame situations throughout the entire system render process. By observing these labels, you can visually identify render-time anomalies. Frame render time is computed by summing the time spent in `Choreographer#doFrame` on the UI thread and `DrawFrames` on the `RenderThread`. If the total is ≥ 32 ms, the label is red; if the total is ≥ 16 ms and \< 32 ms, the label is orange; if the total is \< 16 ms, the label is green. For offline analysis, treat frames marked red or orange as the tasks most likely causing dropped frames and analyze them preferentially.

![Frame Rendering Time](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/20250929-163554.jpeg)
### Locating dropped-frame segments during scrolling

- On the timeline, look for frames that clearly exceed the cadence (for example, consecutive red labels) and mark them as “long-frame segments.”
- Analyze frame by frame to confirm whether the cause is UI-thread congestion, delayed render submission, or resource loading/decoding inserted into the critical path.
- Associate long-frame segments with UI elements (large images, complex list items, card animations) to form actionable ties to what users see.

### Root-cause patterns and identification

- UI thread blocking: layout and measurement stacking, or I/O running on the UI thread.
- Heavy layout and drawing: deep hierarchies, frequent reflow, or large-area repaint; concentrated text and image size computation; complex `Canvas` drawing. Symptom: a single frame’s computation time is unusually long and repeats with scroll.
- Image and resource loading: decode, downsample, and texture upload blocking critical frames; async not truly isolated, or missing placeholders/preload. Manifestations: `GPU` or `RenderThread` queues back up, correlated with image size or count.

### Common investigation suggestions

- Reduce UI-thread workload: move non-essential computation and I/O off the UI thread; spread layout and drawing across frames to avoid “everything in a single frame.”
- Optimize layout depth and measurement: control hierarchy depth and constraints complexity; avoid repeated measurement; use compositing layers to reduce unnecessary repaint.
- Image and resource governance: constrain dimensions and size, use placeholders and preload; move decode and texture upload earlier or run in parallel; load on demand and reuse caches.
- JS and bridge: split long tasks and reduce synchronous calls; use throttling and batching to avoid high-frequency messages overwhelming the UI cadence.



---
url: /guide/performance/analysis-performance/analysis-memory.md
---

  .full_image {
  width: 750px;
  margin: 20px;
}
# Memory Usage Analysis

Memory analysis helps discover leaks and abnormal usage within Lynx pages and ensures stability. You can use Trace Memory Track and IDE tools, to comprehensively monitor and troubleshoot memory-related performance issues.

## Deep analysis with Trace

Starting from 3.4, Trace supports Memory Track, which shows Lynx page memory usage trends over time. Each Memory Track represents one Lynx page’s memory changes.

![Memory Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-latest.png)
Click the Memory Track curve to see the page’s total memory usage and the memory used by Element, background scripting engine, main-thread scripting engine, images, etc.

![Memory Track Detail](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-details.png)
## Analyze memory with IDEs

This section briefly introduces how to use Android Studio or Xcode’s built-in tools to debug apps and view performance metrics.

iOSAndroidThis section introduces how to analyze memory using Xcode.
### Analyze (static check)
Choose Product > Analyze or press Shift + Command + B to run automatically. Analyze uses syntax and memory context to find potential issues. It mainly detects four categories:
1. Logic errors: dereferencing null pointers, uninitialized variables.
2. Memory management errors: e.g., memory leaks.
3. Declaration errors: variables never used.
4. API call errors: missing libraries or frameworks.
:::tip
📌 Analyzer makes compiler-driven judgments and is not always accurate. If you see a report, review surrounding code; some cycle references that cause memory leaks cannot be identified by Analyzer. Analyzer makes compiler-driven judgments and is not always accurate. If you see a report, review surrounding code; some cycle references that cause memory leaks cannot be identified by Analyzer.
:::
### Leaks (dynamic check)
Xcode > Open Developer Tool > Instruments > Leaks
![Leaks dynamic check](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-12.png)Choose Leaks, then specify the device and app to debug. In this example, an iPhone SE2 (iOS 14.5) simulator debugs the LynxExample app. Click the start button to check for memory leaks.
![Leaks Start Button](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-13.png)After starting, operate in the simulator or on device. If the Leaks window shows issues, jump to the corresponding code to debug. You can pause to inspect memory info shown in the chart. After debugging, you can save the results locally.
![Leaks Analysis Result](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-14.png)If a memory leak appears (example below), set the chart to Call Tree mode, then enable Invert Call Tree at the bottom of the window. Select any leak to jump to source code.
![Leaks Call Tree Mode](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-15.png)### Allocations (detailed allocation)
Xcode > Open Developer Tool > Instruments > Allocations
![Allocations Tool](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-17.png)Similar to Leaks but focuses on detailed memory allocations. The lower list shows per-method memory usage. Check a graph to show a bar chart above. Click an item to view stack trace details; click the right-hand Stack Trace pane to jump into code and inspect allocations.
![Allocations Stack Info](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-18.png)The code section is highlighted and the allocation ratio is shown.
![Allocations](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-19.png)###
This section introduces how to analyze memory using Android Studio.
### Profiler basics
![Profiler Tool](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-1.png)First click the highlighted area in the toolbar; Android Studio performs a Build and then opens the Profiler window. From there you can run tests—click the ‘+’ icon to select a device connected via adb and the process to test.
![Profiler Choose Process](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-2.png)Using a Xiaomi MIX (API 24), we run a \~45 s test and manually trigger a GC at 15 s. From left to right, the icons are GC, Capture Heap Dump, and manual Record (an option for devices below API 26 for memory analysis).
![Profiler Tool Record](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-3.png)Over 45 s, the device’s memory changes are as follows:
![Profiler Tool Record](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-4.png)In this example, after the manual GC, the app’s memory usage drops noticeably for a period.
Heap dumps show which objects are using memory at the time of capture. Especially after long user sessions, heap dumps reveal objects that should no longer be in memory, helping identify leaks. After clicking the Heap Dump icon, Java memory may temporarily increase because dumping runs in the same process and needs memory to collect data.
![Profiler Memory Status](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-5.png)After capturing the heap dump, use the built-in analyzer. The table shows:
- Allocations: number of allocations in the heap.
- Native Size: total native memory used by this object type (Bytes). Visible on Android 7.0+ only. Some Java-allocated framework classNames (e.g., Bitmap) consume native memory.
- Shallow Size: total Java memory used by this object type (Bytes).
- Retained Size: total memory retained by all instances of this className (Bytes).
![Profiler Memory Detail](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-6.png)Click a className in the chart to open the Instance List window, then jump to source for inspection.
![Profiler Source Info](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-7.png)Or use the Reference window for more detailed checks and jump elsewhere for inspection.
![Profiler Source Transfer](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-8.png)After capturing a heap dump, you can also export hprof data from the SESSIONS window via Export Heap Dump. Use other tools (such as MAT) to further analyze the heap.
![Profiler Memory Dump](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-9.png)### Memory profiler
On devices below API 26, you need to manually record a time window before running memory performance analysis. Use the filter options (red circle) such as Arrange by className. In the table, select a className to jump to the Instance View, then to Allocation Call Stack to view stack traces and jump to source.
![Memory profiler](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-10.png)### Symptoms of memory leaks
- Many Full GCs during runtime.
- During a specific thread’s execution, manual GC has little effect.
- Many allocations and frees in a short time (memory graph jitter).
![Memory profiler](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-11.png)### Example leak and related analysis
```java
final className LoadedInChildClassLoader {

  static final byte[] moreBytesToLeak = new byte[1024 * 1024 * 100];

  private static final ThreadLocal<LoadedInChildClassLoader> threadLocal
          = new ThreadLocal<>();

  public LoadedInChildClassLoader() {
    threadLocal.set(this);
  }
}
```
#### Methods to trigger potential leaks
Apply pressure to app code and try to force leaks while cross-checking with the memory profiler. One way to induce leaks is to let the app run for some time, then inspect the heap; leaks may accumulate near the top of allocation. The smaller the leak, the longer the app needs to run to reveal it.
- Rotate the device repeatedly to trigger potential leaks.
- Switch between the debug app and other apps across different Activity states (e.g., go Home then return).
#### Possible causes of leaks
- Long-running threads.
- A thread loads a className via the ClassLoader.
- A className allocates large memory.
- A thread clears references to all custom classNames and the ClassLoader that loaded them.

## Performance testing with PerfDog

PerfDog is a third-party tool for checking Android and iOS app performance and is easy to use. After connecting a device and choosing the app to debug, click the red circled plus button at the bottom right to add performance parameters before starting.

![PerfDog Tool](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-20.png)
After the test, you can save data as a table and view performance parameters such as Jank count. Use the tool’s metrics as simple references to check app performance.

![PerfDog Save Data](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ide-perf-21.png)


---
url: /guide/performance/analysis-performance/analysis-native-module.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# NativeModule Invocation

NativeModule is the core communication bridge between JavaScript and native applications. By invoking a NativeModule, Lynx frontend pages can access and control native capabilities. This document together with code examples, details the invocation and execution flow of NativeModule within Trace.

## Deep analysis with Trace

Since Lynx 3.2, the Trace page includes a NativeModule Track that aggregates all NativeModule invocations. Each item’s length reflects the overall duration from request initiation to completion.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-track.png)
Basic display: click an item in the NativeModule Track to view a color-coded breakdown of rough durations for each stage of the invocation.

Details panel: shows the method name, input parameters, and precise per-stage durations (including parameter conversion, platform logic, thread switches, and other key nodes).

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-timing-stage.png)
## Breakdown of NativeModule invocation details

Below we use a frontend NativeModule call as an example to describe execution timing in Trace.

### Example code

```ts {4,5,6,7,10}
NativeModules.bridge.call(
  'setStorage',
  {
    data: {
      key: 'lynx_nativemodule_test',
      value: i,
    },
  },
  (res) => {
    console.log('setStorage res is: ', res);
  },
);
```

### Trace execution analysis

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-normal.jpeg)
A NativeModule call can be divided into five main stages:

#### 1. Parameter conversion

This stage corresponds to `JSValueToPubValue` in Trace, where JS data (lines 4–7 in the code sample) is converted into native types.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-1.png)
#### 2. Platform-layer implementation

This stage corresponds to the time period in the Trace from the start of `CallPlatformImplementation` to `NativeModule::PlatformCallbackStart`, where the native method executes the specific functionality and returns platform-layer data.

Among them, the `CallPlatformImplemention` occurs on the [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread), while the logic between the `CallPlatformImplementation` event and `NativeModule::PlatformCallbackStart` usually runs on other threads.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-2.png)
#### 3. Waiting for the background thread to execute the callback

This stage corresponds to `NativeModule::PlatformCallbackStart` and `NativeModule::Callback` in Trace.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-3.jpeg)
#### 4. Result conversion

This stage corresponds to `PubValueToJSValue` in Trace, where platform-layer return data is converted into JS arguments.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-4.png)
#### 5. Callback execution

This stage corresponds to `InvokeCallback` in Trace, which executes JS code logic (line 10 in the sample).

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-stage-5.png)
## Special NativeModule calls

Currently, JSB SDKs in the company return results via callbacks. Some NativeModule implementations return results directly to the Lynx SDK via callbacks on the background thread. Callback execution is not necessarily limited to the main thread—any thread may invoke and execute callback-related logic.

### Example code

```js {4,5,6,9}
NativeModules.bridge.call(
  'x.reportAppLog',
  {
    data: {
      eventName: 'lynx_nativemodule_test_event_name',
    },
  },
  (res) => {
    console.log('reportAppLog res is: ' + JSON.stringify(res));
  },
);
```

### Trace execution analysis

These special NativeModule calls can be divided into five main stages.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special.jpeg)
#### 1. Parameter conversion

This stage corresponds to `JSValueToPubValue` in Trace, where JS data (lines 4–6 in the sample) is converted into native types.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-1.jpeg)
#### 2. Platform-layer implementation

This stage corresponds to the time period in the Trace from `CallPlatformImplementation` to the start of `NativeModule::Callback`, where the native method executes the specific functionality and returns platform-layer data.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-2.jpeg)
#### 3. Result conversion

This stage corresponds to `PubValueToJSValue` in Trace, where platform-layer return data is converted into JS arguments.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-3.jpeg)
#### 4. Callback execution

This stage corresponds to `InvokeCallback` in Trace, which executes JS code logic (line 9 in the sample).

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-4.jpeg)
#### 5. Cleanup

This stage corresponds to the time period in the Trace from the end of `InvokeCallback` to the end of `NativeModule::Invoke`, where platform-layer cleanup is performed and external registrants are notified that the NativeModule call has completed.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-special-stage-5.jpeg)


---
url: /guide/performance/monitor-performance.md
---

# Performance Monitoring Overview

This overview helps you quickly build a mental model and understand common workflows for performance monitoring. It explains how the [Performance API](/guide/performance/monitor-performance/performance-api.md) and [Timing Flag](/guide/performance/monitor-performance/timing-flag.md) work together to create a closed loop from marking to analysis: `Mark` → `Collect` → `Report` → `Analyze`.

## Mental Model and Closed-Loop Workflow

The goal of monitoring is to ensure that critical moments in your page's lifecycle can be accurately recorded, reported, and analyzed, allowing you to quickly trace issues back to the source code or specific UI locations. Centered around the Lynx rendering pipeline and standardized events, we recommend the following closed-loop workflow:

- **Mark**: Use a Timing Flag (`__lynx_timing_flag`) on critical UI nodes or key data updates to define the rendering pipelines you need to monitor. The special flag `__lynx_timing_actual_fmp` can additionally generate the ActualFMP metric. For details, see [Marking Rendering Pipelines](/guide/performance/monitor-performance/timing-flag.md).
- **Collect**: Register a `PerformanceObserver` as early as possible on the front end (e.g., to listen for `metric.fcp`, `pipeline`, etc.), or consume events via asynchronous callbacks on the client side. For details, see [Collecting Performance Events](/guide/performance/monitor-performance/performance-api.md).
- **Report**: Report key metrics and events to your data platform using consistent naming and fields.
- **Analyze**: Analyze production data, using `PipelineEntry.identifier` (the Timing Flag) and event timelines to trace problems back to the corresponding modules or data flows for debugging and review.

Recommended minimum set of tracking points (for a basic production setup):

- **metric**: `fcp` (required), `actual_fmp` (when you need to measure the "first meaningful data paint")
- **pipeline**: `loadBundle` (for the initial screen rendering), and the pipelines associated with your critical Timing Flags.

## Feature Positioning

### [Performance API](/guide/performance/monitor-performance/performance-api.md)

- **Positioning**: A standardized performance interface covering four event types: `init`, `metric`, `pipeline`, and `resource`.
- **Triggering and Retrieval**: `PerformanceEntry` objects are generated by the Lynx Engine. The front end subscribes to them via `PerformanceObserver.observe([...])`, and the client receives them through the `onPerformanceEvent(entry)` callback on an asynchronous thread.
- **Typical Uses**:
  - Obtaining standard metrics for initial screen rendering and key updates (FCP, ActualFMP).
  - Combining multiple events to build custom business metrics (e.g., the waiting time from the end of the initial screen rendering to the first important data update).

### [Marking Lynx Pipeline](/guide/performance/monitor-performance/timing-flag.md)

- **Positioning**: A unique identifier used to mark a rendering pipeline for monitoring. It triggers the generation of a `PipelineEntry` and can also trigger a `MetricActualFmpEntry`.
- **Usage**:
  - The recommended method is to set the `__lynx_timing_flag` attribute on a UI element.
  - Setting the value to `__lynx_timing_actual_fmp` additionally generates an ActualFMP metric event.
- **Behavior and Limitations**:
  - The same Timing Flag is only effective the first time it is encountered (repeated markings will not trigger the callback again).
  - It is ineffective on tags that do not have a UI node, such as `<inline text/>`, `<block/>`, and `<template/>`.

## Common Workflows

- **Mark critical stages** → Get key moments via `PipelineEntry`/`ActualFMP` → Combine with `LoadBundleEntry`/`FCP` to establish a baseline for initial rendering and updates → **Report** → Filter high-latency samples by different dimensions → Trace back to the component/data flow corresponding to the mark to identify the cause.
- **Lazy-loaded component performance** → Set a Timing Flag on important nodes and listen for the corresponding `PipelineEntry` → Combine with the page's `loadBundle` event to create an end-to-end performance profile → Optimize the resource loading and layout stages separately.



---
url: /guide/performance/monitor-performance/performance-api.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Performance API

## Concepts and usage

Measuring and analyzing performance metrics is critical to ensure the speed and user experience of Lynx applications. Similar to the [Web standard](https://developer.mozilla.org/en-US/docs/Web/API/Performance), Lynx provides the **Performance API** as a standardized interface to measure Lynx app performance, helping developers monitor comprehensive metrics from initialization through rendering completion.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-api-v4.png)
### Performance entry types

The core of the Performance API is the **[`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md)** object, which is the fundamental data structure describing a performance event. Each PerformanceEntry has the following basic properties:

- `entryType`: The type of performance event (e.g., `init`, `metric`, `pipeline`, `resource`)
- `name`: The specific name of the performance event
- Other type-specific properties and timestamps

Based on the `entryType` property, the Performance API supports four main categories of performance events:

- **Initialization events (`init`)**
  - [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md): Container initialization performance event
  - [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md): LynxView initialization performance event
  - [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md): Background runtime initialization performance event

- **Metric events (`metric`)**
  - [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md): FCP (First Contentful Paint)
  - [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md): ActualFMP (Actual First Meaningful Paint)

- **Rendering pipeline events (`pipeline`)**
  - [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md): Performance event for [flagged rendering pipelines](/guide/performance/monitor-performance/timing-flag.md)
  - [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md): Performance event for [TemplateBundle](/api/lynx-native-api/template-bundle.md) loading and first-screen rendering
  - [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md): Performance event for reloading [TemplateBundle](/api/lynx-native-api/template-bundle.md)

- **Resource loading events (`resource`)**
  - [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md): Performance event for lazy-loaded [TemplateBundle](/api/lynx-native-api/template-bundle.md)

### Getting performance data

#### Front-end developers

To consume performance events, the Performance API provides **PerformanceObserver**, which notifies you when the **Lynx Engine** produces performance events (`PerformanceEntry`).

The PerformanceObserver object offers the `observe` method to start observing and the `disconnect` method to stop. With them, you can observe by `entryType` (all entries of a type) or `entryType.name` (a specific kind of entry).

To prevent missing events due to late registration, register observations as early as possible.

- **Component dependencies**
  - `@lynx-js/react` >= 0.107.0

- **Registration timing**
  - Class components: register in the **constructor**
  - Function components: register in **useMemo**

The following example shows how to create a `PerformanceObserver` and observe [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) events.

**This is an example below: performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fsp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fsp") {
        entryType = "MetricFspEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fsp" and "pipeline" event.
    observer.observe(["metric.fsp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



#### Client developers

On the client side, performance events sent by the Performance API are delivered via the `onPerformanceEvent(PerformanceEntry entry)` callback on LynxViewClient on an **asynchronous thread**. It is therefore not recommended to perform any UI-related operations inside this callback.

iOSAndroidHarmonyOS```java
import com.lynx.tasm.LynxViewClientV2;
import com.lynx.tasm.performance.performanceobserver.PerformanceEntry;
import com.lynx.tasm.performance.performanceobserver.MetricFcpEntry;

public class CustomLynxViewClient extends LynxViewClientV2 {
  @Override
  public void onPerformanceEvent(@NonNull PerformanceEntry entry) {
    // If you need to consume raw data directly, convert to HashMap
    Log.d(entry.toHashMap());
    // If you need to consume a specific type, cast and use inner fields
    if (entry.entryType.equals("metric") && entry.name.equals("fcp")) {
      MetricFcpEntry fcpEntry = (MetricFcpEntry) entry;
      Log.d("lynxFcp is %s", fcpEntry.lynxFcp.duration);
    }
  }
}
```
```objc
#import "LynxViewClient.h"
#import "LynxMetricFcpEntry.h"

@interface CustomLynxViewClient : NSObject <LynxViewLifecycleV2>
@end
@implementation

- (void)onPerformanceEvent:(LynxPerformanceEntry*)entry {
  // If you need to consume raw data directly, convert to NSDictionary*
  NSLog(entry.toDictionary);
  // If you need to consume a specific type, cast and use inner fields
  if ([entry.entryType isEqual: @"metric"] && [entry.name isEqual: @"fcp"]) {
    MetricFcpEntry* fcpEntry = (LynxMetricFcpEntry *) entry;
    NSLog(@"lynxFcp is %@", fcpEntry.lynxFcp.duration);
  }
}
@end

```
```typescript
import { LynxViewClient, PerformanceEntry, MetricFcpEntry } from '@lynx/lynx';

export class CustomLynxViewClient extends LynxViewClient {
  public onPerformanceEvent(entry: PerformanceEntry): void {
    // If you need to consume raw data directly, convert to Record
    Log.d(entry.Record);
    // If you need to consume a specific type, cast and use inner fields
    if (entry.entryType == 'metric' && entry.name == 'fcp') {
      let fcpEntry: MetricFcpEntry = entry as MetricFcpEntry;
      Log.d('lynxFcp is %s', fcpEntry.lynxFcp.duration);
    }
  }
}
```

## [Capture specific rendering pipelines](/guide/performance/monitor-performance/timing-flag.md)

A [rendering pipeline](/guide/spec.md#lynx-pipeline) is the complete process from triggering the rendering to displaying it on the screen. If you care about the rendering performance of certain key components, set the component’s `__lynx_timing_flag` property to mark the pipeline it belongs to and monitor its performance.

When the flagged rendering pipeline completes and the screen is refreshed, a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) event is generated. You can retrieve it via [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md).

## Build custom performance metrics

Different business goals imply different metrics to focus on. Your use of the Performance API need not be limited to built-in Lynx metrics—you can flexibly combine timestamps from different `PerformanceEntry`s at key points to construct a metric suite tailored to your application.

For example, if you want to measure the latency from the end of first-screen rendering to the first important data update, you can combine `LoadBundleEntry` and `PipelineEntry` to compute a custom metric `waitingDuration` as shown below. It helps monitor the speed of network requests, file IO, etc., and pinpoint causes of performance regressions.

![waiting duration](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/custom-metric-waitingduration.png)

**This is an example below: performance-api**

**Entry:** `src/simple-observe`
**Bundle:** `dist/actual-fmp-entry.lynx.bundle`

```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useEffect, useMemo, useRef, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry, PerformanceObserver, PipelineEntry } from "@lynx-js/types";
import "../common/common.css";

export default function CreateCustomPerformanceMetricExample(this: any) {
  const [loadBundleEnd, setLoadBundleEnd] = useState<number>(0);
  const [pipelineStart, setPipelineStart] = useState<number>(0);
  const [waitingDuration, setWaitingDuration] = useState<number>(0);
  const [state, setState] = useState({
    importantElement: "Loading",
    __lynx_timing_flag: "",
  });

  const loadBundleEndRef = useRef(0);
  const observerRef = useRef<PerformanceObserver>();

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "pipeline" && entry.name == "loadBundle") {
        // 3. Received "pipeline.loadBundle" event.
        const LoadBundleEntry = entry as LoadBundleEntry;
        setLoadBundleEnd(LoadBundleEntry.loadBundleEnd);
      } else if (entry.entryType == "pipeline") {
        // 4. calculate waitingDuration
        const pipelineEntry = entry as PipelineEntry;
        if (pipelineEntry.identifier == "important-update") {
          setPipelineStart(pipelineEntry.pipelineStart);
          setWaitingDuration(pipelineEntry.pipelineStart - loadBundleEndRef.current);
          observer.disconnect();
        }
      }
    });
    // 2. register to listen to the "pipeline" event.
    observer.observe(["init", "pipeline"]);
    observerRef.current = observer;
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  useEffect(() => {
    loadBundleEndRef.current = loadBundleEnd;
  }, [loadBundleEnd]);

  useEffect(() => {
    const timeout = setTimeout(() => {
      setState(() => ({
        __lynx_timing_flag: "important-update",
        importantElement: "Display",
      }));
    }, 3000);

    return () => {
      clearTimeout(timeout);
    };
  });

  return (
    <view className="container">
      <text className="title">Create Your Performance Metric</text>
      <view className="card">
        <text className="entry highlight" __lynx_timing_flag={state.__lynx_timing_flag}>
          🎯 {state.importantElement} important element
        </text>
        <text className="entry">⏱️ loadBundleEnd: {loadBundleEnd} ms</text>
        <text className="entry">⏱️ updateTime: {pipelineStart} ms</text>
        <text className="entry">⏳ waitingDuration: updateTime - loadBundleEnd = {waitingDuration} ms</text>
      </view>
    </view>
  );
}

root.render(<CreateCustomPerformanceMetricExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Best practices

### 1. Register observers early

To avoid missing events due to late registration, register observations as early as possible:

- Register in the class component `constructor`, or in `useMemo` for function components

### 2. Choose an appropriate observe scope

Select the observe scope based on your needs:

```typescript
// Observe all metric events
observer.observe(['metric']);

// Observe only FCP metric events
observer.observe(['metric.fcp']);

// Observe multiple specific events
observer.observe(['metric.fcp', 'pipeline.loadBundle']);
```

### 3. Clean up promptly

When a component unmounts or observation is no longer needed, call `disconnect()` to release resources:

```typescript
useEffect(() => {
  return () => {
    if (observer) {
      observer.disconnect();
    }
  };
}, []);
```

## FAQ

### Q1: If my page uses [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), do I still need to mark a Timing Flag?

For pages with [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), you generally do not need to manually mark a Timing Flag. However, if you do, you will still receive a `LoadBundleEntry` with an `identifier` value equal to the TimingFlag you marked.

### Q2: My page uses [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md). How can I get the ActualFMP performance metric?

In scenarios with [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md), you generally do not need to focus on the ActualFMP performance metric; you only need to pay attention to the FCP metric. The FCP metric can be obtained directly through `MetricFcpEntry`.

### Q3: Can I get the rendering time of lazy-loaded components?

Yes. Marking Timing Flags on lazy-loaded components works the same as on the main page; you can use the Timing Flag inside the lazy-loaded component:

```typescript
export default function MyLazyBundle() {
  return (
    <view className="root">
      <text className="text", __lynx_timing_flag="dynamic_render" >Hello, This is a Lazy Bundle!</text>
    </view>
  );
}
```

```typescript
export default function app() {
  return (
    <view className="container">
      <text className="title">Hello LazyBundleEntry~</text>
      <Suspense fallback={<text className="sub-text">Loading...</text>}>
        <MyLazyBundle />
      </Suspense>
      <ScrollItem title={entryName} value={lazyBundleEntry} />
    </view>
  );
}
```

This method can be used to obtain the timestamp of the dynamic component rendering phase. For information about the time consumption of the dynamic component resource loading phase, refer to [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md).

### Q4: Are Performance API callbacks related to other Lynx lifecycles?

Performance API triggers its callbacks after all rendering pipeline timestamps are captured—i.e., after pixels are on screen—and has no strict ordering relationship with other Lynx lifecycles.

### Q5: Which is triggered faster, a setState callback or a Performance API callback?

See Q4: there is no defined ordering.

### Q6: Can Timing Flags be reused?

No. If two identical Timing Flags are injected, Performance API fires on the first one it detects and will not fire again for the second.

### Q7: What happens if the client calls ReloadTemplate, calls LoadTemplate multiple times, or the front end calls reload?

**Before Lynx 3.4**: Performance API state resets; LoadBundleEntry will be triggered again with timestamps from this template load. If front-end reloads but the page has no UI to redraw, no callback is received.

**After Lynx 3.4**: Multiple LoadTemplate calls yield multiple LoadBundleEntry events; client ReloadTemplate and front-end reload yield ReloadBundleEntry.

### Q8: Why don’t I receive the LoadBundleEntry callback?

Possible causes:

1. First-screen rendering produced no pixels, e.g., LynxView width/height is 0, LynxView is off-screen, or LynxView wasn’t added to the window.
2. The observer was registered too late; try registering earlier:
   - register in the class constructor or `useMemo`

### Q9: I used an Timing Flag—why don’t I receive PipelineEntry callbacks?

Possible causes:

1. Observer registered too late (see Q8)
2. Timing Flag is set on a Component while the `removeComponentElement` switch is enabled, making the Timing layer unable to detect the flag
3. Timing Flag is ineffective on tags with no UI nodes, such as `<inline text/>`, `<block/>`, `<template/>`
4. The same Timing Flag does not trigger multiple callbacks (see Q6)

### Q10: How do I verify that Timing Flag integration works?

You can validate via local Trace, or by registering an observer and checking whether callbacks fire.

### Q11: My ActualFMP metric is particularly large—why?

Check whether preloading is in effect; with preloading, the starting point of ActualFMP can be very early.

### Q12: Error “OnPipelineStart arg count must == 1”

To fix this, upgrade `@lynx-js/react` to version 0.107.1 or higher.



---
url: /guide/performance/monitor-performance/timing-flag.md
---

# Mark Rendering Pipelines

[Lynx Pipeline](/guide/spec.md#lynx-pipeline) defines the complete process from triggering the rendering to displaying it on the screen. If you care about rendering performance of certain key components, you can set the component’s `__lynx_timing_flag` property to mark its Lynx Pipeline and monitor its performance.

When the flagged Lynx Pipeline finishes and the screen is refreshed, a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) performance event is generated. You can obtain it via [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md).

## Usage rules

- The `__lynx_timing_flag` attribute must be a non-empty string. Empty values or invalid types will not trigger [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md) callbacks.
- When the `__lynx_timing_flag` attribute value is `__lynx_timing_actual_fmp`, an additional [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md) performance event is generated.

## Examples

1. Mark a node: set the `__lynx_timing_flag` attribute on the target component. When the node finishes rendering, the framework automatically collects performance data for its Lynx Pipeline.
2. Get data: register an observer (`PerformanceObserver`) via [`lynx.performance.createObserver()`](/api/lynx-api/lynx/lynx-performance.md#createobserver) to receive the corresponding performance data (`PipelineEntry`).

**This is an example below: performance-api**

**Entry:** `src/pipeline-entry`
**Bundle:** `dist/pipeline-entry.lynx.bundle`

```tsx {11-21,34}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [myName, setMyName] = useState<string | undefined>(undefined);

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("PipelineEntry");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Notes

### 1. Multiple components set the same `__lynx_timing_flag` attribute

```ts
export default function App() {
  const [showImage, setShowImage] = useState(false);

  useEffect(() => {
    setTimeout(() => {
      setShowImage(true);
    }, 3000);
  }, []);

  return (
    <view className="container">
      <text __lynx_timing_flag="__lynx_timing_actual_fmp">Hello World</text>
      {showImage && <image __lynx_timing_flag="__lynx_timing_actual_fmp" src="xxxx.png" />}
    </view>
  );
}
```

In this case, only the Lynx Pipeline data of the first component that appears on screen will be recorded:

1. Compute `ActualFMP` once and send one [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).
2. Send one [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you want to record the moment when both components finish rendering, use different `__lynx_timing_flag` values.

### 2. The same component renders multiple times

```ts
export default function App(this: any) {
  return (
    <view className="container">
      {
         // needShow: true -> false -> true
         data.needShow ? <text __lynx_timing_flag="__lynx_timing_actual_fmp">{data.msg}</text> : null
      }
    </view>
  );
}
```

In this scenario, only the Lynx Pipeline data for the component’s first appearance is recorded:

1. Compute `ActualFMP` once and send one [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).
2. Send one [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

If you need to measure each render individually, implement as follows:

```ts
let isFirst = true;
export default function App(this: any) {
  return (
    <view className="container">
      {
         // needShow: true -> false -> true
         data.needShow ? <text __lynx_timing_flag={"__lynx_timing_actual_fmp" + (isFirst ? "" : +data.id)}>{data.msg}</text> : null
      }
    </view>
  );
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.timing-flag`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /guide/compatibility.md
---

# Compatibility

This article explains how to ensure version compatibility between [Bundle] and [Lynx Engine], and how to handle challenges that come with Lynx Engine version evolution.

## Build from Source

A simple way to ensure compatibility is to **always build the Bundle with the Host application from source**.

- Bundle can fully utilize all features of the current Lynx Engine version
- Compatibility can be fully verified during development, what you see is what you get

## Multi-version Compatibility

However, in a complex project, the relationship between Bundle and Lynx Engine is not one-to-one:

- A Bundle might run in applications with different Lynx Engine versions

- An application can run multiple Bundles maintained by different teams

In this case, you need to set the [`engineVersion`] to ensure compatibility.

:::info Engine Version
When the Bundle's [`engineVersion`] is greater than the Lynx Engine version, it will not be able to run.
:::

For example: a Bundle with [`engineVersion`] 3.3 can run on Lynx Engine 3.3 and later versions, but cannot run on 3.2.

**Version Compatibility Diagram** 

graph TB
  subgraph Bundle["🎯 Bundle"]
      B10["Engine Version 3.3"]
  end
  subgraph Engine["⚙️ Lynx Engine"]
      E12["Version 3.5"]
      E11["Version 3.4"]
      E10["Version 3.3"]
      E09["Version 3.2"]
  end
  B10 -.->|❌ Not Supported| E09
  B10 ==>|✅ Can Run| E10
  B10 ==>|✅ Can Run| E11
  B10 ==>|✅ Can Run| E12
  %% Node styles
  style E12 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
  style E11 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
  style E10 fill:#2b5a83,stroke:#4a90e2,stroke-width:3px,rx:10px
  style E09 fill:#2b5a83,stroke:#4a90e2,stroke-width:2px,rx:10px,stroke-dasharray:5,5
  style B10 fill:#2d5a1e,stroke:#7ed321,stroke-width:3px,rx:10px
  %% Subgraph styles
  style Bundle fill:transparent,stroke:#7ed321,stroke-width:2px,rx:10px
  style Engine fill:transparent,stroke:#4a90e2,stroke-width:2px,rx:10px
  %% Default styles
  classDef default fill:#23272f,color:#ccc,font-family:system-ui
  %% Connection line label styles
  linkStyle default stroke-width:2px

When a Bundle needs to run on multiple Lynx Engine versions, its [`engineVersion`] must be lower than all Lynx Engine versions.

When running multiple Bundles on a single Lynx Engine version, each Bundle can set different [`engineVersion`]s, but none can be greater than the Lynx Engine version.

### Version Incompatibility Handling

If you try to run a Bundle on a lower version of the Lynx Engine, a Fatal level error with code [10204](/api/errors/error-code.md#subcode-10204) will occur, and the rendering process will stop. This mechanism prevents potential runtime issues caused by version incompatibility.

### Configuring Engine Version

The [`engineVersion`] is a string containing two version numbers, and you can specify it in your configuration file:

```js title="lynx.config.js"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReactLynx({
      engineVersion: '3.2',
    }),
  ],
});
```

## Upgrading Lynx Engine

As Lynx Engine evolves, new features are added and some features may be deprecated. Their compatibility is also managed by [`engineVersion`].

### New Features

Some new features **_will not_** affect existing Bundles, but if [`engineVersion`] is lower than the version where they were introduced, runtime detection is needed, for example:

```js
// Detect if `lynx.newlyAddedMethod` can be called
if (lynx.newlyAddedMethod) {
  lynx.newlyAddedMethod();
}
```

While some new features cannot run on lower versions of the Lynx Engine at all, so they will only be enabled when [`engineVersion`] is greater than or equal to the corresponding version.

### Deprecated Features

Some features may be deprecated during iteration, and their behavior may change when a higher [`engineVersion`] is set.

- If only the Lynx Engine version is upgraded without upgrading the Bundle's [`engineVersion`], there will be no compatibility issues
- If both Lynx Engine and Bundle's [`engineVersion`] are upgraded, you need to read the CHANGELOG to ensure there are no unexpected behavior changes

## API Compatibility

Lynx provides comprehensive compatibility information for each API, built-in component, and CSS property. We offer two paired components to help you understand platform support:

### APISummary

The `<APISummary />` component provides a quick, high-level overview of an API's availability across platforms. It shows a summary status (e.g., "Widely available") and badges for supported platforms. Clicking on this summary card will automatically jump to the detailed compatibility table.

### APITable

The `<APITable />` component displays detailed, version-specific support information for each platform. It breaks down support by OS (Android, iOS) and Web, including specific version numbers where applicable.

### Interactive Explorer

Use the interactive explorer below to search and discover compatibility information using both components:

- **CSS Properties**: Enter paths like `css/properties/gap`
- **Built-in Elements**: Enter paths like `elements/view` to see element compatibility
- **Nested APIs**: Use dot notation to access nested identifiers, e.g., `css/properties/align-self.supported_in_flex_layout`

API Compatibility ExplorerSearch for any Lynx API to view its compatibility across platformsQuick access:CSS`gap`Element`view`CSS`align-self`Nested`align-self → flex layout`Embed this table in your MDX:
```jsx
import { APISummary, APITable } from '@lynx';

<APISummary query="css/properties/gap" />
<APITable query="css/properties/gap" />
```
APISummary**Compatibility Table**
**Query:** `css.properties.gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |


[Bundle]: /guide/spec.md#app-bundle-aka-template-bundle

[Lynx Engine]: /guide/spec.md#engine

[`engineVersion`]: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md



---
url: /guide/scripting-runtime/index.md
---

# JavaScript Runtime and WebAssembly

## JavaScript Runtime

One of biggest features of Lynx is [Dual-Thread Architecture](/guide/spec.md#scripting-facing-threading-abstraction)(read [Thinking in ReactLynx](/react/thinking-in-reactlynx.md) for more information), JavaScript code runs on two threads: the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) and the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). The two threads use different JavaScript engines as their runtime.

### [Main Thread](/guide/spec.md#main-thread-or-lynx-main-thread)

The Lynx main thread is responsible for handling tasks that directly affect the screen [pixel-pipeline](/guide/spec.md#enginepixeling-the-pixel-pipeline), including executing [main thread scripts](/react/main-thread-script.md), handling layout, and rendering graphics.

The main thread uses [PrimJS](/guide/scripting-runtime/main-thread-runtime.md#primjs), maintained by the Lynx team, as its runtime. PrimJS is a lightweight, high-performance JavaScript engine based on QuickJS, providing excellent runtime performance for the main thread.

### [Background Thread](/guide/spec.md#background-thread-aka-off-main-thread)

As opposed to the main thread, Lynx's background threads handle tasks that do not directly affect the display of screen pixels. This includes scripts and tasks that run in the background, separate from the main thread. This allows the main thread to focus on handling user interaction and rendering, which improves overall performance.

- Android: for a combination of package size and performance considerations, we use [PrimJS](/guide/scripting-runtime/main-thread-runtime.md#primjs) by default
- iOS: we use [JavaScriptCore](https://trac.webkit.org/wiki/JavaScriptCore) by default, unless you need to use the [PrimJS](/guide/scripting-runtime/main-thread-runtime.md#primjs) for debugging

While these environments are very similar, you may end up hitting some inconsistencies. It is best to avoid relying on specifics of any runtime.

## WebAssembly

Starting from Lynx 3.8, Lynx provides basic WebAssembly support on Android through the PrimJS runtime integration.

This support is intended for common module loading and execution scenarios, and is currently available on the background thread only. At the moment, Lynx does not expose the complete WebAssembly JavaScript API surface. See [WebAssembly](/guide/scripting-runtime/webassembly.md) for the supported scope and current limitations.

## JavaScript Syntax Transformers

The Lynx dual-thread runtime supports the following maximum ECMAScript versions:

- Main thread: [ECMAScript 2019 (ES10)](https://tc39.es/ecma262/2019/)
- Background thread: [ECMAScript 2015 (ES6)](https://262.ecma-international.org/6.0/)

Of course, you can use new JavaScript syntax to write your code. During the build process, [SWC](https://swc.rs/) will be used as Syntax Transformer to transform your code, so you don't have to wait for JavaScript runtime support.

## JavaScript Polyfills

:::info
Only injects polyfills on iOS.

A full list of Lynx's polyfills can be found in [Lynx repository](https://github.com/lynx-family/lynx/blob/develop/js_libraries/lynx-polyfill/src/index.js)
:::

Besides syntax transformers, many built-in objects and standard functions are also available. Including:

### Built-in Objects

- [Map](https://tc39.es/ecma262/#sec-map-constructor)
- [Set](https://tc39.es/ecma262/#sec-set-constructor)
- [WeakMap](https://tc39.es/ecma262/#sec-weakmap-constructor)
- [WeakSet](https://tc39.es/ecma262/#sec-weakset-constructor)

### Array

- [Array.prototype.concat](https://tc39.es/ecma262/#sec-array.prototype.concat)
- [Array.prototype.filter](https://tc39.es/ecma262/#sec-array.prototype.filter)
- [Array.prototype.flat](https://tc39.es/ecma262/#sec-array.prototype.flat)
- [Array.prototype.flatMap](https://tc39.es/ecma262/#sec-array.prototype.flatmap)
- [Array.prototype.includes](https://tc39.es/ecma262/#sec-array.prototype.includes)
- [Array.prototype\[@@iterator\]](https://ts39.es/ecma262/#sec-array.prototype-@@iterator)
- [Array.prototype.map](https://tc39.es/ecma262/#sec-array.prototype.map)
- [Array.prototype.reverse](https://tc39.es/ecma262/#sec-array.prototype.reverse)
- [Array.prototype.slice](https://tc39.es/ecma262/#sec-array.prototype.slice)
- [Array.prototype.sort](https://tc39.es/ecma262/#sec-array.prototype.sort)
- [Array.prototype.species](https://tc39.es/ecma262/#sec-array.prototype.species)
- [Array.prototype.splice](https://tc39.es/ecma262/#sec-array.prototype.splice)
- [Array.prototype\[@@unscopables\].flat](https://ts39.es/ecma262/#sec-array.prototype-@@unscopables)
- [Array.prototype\[@@unscopables\].flatMap](https://ts39.es/ecma262/#sec-array.prototype-@@unscopables)

### ArrayBuffer

- [ArrayBuffer](https://tc39.es/ecma262/#sec-arraybuffer-objects)
- [ArrayBuffer.prototype.slice](https://tc39.es/ecma262/#sec-arraybuffer.prototype.slice)

### Date

- [Date.prototype.toJSON](https://tc39.es/ecma262/#sec-date.prototype.tojson)
- [Date.prototype\[@@toPrimitive\]](https://tc39.es/ecma262/#sec-date.prototype-@@toprimitive)

### Number

- [Number.parseFloat](https://ts39.es/ecma262/#sec-number.parseFloat)

### Object

- [Object.entries](https://tc39.es/ecma262/#sec-object.entries)
- [Object.fromEntries](https://tc39.es/ecma262/#sec-object.fromentries)
- [Object.getOwnPropertyDescriptors](https://tc39.es/ecma262/#sec-object.getownpropertydescriptors)
- [Object.toString](https://tc39.es/ecma262/#sec-object.tostring)
- [Object.values](https://tc39.es/ecma262/#sec-object.values)

### Promise

- [Promise](https://tc39.es/ecma262/#sec-promise-constructor)
- [Promise.all](https://tc39.es/ecma262/#sec-promise.all)
- [Promise.race](https://tc39.es/ecma262/#sec-promise.race)
- [Promise.reject](https://tc39.es/ecma262/#sec-promise.reject)
- [Promise.resolve](https://tc39.es/ecma262/#sec-promise.resolve)
- [Promise.prototype.catch](https://tc39.es/ecma262/#sec-promise.prototype.catch)
- [Promise.prototype.finally](https://tc39.es/ecma262/#sec-promise.prototype.finally)
- [Promise.prototype.then](https://tc39.es/ecma262/#sec-promise.prototype.then)

### Reflect

- [Reflect.apply](https://tc39.es/ecma262/#sec-reflect.apply)
- [Reflect.construct](https://tc39.es/ecma262/#sec-reflect.construct)
- [Reflect.defineProperty](https://tc39.es/ecma262/#sec-reflect.defineproperty)
- [Reflect.deleteProperty](https://tc39.es/ecma262/#sec-reflect.deleteproperty)
- [Reflect.get](https://tc39.es/ecma262/#sec-reflect.get)
- [Reflect.getOwnPropertyDescriptors](https://tc39.es/ecma262/#sec-reflect.getownpropertydescriptor)
- [Reflect.getPrototypeOf](https://tc39.es/ecma262/#sec-reflect.getprototypeof)
- [Reflect.has](https://tc39.es/ecma262/#sec-reflect.has)
- [Reflect.isExtensible](https://tc39.es/ecma262/#sec-reflect.isextensible)
- [Reflect.ownKeys](https://tc39.es/ecma262/#sec-reflect.ownkeys)
- [Reflect.preventExtensions](https://tc39.es/ecma262/#sec-reflect.preventextensions)
- [Reflect.set](https://tc39.es/ecma262/#sec-reflect.set)
- [Reflect.setPrototypeOf](https://tc39.es/ecma262/#sec-reflect.setprototypeof)

### RegExp

- [RegExp](https://ts39.es/ecma262/#sec-regexp-constructor)
- [RegExp.prototype.exec](https://tc39.es/ecma262/#sec-regexp.prototype.exec)
- [RegExp.prototype.sticky](https://tc39.es/ecma262/#sec-regexp.prototype.sticky)
- [RegExp.prototype.test](https://tc39.es/ecma262/#sec-regexp.prototype.test)
- [RegExp.prototype.toString](https://tc39.es/ecma262/#sec-regexp.prototype.tostring)

### String

- [String.prototype.endsWith](https://tc39.es/ecma262/#sec-string.prototype.endswith)
- [String.prototype.includes](https://tc39.es/ecma262/#sec-string.prototype.includes)
- [String.prototype.match](https://tc39.es/ecma262/#sec-string.prototype.match)
- [String.prototype.matchAll](https://tc39.es/ecma262/#sec-string.prototype.matchall)
- [String.prototype.padEnd](https://tc39.es/ecma262/#sec-string.prototype.padend)
- [String.prototype.padStart](https://tc39.es/ecma262/#sec-string.prototype.padstart)
- [String.prototype.replace](https://tc39.es/ecma262/#sec-string.prototype.replace)
- [String.prototype.search](https://tc39.es/ecma262/#sec-string.prototype.search)
- [String.prototype.split](https://tc39.es/ecma262/#sec-string.prototype.split)
- [String.prototype.startsWith](https://tc39.es/ecma262/#sec-string.prototype.startswith)
- [String.prototype.trim](https://tc39.es/ecma262/#sec-string.prototype.trim)
- [String.prototype.trimEnd](https://tc39.es/ecma262/#sec-string.prototype.trimend)
- [String.prototype.trimStart](https://tc39.es/ecma262/#sec-string.prototype.trimstart)

### Symbol

- [Symbol](https://tc39.es/ecma262/#sec-symbol-constructor)
- [Symbol.prototype.description](https://tc39.es/ecma262/#sec-symbol-prototype.description)
- [Symbol.asyncIterator](https://tc39.es/ecma262/#sec-symbol.asynciterator)
- [Symbol.hasInstance](https://tc39.es/ecma262/#sec-symbol.hasinstance)
- [Symbol.isConcatSpreadable](https://tc39.es/ecma262/#sec-symbol.isconcatspreadable)
- [Symbol.match](https://tc39.es/ecma262/#sec-symbol.match)
- [Symbol.matchAll](https://tc39.es/ecma262/#sec-symbol.matchall)
- [Symbol.replace](https://tc39.es/ecma262/#sec-symbol.replace)
- [Symbol.search](https://tc39.es/ecma262/#sec-symbol.search)
- [Symbol.species](https://tc39.es/ecma262/#sec-symbol.species)
- [Symbol.split](https://tc39.es/ecma262/#sec-symbol.split)
- [Symbol.toPrimitive](https://tc39.es/ecma262/#sec-symbol.toprimitive)
- [Symbol.toStringTag](https://tc39.es/ecma262/#sec-symbol-prototype.tostringtag)

## Module

You can use JavaScript module when developing Lynx project.

Lynx currently supports [ESModule](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [CommonJS](https://en.wikipedia.org/wiki/CommonJS). The usage of ESModule and CommonJS can be mixed.

It is recommended to use ESModule, which allows for better [Tree Shaking](https://webpack.js.org/guides/tree-shaking/).

### Module Names

Both ESModule and CommonJS, a module name needs to be specified. It can be one of:

- Relative path: `./common.js`
- Name of a npm package: `lodash` (C++ addon and NodeJS builtin packages are not supported)
- Path with [alias](/api/rspeedy/rspeedy.source.alias.md): `@common/foo.js`

### CommonJS

CommonJS uses `require(path)` to import a module. Uses `module.exports` or `exports` to export a module.


**common.js**

```js title="common.js" {1,10-11}
const lodash = require('lodash'); // can require npm packages
function hello(name) {
  console.log(`Hello ${lodash.capitalize(name)} !`);
}

function goodbye(name) {
  console.log(`Goodbye ${name} !`);
}

module.exports.hello = hello;
exports.goodbye = goodbye;
```


**ReactLynx**

```jsx {1,6,10}
const { Component } = require('@lynx-js/react'); // can require npm packages

export default App extends Component {
  constructor(props) {
    super(props);
    const common = require('./common.js'); // can require relative path
    common.hello('world');
  }
  componentDidMount() {
    const common = require('./common.js'); // can require relative path
    common.goodbye('world');
  }
  render() {
    return <view><text>Hello, world!</text></view>;
  }
}
```


:::tip

- `require` can be anywhere in your code, not required to be at top.

- `require` will **synchronously** execute the target module.

- `require` will cache the returned object. Multiple `require` to the same path will return the **same** value. e.g:

```js
require('foo') === require('foo'); // true
```

:::

### ESModule

ESModule uses `import` to import a module. Uses `export` to export a module.
`import` and `export` must be placed at the top level of source file.

ESModule can also use `import()` to dynamically import a module.


**utils.js**

```js title="utils.js"
export function getAge() {
  return 11;
}

export default function (add1, add2) {
  return add1 + add2;
}
```


**ReactLynx**

```jsx {1-2,8,13}
import { Component } from '@lynx-js/react'; // can import npm packages
import { capitalize } from 'lodash';

export default App extends Component {
  constructor(props) {
    super(props);
    // can dynamic import relative path
    import('./utils.js').then(utils => {
      capitalize(utils.getSum());
    });
  }
  async componentDidMount() {
    const utils = await import('./utils.js'); // can dynamic import relative path
    utils.getAge();
  }
  render() {
    return <view><text>Hello, world!</text></view>;
  }
}
```




---
url: /guide/scripting-runtime/webassembly.md
---

# WebAssembly

3.8
Starting from Lynx 3.8, Lynx provides basic WebAssembly support on Android through the PrimJS runtime integration.

This capability is designed for common WebAssembly loading and execution scenarios in Lynx applications. It is currently available on the background thread only and is not supported on the main thread. The current implementation focuses on practical interoperability between JavaScript and WebAssembly, rather than full compatibility with the complete WebAssembly JavaScript API.

## What Is Supported

Lynx currently supports the following core flows:

- Create modules with `new WebAssembly.Module(...)`
- Instantiate modules with `new WebAssembly.Instance(...)`
- Call exported WebAssembly functions from JavaScript
- Use `WebAssembly.Memory`, `WebAssembly.Table`, and `WebAssembly.Global` in common cases
- Provide function, memory, table, and global imports during instantiation

## Current Limitations

The current support is intentionally scoped.

- This capability is currently available on Android in Lynx 3.8
- WebAssembly is currently available on the background thread only
- WebAssembly is not supported on the main thread
- The complete WebAssembly JavaScript API is not available yet
- Some static APIs on `WebAssembly`, such as `compile`, `instantiate`, `validate`, and streaming variants, are not supported yet
- Some advanced reflection APIs and behaviors are still partial

In practice, it is recommended to use the constructor-based flow based on `WebAssembly.Module` and `WebAssembly.Instance`.

## Example

```js
const module = new WebAssembly.Module(wasmBytes);
const instance = new WebAssembly.Instance(module, imports);

const result = instance.exports.add(1, 2);
```

Try the complete Lynx example below to see the same flow in a page:

**This is an example below: webassembly**

**Entry:** `src`
**Bundle:** `dist/main.lynx.bundle`

```tsx
import { useCallback, useState } from "@lynx-js/react";

import { addWithWasm } from "./addWasm.js";

import "./App.css";

export function App() {
  const [result, setResult] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);

  const calculate = useCallback(() => {
    "background-only";
    setError(null);

    try {
      setResult(addWithWasm(1, 2));
    } catch (err) {
      setResult(null);
      setError(err instanceof Error ? err.message : "Failed to run WebAssembly");
    }
  }, []);

  return (
    <page>
      <view className="App">
        <view className="Panel">
          <text className="Eyebrow">WebAssembly on Lynx</text>
          <text className="Title">1 + 2</text>
          <text className="Formula">Calculated by a Wasm add function</text>

          <view className="Button" bindtap={calculate}>
            <text className="ButtonText">Run add(1, 2)</text>
          </view>

          <view className="ResultBox">
            <text className="ResultLabel">Result</text>
            <text className="ResultValue">
              {error ?? (result == null ? "Tap to calculate" : String(result))}
            </text>
          </view>
        </view>
      </view>
    </page>
  );
}

```



For more details about the underlying runtime support, see the [PrimJS WebAssembly document](https://github.com/lynx-family/primjs/blob/develop/docs/wasm.md).



---
url: /guide/scripting-runtime/main-thread-runtime.md
---

# Main Thread Runtime

## [PrimJS](https://github.com/lynx-family/primjs)

The main thread uses PrimJS as the runtime engine. PrimJS is a lightweight, high-performance JavaScript engine designed specifically for Lynx. PrimJS is built on top of [QuickJS](https://bellard.org/quickjs/) and offers a much better performance and development experience than QuickJS.

Meanwhile, PrimJS provides a high-performance FFI capability, which can encapsulate the Lynx object as a JS object and return it to the FFI caller at low cost, which has obvious performance advantage over the traditional FFI. However, this type of JS object is not an Object Model, Lynx engine can not bind setter getter methods to this object, it can only provide FFI to pass it as a parameter to realize similar functions.

## [Element PAPI](/api/engine/element-api.md) Bindings

In order to achieve high performance, the Element PAPI provided in the main thread runtime is based on the above approach. Since ReactLynx developers don't need to manipulate Element directly in most scenarios, this limitation of high-performance FFI doesn't degrade the experience.

If developers need to operate Element directly, we provide the [main-thread-element](/api/lynx-api/main-thread/main-thread-element.md) based on the Element PAPI to improve the development experience.

## [Lynx API](/api/lynx-api/main-thread.md) Bindings

Because of the special nature of the main thread, we only provide Lynx APIs in the main thread that do not affect rendering, which are a subset of the background thread APIs.

## Runtime Script Format

For performance optimization, the main thread scripts use the bytecode format compiled by PrimJS. This format avoids the parsing of scripts at runtime, and the bytecode format can be loaded about four times faster than normal text format scripts.



---
url: /guide/use-native-modules.md
---

# Native Modules

When developing Lynx applications, you may encounter scenarios where you need to interact with native platform APIs not covered by Lynx. Or, you might want to reuse existing native platform code in your Lynx application. Regardless of the reason, you can use [**Native Modules**](/guide/spec.md#nativemodules) to seamlessly connect your JavaScript code with native code, allowing you to call native platform functions and APIs from your JavaScript code. The following will detail how to write a native module.

The basic steps for writing a native module are as follows:

1. Use TypeScript to **declare your typed interface specification**.
2. Use your interface specification to **write your Lynx application code**.
3. Follow your interface specification to **write your native platform code** and connect your native code to the Lynx runtime environment.

Next, this guide will demonstrate these steps through an example of building a native module.

:::info
Currently, native modules can only be used in [Background Thread Scripting](/guide/spec.md#background-thread-scripting).
:::

## Local Persistent Storage Module

This guide aims to show you how to write a local persistent storage module that enables your Lynx application to use JavaScript code to store data persistently locally.

To implement local persistent storage on mobile devices, you need to use the native APIs of Android, iOS and HarmonyOS:

- Android: [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences)
- iOS: [NSUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults)
- HarmonyOS: [Preferences](https://developer.huawei.com/consumer/en/doc/harmonyos-references/_preferences)

### Declare a Typed Interface Specification
The interface specification of a native module serves as a bridge between the native code and the Lynx JavaScript runtime, defining the methods and data types passed between them.
The steps to declare an interface specification are as follows:
1. **Create a Lynx project**: Refer to the [Create a Lynx Project](/guide/start/quick-start.md#Installation) guide to create your Lynx project.
2. **Create a new type declaration file**: Create a new file named `src/typing.d.ts` in your Lynx project.
3. **Implement the interface specification**: Implement the interface specification of the native module in the `typing.d.ts` file.
:::info
You can view the types available in the specification and their corresponding native types in the [Type Mapping Table](#type-mapping-table).
:::
The following is the implementation of the interface specification for the local persistent storage module:
```typescript title="typing.d.ts"
declare let NativeModules: {
  NativeLocalStorageModule: {
    setStorageItem(key: string, value: string): void;
    getStorageItem(key: string, callback: (value: string) => void): void;
    clearStorage(): void;
  };
};
```
`NativeModules` is a global built-in object provided by Lynx in the JavaScript runtime. It serves as the access point for all native modules, and all native module declarations must be defined within it.
### Write Your Lynx Application Code
Next, write your application code in `src/App.tsx` within your Lynx project.
The following is the `App.tsx` for the local persistent storage module. It includes an area to display the content read from local storage and three buttons for reading, writing, and clearing local storage.
**This is an example below: local-storage**

**Bundle:** `dist/main.lynx.bundle`

```tsx {11,19,24}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { useEffect, useState } from "@lynx-js/react";

export function App() {
  const [storedValue, setStoredValue] = useState<string | null>(null);

  const setStorage = () => {
    NativeModules.NativeLocalStorageModule.setStorageItem(
      "testKey",
      "Hello, ReactLynx!",
    );
    getStorage();
  };

  const getStorage = () => {
    NativeModules.NativeLocalStorageModule.getStorageItem("testKey", (value) => {
      setStoredValue(value);
    });
  };

  const clearStorage = () => {
    NativeModules.NativeLocalStorageModule.clearStorage();
    setStoredValue(null);
  };

  useEffect(() => {
    getStorage();
  }, []);

  const containerStyle = {
    display: "flex",
    flexDirection: "column",
    alignItems: "center",
    justifyContent: "center",
    height: "100vh",
  } as const;

  const contentBoxStyle = {
    border: "1px solid #ccc",
    padding: "2px",
    marginBottom: "20px",
    borderRadius: "5px",
    width: "300px",
    textAlign: "center",
  } as const;

  const buttonContainerStyle = {
    display: "flex",
    flexDirection: "column",
    width: "max-content",
  } as const;

  const buttonStyle = {
    padding: "2px",
    margin: "5px",
    backgroundColor: "#ec644c",
    borderRadius: "5px",
    fontSize: "16px",
    boxShadow: "0 2px 4px rgba(0, 0, 0, 0.2)",
    flexShrink: "0",
  };

  const textStyle = {
    fontSize: "18px",
    margin: "10px 0",
    color: "#333",
  };

  const buttonTextStyle = {
    fontSize: "18px",
    margin: "10px 0",
    color: "#fffffe",
    alignSelf: "center",
  };

  return (
    <view style={containerStyle}>
      <view style={contentBoxStyle}>
        <text style={textStyle}>
          Current stored value: {storedValue || "None"}
        </text>
      </view>
      <view style={buttonContainerStyle}>
        <view style={buttonStyle} bindtap={setStorage}>
          <text style={buttonTextStyle}>Set storage: Hello, ReactLynx!</text>
        </view>
        <view style={buttonStyle} bindtap={getStorage}>
          <text style={buttonTextStyle}>Read storage</text>
        </view>
        <view style={buttonStyle} bindtap={clearStorage}>
          <text style={buttonTextStyle}>Clear storage</text>
        </view>
      </view>
    </view>
  );
}

```


### Write Your Native Platform Code
Now, you can start writing the native platform code.
iOSAndroidHarmonyOS#### Prepare Your Xcode Project

First, follow the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide to create a Lynx Explorer project locally and open it with Xcode.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step1.png)

Next, right-click on the `modules` folder in the Lynx Explorer project and select `New File...` to create the header and source files for the native module.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step2.png)

Then, use the `Cocoa Touch Class` template.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step3.png)

Name the class `NativeLocalStorageModule`. You can choose to create it in either `Objective-C` or `Swift`. Then click `Next` to complete the file creation.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-ios-step4.png)

#### Implement Your Native Module

:::info
You need to implement an additional static method `name` in the native module to return the exported name of your native module. Also, implement an additional static method `methodLookup` in the native module to map the names of the methods to be exported to their corresponding selectors.
:::


**Objective-C**

```objective-c {6} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.h"

#import <Foundation/Foundation.h>
#import <Lynx/LynxModule.h>

NS_ASSUME_NONNULL_BEGIN

@interface NativeLocalStorageModule : NSObject <LynxModule>

@end

NS_ASSUME_NONNULL_END

```
```objective-c {18-20,22-27} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.m"
#import "NativeLocalStorageModule.h"

@interface NativeLocalStorageModule()
@property (strong, nonatomic) NSUserDefaults *localStorage;
@end

@implementation NativeLocalStorageModule

static NSString *const NativeLocalStorageKey = @"MyLocalStorage";

- (instancetype)init {
    if (self = [super init]) {
        _localStorage = [[NSUserDefaults alloc] initWithSuiteName:NativeLocalStorageKey];
    }
    return self;
}

+ (NSString *)name {
    return @"NativeLocalStorageModule";
}

+ (NSDictionary<NSString *, NSString *> *)methodLookup {
    return @{
        @"setStorageItem": NSStringFromSelector(@selector(setStorageItem:value:)),
        @"getStorageItem": NSStringFromSelector(@selector(getStorageItem:callback:)),
        @"clearStorage": NSStringFromSelector(@selector(clearStorage))
    };
}

- (void)setStorageItem:(NSString *)key value:(NSString *)value {
    [self.localStorage setObject:value forKey:key];
}

- (void)getStorageItem:(NSString *)key callback:(void(^)(NSString *value)) callback{
    NSString *value = [self.localStorage stringForKey:key];
    callback(value);
}

- (void)clearStorage {
    NSDictionary *keys = [self.localStorage dictionaryRepresentation];
    for (NSString *key in keys) {
        [self.localStorage removeObjectForKey:key];
    }
}

@end

```


**Swift**

:::tip
Lynx Explorer is a project built with Objective-C. If you wish to implement a native module with Swift, please refer to [Importing Objective-C into Swift](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header file `LynxModule.h`.
:::
```swift title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/LynxExplorer-Bridging-Header.h"

//
//  Use this file to import your target's public headers that you would like to expose to Swift.
//

#import <Lynx/LynxModule.h>


```
```swift {6-8,10-16} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/modules/NativeLocalStorageModule.swift"

import Foundation

@objcMembers
public final class NativeLocalStorageModule: NSObject, LynxModule {

    public static var name: String {
        return "NativeLocalStorageModule"
    }

    public static var methodLookup: [String : String] {
        return [
            "setStorageItem": NSStringFromSelector(#selector(setStorageItem(_:value:))),
            "getStorageItem": NSStringFromSelector(#selector(getStorageItem(_:completion:))),
            "clearStorage": NSStringFromSelector(#selector(clearStorage))
        ]
    }

    private let localStorage: UserDefaults
    private static let storageKey = "MyLocalStorage"

    public init(param: Any) {
      guard let suite = UserDefaults(suiteName: NativeLocalStorageModule.storageKey) else {
          fatalError("Failed to initialize UserDefaults with suiteName: \(NativeLocalStorageModule.storageKey)")
      }
      localStorage = suite
      super.init()
    }

    public override init() {
        guard let suite = UserDefaults(suiteName: NativeLocalStorageModule.storageKey) else {
            fatalError("Failed to initialize UserDefaults with suiteName: \(NativeLocalStorageModule.storageKey)")
        }
        localStorage = suite
        super.init()
    }

    func setStorageItem(_ key: String, value: String) {
        localStorage.set(value, forKey: key)
    }

    objc func getStorageItem(_ key: String, completion:(NSString) -> Void) {
      if let value = localStorage.string(forKey: key) {
          completion(value as NSString)
      } else {
          completion("" as NSString)
      }
    }

    func clearStorage() {
        localStorage.dictionaryRepresentation().keys.forEach {
            localStorage.removeObject(forKey: $0)
        }
    }

}

```


Next, you need to register your native module into the Lynx runtime environment.

Add the following registration code to the `setupLynxEnv` method in the `explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m` file of the Lynx Explorer project to register your native module with the global configuration of the Lynx runtime environment.


**Objective-C**

```objective-c {7} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m"

#import "NativeLocalStorageModule.h"

- (void)setupLynxEnv {
  // ...

  // register global JS module
  [globalConfig registerModule:NativeLocalStorageModule.class];

  // ...
}


NS_ASSUME_NONNULL_END

```


**Swift**

:::tip
Lynx Explorer is a project built with Objective-C. If you want to use Swift native modules in Objective-C files, please refer to [Importing Swift into Objective-C](https://developer.apple.com/documentation/swift/importing-swift-into-objective-c) to generate and import the `LynxExplorer-Swift.h` header file.
:::
```objective-c {7} title="explorer/darwin/ios/lynx_explorer/LynxExplorer/LynxInitProcessor.m"

#import "LynxExplorer-Swift.h"

- (void)setupLynxEnv {
  // ...

  // register global JS module
  [globalConfig registerModule:NativeLocalStorageModule.class];

  // ...
  }

NS_ASSUME_NONNULL_END

```


#### Run Your Code

Once you've prepared everything, you can now build and run your code.

First, follow the [Build and Run iOS Lynx Explorer](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios#build-ios-app) guide to build Lynx Explorer and install it on your phone.

Next, refer to the [Install Dependencies & Start the Development Server](/guide/start/quick-start.md#Installation) guide to install dependencies and start the development server in the root directory of your Lynx project.

Install dependencies:


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

Start the development server:


```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```

You'll see a QR code and an artifact link in the console. Use Lynx Explorer to scan the QR code or enter the artifact link to open your Lynx page.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-demo-ios-en.gif)
First, follow the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide to create a Lynx Explorer project locally.

Next, create a new `NativeLocalStorageModule.java` or `NativeLocalStorageModule.kt` file in the `explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/` path of the Lynx Explorer project. Then, inherit from `LynxModule` to implement the `NativeLocalStorageModule` native module.

:::info
You need to add the `@LynxMethod` annotation to the methods that need to be exported in the native module.
:::


**Java**

```java {22,30,37} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/NativeLocalStorageModule.java"
package com.lynx.explorer.modules;

import android.content.Context;
import android.content.SharedPreferences;

import com.lynx.jsbridge.LynxMethod;
import com.lynx.jsbridge.LynxModule;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.react.bridge.Callback;

public class NativeLocalStorageModule extends LynxModule {
  private static final String PREF_NAME = "MyLocalStorage";
  public NativeLocalStorageModule(Context context) {
    super(context);
  }

  Context getContext() {
    LynxContext lynxContext = (LynxContext) mContext;
    return lynxContext.getContext();
  }

  @LynxMethod
  public void setStorageItem(String key, String value) {
    SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
    SharedPreferences.Editor editor = sharedPreferences.edit();
    editor.putString(key, value);
    editor.apply();
  }

  @LynxMethod
  public void getStorageItem(String key, Callback callback) {
    SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
    String value = sharedPreferences.getString(key, null);
    callback.invoke(value);
  }

  @LynxMethod
  public void clearStorage() {
    SharedPreferences sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
    SharedPreferences.Editor editor = sharedPreferences.edit();
    editor.clear();
    editor.apply();
  }
}

```


**Kotlin**

```kotlin {18,26,32} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/NativeLocalStorageModule.kt"

package com.lynx.explorer.modules

import android.content.Context
import com.lynx.jsbridge.LynxMethod
import com.lynx.jsbridge.LynxModule
import com.lynx.tasm.behavior.LynxContext
import com.lynx.react.bridge.Callback

class NativeLocalStorageModule(context: Context) : LynxModule(context) {
  private val PREF_NAME = "MyLocalStorage"

  private fun getContext(): Context {
    val lynxContext = mContext as LynxContext
    return lynxContext.getContext()
  }

  @LynxMethod
  fun setStorageItem(key: String, value: String) {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    val editor = sharedPreferences.edit()
    editor.putString(key, value)
    editor.apply()
  }

  @LynxMethod
  fun getStorageItem(key: String, callback: Callback) {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    callback(sharedPreferences.getString(key, null))
  }

  @LynxMethod
  fun clearStorage() {
    val sharedPreferences = getContext().getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE)
    val editor = sharedPreferences.edit()
    editor.clear()
    editor.apply()
  }
}

```


Next, you need to register your native module with the Lynx runtime environment.

Add the following registration code to the `Init` method in the `explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java` file of the Lynx Explorer project to register your native module with the Lynx runtime environment. Here, you need to specify the name of the native module you are exporting, which must be consistent with your interface specification.

```java {4} title="explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/modules/LynxModuleAdapter.java"

  public void Init(Context context) {
    // ......

    LynxEnv.inst().registerModule("NativeLocalStorageModule", NativeLocalStorageModule.class);

    // ......
  }

```

After preparing everything, you can now build and run your code.

First, follow the [Compile and Run Android Lynx Explorer](https://github.com/lynx-family/lynx/tree/develop/explorer/android#compile-and-run) guide to build Lynx Explorer from source code and install it on your phone.

Then, refer to the [Install Dependencies & Start the Development Server](/guide/start/quick-start.md#Installation) guide to install dependencies and start the development server in the root directory of your Lynx project.

Install dependencies:


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

Start the development server:


```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```

You will see a QR code in the console. Use Lynx Explorer to scan the QR code to open the page.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-demo-android-en.gif)
First, follow the [Build Lynx Explorer for HarmonyOS](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide to create a Lynx Explorer project locally.

Next, create a new `NativeLocalStorageModule.ets` file in the Lynx Explorer project and inherit from `LynxModule` in the `@lynx/lynx` package to implement the `NativeLocalStorageModule` native module.

:::info
You can add the `@Sendable` annotation to the Module class to convert it into a Sendable Module. Only the methods of a Sendable Module are synchronous; all other methods are asynchronous. The return value of an asynchronous method is `null`.
:::

```typescript title="NativeLocalStorageModule.ets"
import { LynxContext, LynxModule } from '@lynx/lynx';
import common from '@ohos.app.ability.common';
import { preferences } from '@kit.ArkData';

export class NativeLocalStorageModule extends LynxModule {
  private static readonly PREF_NAME: string = "NativeLocalStorageModule";
  private dataPreferences: preferences.Preferences | null = null;

  constructor(context: LynxContext, param?: Object) {
    super(context, param);
    this.initPreferencesSync();
  }

  private initPreferencesSync() {
    try {
      this.dataPreferences = preferences.getPreferencesSync(
        getContext(), 
        { name: NativeLocalStorageModule.PREF_NAME }
      );
      console.info("Preferences initialization succeeded.");
    } catch (error) {
      console.error(`Failed to initialize preferences: ${error}`);
    }
  }

  public setStorageItem(key: string, value: string) {
    if (!this.dataPreferences) {
      console.error("Preferences instance is not initialized.");
      return;
    }

    try {
      this.dataPreferences.putSync(key, value);
      this.dataPreferences.flushSync();
      console.info(`Storage item set successfully. key=${key}`);
    } catch (err) {
      console.error(`Failed to set storage item. key=${key}, error=${err.message}`);
    }
  }

  public getStorageItem(key: string, callback: (value: string)=> void) {
    if (!this.dataPreferences) {
      console.error("Preferences instance is not initialized.");
      callback("");
      return;
    }

    try {
      const value = this.dataPreferences.getSync(key, "");
      callback(value as string);
      return;
    } catch (err) {
      console.error(`Failed to get storage item. key=${key}, error=${err.message}`);
      callback("");
      return;
    }
  }

  public clearStorage() {
    if (!this.dataPreferences) {
      console.error("Preferences instance is not initialized.");
      return;
    }

    try {
      this.dataPreferences.clearSync();
      this.dataPreferences.flushSync();
      console.info("Storage cleared successfully.");
    } catch (err) {
      console.error(`Failed to clear storage. error=${err.message}`);
    }
  }
}

```

Next, register the native module with the Lynx runtime environment.

In the aboutToAppear method of the explorer/harmony/lynx\_explorer/src/main/ets/pages/Lynx.ets file in your Lynx Explorer project, add the following registration code to register the native module with the Lynx runtime environment. Here, you need to specify the name of the native module, which must be consistent with the name in the interface specification above.

:::info
Register a regular Module in `this.modules` , and a Sendable Module in `this.sendableModules` .
:::

```typescript {8-10,12} title="src/main/ets/pages/Lynx.ets"
import { NativeLocalStorageModule } from '../module/NativeLocalStorageModule';

@Entry
@Component
struct Lynx {
  aboutToAppear() {
    // `param` is an optional constructor parameter for the module
    this.modules.set('NativeLocalStorageModule', {
      moduleClass: NativeLocalStorageModule
    });
    // Register Sendable Modules to this.sendableModules
  }
}
```

Once you've prepared everything, you can now build and run your code.

First, follow the [Build and Run Harmony Lynx Explorer](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide to build Lynx Explorer and install it on your phone.

Next, refer to the [Install Dependencies & Start the Development Server](/guide/start/quick-start.md#Installation) guide to install dependencies and start the development server in the root directory of your Lynx project.

Install dependencies:


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

Start the development server:


```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```

You'll see a QR code and an artifact link in the console. Use Lynx Explorer to scan the QR code or enter the artifact link to open your Lynx page.

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/native-modules-demo-harmony.gif)

Congratulations! You have successfully created a native module in Lynx Explorer! If you want to create a native module in your application, you first need to integrate Lynx by referring to the [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md) guide, and then follow the steps above to create the native module.

## Type Mapping Table

| TypeScript    | iOS(Objective-C)                                  | Android(Java)                                     | HarmonyOS(ets) |
| ------------- | ------------------------------------------------- | ------------------------------------------------- | -------------- |
| `null`        | `nil`                                             | `null`                                            | `null`         |
| `undefined`   | `nil`                                             | `null`                                            | `undefined`    |
| `boolean`     | `BOOL` (or `NSNumber` when used inside objects)   | `boolean` (or `Boolean` when used inside objects) | `boolean`      |
| `number`      | `double` (or `NSNumber` when used inside objects) | `double` (or `Number` when used inside objects)   | `number`       |
| `string`      | `NSString`                                        | `String`                                          | `string`       |
| `BigInt`      | `NSString`                                        | `long` (or `Number` when used inside objects)     | `BigInt`       |
| `ArrayBuffer` | `NSData`                                          | `byte[]`                                          | `Buffer`       |
| `object`      | `NSDictionary`                                    | `com.lynx.react.bridge.ReadableMap`               | `object`       |
| `array`       | `NSArray`                                         | `com.lynx.react.bridge.ReadableArray`             | `array`        |
| `function`    | block `void (^)(id)`                              | `com.lynx.react.bridge.Callback`                  | `function`     |

## Native Module Permission Verification (Experimental)

Starting from Lynx SDK 3.5, developers can use `LynxViewBuilder` to set a native module validator for the current `LynxView`, thereby controlling all native module calls within the `LynxView`. Currently, this feature is only supported on Android and iOS, with HarmonyOS support to be added in the future.

iOSAndroidWhen creating a `LynxView` using `LynxViewBuilder`, register a native module validator through the `registerModuleAuthValidator` interface. The validator will apply to all native module calls within the current `LynxView`.
**Native Module Validator Interface**
```java title=""

/**
* LynxMethod verification interface, used to verify whether the LynxMethod is allowed to be
* called
*/
public interface AuthValidator {
/**
 *
 * @param moduleName The name of the called native module
 * @param methodName The name of the called native module method
 * @param methodParams The parameters of the called native module method
 * @return
 * true: Verification passed, the native module call will be executed
 * false: Verification failed, the native module call will not be executed, and a JS error will be generated
 */
boolean verify(String moduleName, String methodName, JavaOnlyArray methodParams);
}

```
**Native Module Validator Registration Method**
```java title=""

LynxViewBuilder builder = LynxView.builder()
// Register the validator instance with LynxViewBuilder
.registerModuleAuthValidator(new LynxModule.AuthValidator() {
void validate(@NonNull String moduleName, @NonNull String moduleName, @NonNull ReadableMap params) {
//Validation logic
return result;
}
}
LynxView view = builder.build(context);

```
When creating a `LynxView` using `LynxViewBuilder`, register a native module validator through the `registerMethodAuth` interface. The validator will apply to all native module calls within the current `LynxView`.
**Native Module Validator Interface**
```objective-c title=""

/**
*
* @param method: The name of the called native module method
* @param module: The called native module
* @param invoke_session: The timestamp of the native module call
* @param inv：The dynamic invocation method for this call
* @return
* true: Verification passed, the native module call will be executed
* false: Verification failed, the native module call will not be executed, and a JS error will be generated
*/
typedef BOOL (^LynxMethodBlock)(NSString *method, NSString *module, NSString *invoke_session,
NSInvocation *inv);

```
**Native Module Validator Registration Method**
```objective-c title=""

// Register the validator instance with LynxViewBuilder
LynxViewBuilder *builder = GetLynxViewBuilder();
[builder.config registerMethodAuth:validtorBlock];

```
## 




---
url: /guide/custom-native-component.md
---

# Custom Element

If the built-in elements do not meet your requirements, you can extend Lynx's capabilities by creating custom native elements. This section will guide you through creating and registering custom elements on Android, iOS and HarmonyOS platforms.

:::info Prerequisites

✅ Completed [Quick Start](/guide/start/quick-start.md)

✅ Completed [Lynx Integration](/guide/start/integrate-with-existing-apps.md)

✅ Familiar with [element Basics](/guide/ui/elements-components.md)

:::

## Building your Native Code

iOSAndroidHarmonyOSWebThe implementation of custom native elements can be broken down into several steps, including: declaring and registering elements, creating native views, handling styles and properties, event binding, etc. Let's take a simple custom input element `<explorer-input>` as an example to briefly introduce the implementation process of custom elements.

The complete implementation can be found in the [LynxExplorer/input module](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios/lynx_explorer/LynxExplorer/input). You can compile and run the [LynxExplorer sample project](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) to preview element behavior in real-time.

### Declare and Register Elements
#### Declare Custom Elements
A declared custom element needs to inherit from `LynxUI`. Below is the implementation of the `<explorer-input>` element:
```objc title="LynxExplorerInput.h" {1,11}

#import <Lynx/LynxUI.h>

NS_ASSUME_NONNULL_BEGIN

@interface LynxTextField : UITextField

@property(nonatomic, assign) UIEdgeInsets padding;

@end

@interface LynxExplorerInput : LynxUI <LynxTextField *> <UITextFieldDelegate>

@end

NS_ASSUME_NONNULL_END
```
```objc title="LynxExplorerInput.m"

#import "LynxExplorerInput.h"

@implementation LynxExplorerInput

//...

@end



@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
#### Register Custom Element
Elements can be registered in two ways: globally and locally.
##### Global Registration
Globally registered elements can be shared across multiple `LynxView` instances.
```objc title="LynxExplorerInput.m" {2,6}

#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

@end



@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
##### Local Registration
Locally registered elements are only applicable to the current `LynxView` instance.
```objc {7}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

  LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
    builder.config =
        [[LynxConfig alloc] initWithProvider:[LynxEnv sharedInstance].config.templateProvider];
    [builder.config registerUI:[LynxExplorerInput class] withName:@"explorer-input"];
  }];
```
Where `"explorer-input"` corresponds to the tag name in the front-end DSL. When Lynx Engine parses this tag, it will look for the registered native element and create an instance.
### Create Native `View` Instance
Each custom element needs to implement the `createView` method, which returns a corresponding native `View` instance.
Here is the implementation for the `<explorer-input>` element:
```objc title="LynxExplorerInput.m" {8-13}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
### Handle Front-End Style and Property Updates
You can use the `LYNX_PROP_SETTER` macro to listen for property changes passed from the front end and update the native view. For example, handling the `value` property of the `<explorer-input>` element:
```objc title="LynxExplorerInput.m" {3,9-11}

#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
### Handle Layout Information (Optional)
#### Handle Lynx Engine Layout Results
Typically, Lynx Engine automatically calculates and updates the `View` layout information, so developers do not need to manually handle this. However, in some special cases, such as when additional adjustments to the `View` are required, you can obtain the latest layout information in the `layoutDidFinished` callback and apply custom logic.
```objc title="LynxExplorerInput.m" {9-11}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

- (void)layoutDidFinished {
  self.view.padding = self.padding;
  }

LYNX_PROP_SETTER("value", setValue, NSString \*) {
self.view.text = value;
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  return textField;
  }

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
  }

- (void)setPadding:(UIEdgeInsets)padding {
  \_padding = padding;
  [self setNeedsLayout];
  }

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
  }

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
  }
  @end

```
### Handle Event Binding (Optional)
In some scenarios, the front-end may need to respond to events from custom elements. For example, when the user types in the input box, the front-end might
need to capture and process the input data.
Here is an example of how to send a text input event from the `<explorer-input>` element to the front-end and how the front-end listens for the event.
#### Client-Side Event Sending
The client listens to text input callbacks from the native view, and when the text changes, it uses `[self.context.eventEmitter dispatchCustomEvent:eventInfo]` to send the event to the front-end for handling.
```objc title="LynxExplorerInput.m" {13-16,20-25,27-32}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(textFieldDidChange:)
                                        name:UITextFieldTextDidChangeNotification
                                        object:textField];
  return textField;
}

- (void)emitEvent:(NSString *)name detail:(NSDictionary *)detail {
  LynxCustomEvent *eventInfo = [[LynxDetailEvent alloc] initWithName:name
                                                          targetSign:[self sign]
                                                              detail:detail];
  [self.context.eventEmitter dispatchCustomEvent:eventInfo];
}

- (void)textFieldDidChange:(NSNotification *)notification {
  [self emitEvent:@"input"
           detail:@{
             @"value": [self.view text] ?: @"",
           }];
}

- (void)layoutDidFinished {
    self.view.padding = self.padding;
}

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
#### Front-End DSL Event Binding
On the front-end, bind the corresponding input event to listen for and handle the text input data sent by the client.
```jsx title="App.tsx"
const handleInput = (e) => {
  const currentValue = e.detail.value.trim();
  setInputValue(currentValue);
};

<explorer-input
  className="input-box"
  bindinput={handleInput}
  value={inputValue}
/>;
```
> **Note**: The front-end DSL uses `bindxxx` for event binding, such as `bindinput` to bind the `input` event.
### Support Direct Element Manipulation (Optional)
In some cases, the front-end may need to directly manipulate custom elements via imperative APIs. You can make elements support such operations with `LYNX_UI_METHOD`.
#### Front-End Call Example
The following code shows how to use [SelectorQuery](/api/lynx-api/selector-query.md) to call the `focus` method and focus the `<explorer-input>` element:
```jsx title="App.tsx"
lynx
  .createSelectorQuery()
  .select('#input-id')
  .invoke({
    method: 'focus',
    params: {},
    success: function (res) {
      console.log('lynx', 'request focus success');
    },
    fail: function (res) {
      console.log('lynx', 'request focus fail');
    },
  })
  .exec();
```
#### Client-Side Implementation
On the client side, use `LYNX_UI_METHOD` to add a `focus` method to the custom element to handle the front-end call.
```objc title="LynxExplorerInput.m" {4,10-16}
#import "LynxExplorerInput.h"
#import <Lynx/LynxComponentRegistry.h>
#import <Lynx/LynxPropsProcessor.h>
#import <Lynx/LynxUIMethodProcessor.h>

@implementation LynxExplorerInput

LYNX_LAZY_REGISTER_UI("explorer-input")

LYNX_UI_METHOD(focus) {
    if ([self.view becomeFirstResponder]) {
        callback(kUIMethodSuccess, nil);
    } else {
        callback(kUIMethodUnknown, @"fail to focus");
    }
}

- (UITextField *)createView {
  UITextField *textField = [[LynxTextField alloc] init];
  //...
  textField.delegate = self;
  [[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(textFieldDidChange:)
                                        name:UITextFieldTextDidChangeNotification
                                        object:textField];
  return textField;
}

- (void)emitEvent:(NSString *)name detail:(NSDictionary *)detail {
  LynxCustomEvent *eventInfo = [[LynxDetailEvent alloc] initWithName:name
                                                          targetSign:[self sign]
                                                              detail:detail];
  [self.context.eventEmitter dispatchCustomEvent:eventInfo];
}

- (void)textFieldDidChange:(NSNotification *)notification {
  [self emitEvent:@"input"
           detail:@{
             @"value": [self.view text] ?: @"",
           }];
}

- (void)layoutDidFinished {
    self.view.padding = self.padding;
}

LYNX_PROP_SETTER("value", setValue, NSString *) {
    self.view.text = value;
}

@end

@implementation LynxTextField

- (UIEditingInteractionConfiguration)editingInteractionConfiguration API_AVAILABLE(ios(13.0)) {
  return UIEditingInteractionConfigurationNone;
}

- (void)setPadding:(UIEdgeInsets)padding {
  _padding = padding;
  [self setNeedsLayout];
}

- (CGRect)textRectForBounds:(CGRect)bounds {
  CGFloat x = self.padding.left;
  CGFloat y = self.padding.top;
  CGFloat width = bounds.size.width - self.padding.left - self.padding.right;
  CGFloat height = bounds.size.height - self.padding.top - self.padding.bottom;

  return CGRectMake(x, y, width, height);
}

- (CGRect)editingRectForBounds:(CGRect)bounds {
  return [self textRectForBounds:bounds];
}
@end
```
#### Method Callback Return Values
When implementing the focus method, component developers need to return a status code to the frontend to indicate whether the operation was successful. For instance, the frontend call might fail, in which case an appropriate error status should be returned so that the frontend can handle it in the `fail` callback.
Lynx Engine defines several common error codes, and developers can return the appropriate status code in the method callback:
```objc
enum LynxUIMethodErrorCode {
  kUIMethodSuccess = 0, // Succeeded
  kUIMethodUnknown, // Unknown error
  kUIMethodNodeNotFound, // Cannot find corresponding element
  kUIMethodMethodNotFound, // No corresponding method on this element
  kUIMethodParamInvalid, // Invalid method parameters
  kUIMethodSelectorNotSupported, // Selector not supported
};
```
### Custom Native element Implementation Process

The implementation of custom native elements involves several steps, including: declaring and registering the element, creating native views, handling styles and properties, event binding, etc. Let's take a simple custom input element `<explorer-input>` as an example to briefly introduce the implementation process of a custom element. The complete code can be viewed in [LynxExplorer](https://github.com/lynx-family/lynx/tree/develop/explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/input).

The complete implementation can be found in the [LynxExplorer/input module](https://github.com/lynx-family/lynx/tree/develop/explorer/android/lynx_explorer/src/main/java/com/lynx/explorer/input). You can compile and run the [LynxExplorer sample project](https://github.com/lynx-family/lynx/tree/develop/explorer/android) to preview element behavior in real-time.

### Integrate the LynxProcessor Module
Add the following to your module's build.gradle(.kts) file:

**Java**

```java
compileOnly project('org.lynxsdk.lynx:lynx-processor:{versionJson.LYNX_VERSION}')
annotationProcessor project('org.lynxsdk.lynx:lynx-processor:{versionJson.LYNX_VERSION}')
```


**Kotlin**

```kotlin
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.jetbrains.kotlin.android)
    id("kotlin-kapt")
}
//dependency
kapt('org.lynxsdk.lynx:lynx-processor:{versionJson.LYNX_VERSION}')
implementation("androidx.appcompat:appcompat:1.7.0")
```

### Declaring and Registering the Element
#### Declare the Custom Element
The declared custom element needs to inherit from `LynxUI`.

**Java**

```java title="LynxExplorerInput.java"

import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.ui.LynxUI;
import androidx.appcompat.widget.AppCompatEditText;


public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }
  //...

}

```


**Kotlin**

```kotlin title="LynxExplorerInput.kt"

import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.ui.LynxUI
import androidx.appcompat.widget.AppCompatEditText


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

   //...

}

```

#### Register the Custom Element
There are two ways to register elements: global registration and local registration.
##### Global Registration
Globally registered elements can be shared among multiple `LynxView` instances.

**Java**

```java

import com.lynx.tasm.LynxEnv;
import com.lynx.tasm.behavior.Behavior;

LynxEnv.inst().addBehavior(new Behavior("explorer-input"){
      @Override
      public LynxExplorerInput createUI(LynxContext context) {
        return new LynxExplorerInput(context);
      }
    });

```


**Kotlin**

```kotlin

import com.lynx.tasm.LynxEnv
import com.lynx.tasm.behavior.Behavior

LynxEnv.inst().addBehavior(object : Behavior("explorer-input") {
    override fun createUI(context: LynxContext): LynxExplorerInput {
        return LynxExplorerInput(context)
    }
})

```

##### Local Registration
Locally registered elements are only available for the current `LynxView` instance.

**Java**

```java

LynxViewBuilder lynxViewBuilder = new LynxViewBuilder();
lynxViewBuilder.addBehavior(new Behavior("explorer-input") {
      @Override
      public LynxExplorerInput createUI(LynxContext context) {
        return new LynxExplorerInput(context);
      }
    });

```


**Kotlin**

```kotlin

    val lynxViewBuilder = LynxViewBuilder()
    lynxViewBuilder.addBehavior(object : Behavior("explorer-input") {
      override fun createUI(context: LynxContext): LynxExplorerInput {
        return LynxExplorerInput(context)
      }
    })

```

Where `explorer-input"` corresponds to the tag name in the front-end DSL. When the Lynx Engine encounters this tag, it will look for the registered native element and create an instance.
### Create the Native `View` Instance
Each custom element needs to implement the `createView` method, which returns the corresponding native `View` instance.
Here’s the implementation for the `<explorer-input>` element:

**Java**

```java title="LynxExplorerInput.java" {12-17}

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }

}


```


**Kotlin**

```kotlin title="LynxExplorerInput.kt" {9-13}

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.ui.LynxUI


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }
}

```

### Handle Front-End Style and Property Updates
You can use the `@LynxProp` annotation to listen for property changes passed from the front-end and update the native view accordingly. For example, handling the `value` property of the `<explorer-input>` element:

**Java**

```java {4,13-18} title="LynxExplorerInput.java"

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }



}


```


**Kotlin**

```kotlin {4,15-20} title="LynxExplorerInput.kt"

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI

class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}

```

### Handle Layout Information (Optional)
#### Handle the Layout Result from the Lynx Engine
Usually, the Lynx Engine will automatically calculate and update the `View` layout information, so developers don’t need to handle this manually. However, in some special cases, such as when extra adjustments are needed for the `View`, you can retrieve the latest layout information in the `onLayoutUpdated` callback and apply custom logic.

**Java**

```java title="LynxExplorerInput.java" {13-21}

import android.content.Context;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    //...
    return view;
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

}


```


**Kotlin**

```kotlin title="LynxExplorerInput.kt" {10-17}

import android.content.Context
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      //...
    }
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}



```

### Event Binding
Event handling in native elements is usually done using the `@LynxEvent` annotation, which binds events between the front-end and native elements. For example, let’s implement a custom `onChange` event for the `<explorer-input>` element:

**Java**

```java title="LynxExplorerInput.java" {2-3,8-10,14-22,27-43}
import android.content.Context;
import android.text.Editable;
import android.text.TextWatcher;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;
import com.lynx.tasm.event.LynxCustomEvent;
import java.util.HashMap;
import java.util.Map;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  private void emitEvent(String name, Map<String, Object> value) {
    LynxCustomEvent detail = new LynxCustomEvent(getSign(), name);
    if (value != null) {
      for (Map.Entry<String, Object> entry : value.entrySet()) {
        detail.addDetail(entry.getKey(), entry.getValue());
      }
    }
    getLynxContext().getEventEmitter().sendCustomEvent(detail);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    view.addTextChangedListener(new TextWatcher() {
      @Override
      public void afterTextChanged(Editable s) {
        emitEvent("input", new HashMap<String, Object>() {
          {
            put("value", s.toString());
          }
        });
      }

      @Override
      public void beforeTextChanged(CharSequence s, int start, int count, int after) {}

      @Override
      public void onTextChanged(CharSequence s, int start, int before, int count) {
      }
    });
    return view;

  }

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }

}


```


**Kotlin**

```kotlin title="LynxExplorerInput.kt" {2-3,8,15-23,27-33}

import android.content.Context
import android.text.Editable
import android.text.TextWatcher
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.ui.LynxUI
import com.lynx.tasm.event.LynxCustomEvent


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      addTextChangedListener(object : TextWatcher {
        override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}

        override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}

        override fun afterTextChanged(s: Editable?) {
          emitEvent("input", mapOf("value" to (s?.toString() ?: "")))
        }
      })
    }
  }

  private fun emitEvent(name: String, value: Map<String, Any>?) {
    val detail = LynxCustomEvent(sign, name)
    value?.forEach { (key, v) ->
      detail.addDetail(key, v)
    }
    lynxContext.eventEmitter.sendCustomEvent(detail)
  }


  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}


```

### Front-End DSL Event Binding
On the front-end, you need to bind the relevant input events for the text box. With the following code, the front-end will listen for events sent by the client and process the input data as needed.
```jsx title="App.tsx"
const handleInput = (e) => {
  const currentValue = e.detail.value.trim();
  setInputValue(currentValue);
};

<explorer-input
  className="input-box"
  bindinput={handleInput}
  value={inputValue}
/>;
```
> **Note**: Front-end DSL uses `bindxxx` for event binding, such as `bindinput` for binding the `input` event.
### Supporting Direct Element Manipulation (Optional)
In some cases, the front-end may need to directly manipulate custom elements using imperative APIs. You can enable such operations on elements by using `@LynxUIMethod`.
#### Front-End Example Call
The following code demonstrates how to use the [SelectorQuery](/api/lynx-api/selector-query.md) API to call the `focus` method and make the `<explorer-input>` element gain focus:
```jsx title="App.tsx"
lynx
  .createSelectorQuery()
  .select('#input-id')
  .invoke({
    method: 'focus',
    params: {},
    success: function (res) {
      console.log('lynx', 'request focus success');
    },
    fail: function (res) {
      console.log('lynx', 'request focus fail');
    },
  })
  .exec();
```
#### Client-Side Implementation
On the client side, you need to add the `focus` method to your custom element using `@LynxUIMethod`, ensuring it can correctly handle the front-end call.

**Java**

```java title="LynxExplorerInput.java" {4,6-7,10-11,20-24,26-37}
import android.content.Context;
import android.text.Editable;
import android.text.TextWatcher;
import android.view.inputmethod.InputMethodManager;
import androidx.appcompat.widget.AppCompatEditText;
import com.lynx.react.bridge.Callback;
import com.lynx.react.bridge.ReadableMap;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.LynxUIMethod;
import com.lynx.tasm.behavior.LynxUIMethodConstants;
import com.lynx.tasm.behavior.ui.LynxUI;
import com.lynx.tasm.event.LynxCustomEvent;

import java.util.HashMap;
import java.util.Map;

public class LynxExplorerInput extends LynxUI<AppCompatEditText> {

  private boolean showSoftInput() {
    InputMethodManager imm = (InputMethodManager) getLynxContext().getSystemService(Context.INPUT_METHOD_SERVICE);
    return imm.showSoftInput(mView,
      InputMethodManager.SHOW_IMPLICIT, null);
  }

  @LynxUIMethod
  public void focus(ReadableMap params, Callback callback) {
    if (mView.requestFocus()) {
      if (showSoftInput()) {
        callback.invoke(LynxUIMethodConstants.SUCCESS);
      } else {
        callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to show keyboard");
      }
    } else {
      callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to focus");
    }
  }

  private void emitEvent(String name, Map<String, Object> value) {
    LynxCustomEvent detail = new LynxCustomEvent(getSign(), name);
    if (value != null) {
      for (Map.Entry<String, Object> entry : value.entrySet()) {
        detail.addDetail(entry.getKey(), entry.getValue());
      }
    }
    getLynxContext().getEventEmitter().sendCustomEvent(detail);
  }

  @Override
  protected AppCompatEditText createView(Context context) {
    AppCompatEditText view = new AppCompatEditText(context);
    view.addTextChangedListener(new TextWatcher() {
      @Override
      public void afterTextChanged(Editable s) {
        emitEvent("input", new HashMap<String, Object>() {
          {
            put("value", s.toString());
          }
        });
      }

      @Override
      public void beforeTextChanged(CharSequence s, int start, int count, int after) {
      }

      @Override
      public void onTextChanged(CharSequence s, int start, int before, int count) {
      }
    });
    return view;
  }

  public LynxExplorerInput(LynxContext context) {
    super(context);
  }

  @Override
  public void onLayoutUpdated() {
    super.onLayoutUpdated();
    int paddingTop = mPaddingTop + mBorderTopWidth;
    int paddingBottom = mPaddingBottom + mBorderBottomWidth;
    int paddingLeft = mPaddingLeft + mBorderLeftWidth;
    int paddingRight = mPaddingRight + mBorderRightWidth;
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom);
  }

  @LynxProp(name = "value")
  public void setValue(String value) {
    if (!value.equals(mView.getText().toString())) {
      mView.setText(value);
    }
  }
}

```


**Kotlin**

```kotlin title="LynxExplorerInput.kt" {4,6-7,18-21,23-34}

import android.content.Context
import android.text.Editable
import android.text.TextWatcher
import android.view.inputmethod.InputMethodManager
import androidx.appcompat.widget.AppCompatEditText
import com.lynx.react.bridge.Callback
import com.lynx.react.bridge.ReadableMap
import com.lynx.tasm.behavior.LynxContext
import com.lynx.tasm.behavior.LynxProp
import com.lynx.tasm.behavior.LynxUIMethod
import com.lynx.tasm.behavior.LynxUIMethodConstants
import com.lynx.tasm.behavior.ui.LynxUI
import com.lynx.tasm.event.LynxCustomEvent


class LynxExplorerInput(context: LynxContext) : LynxUI<AppCompatEditText>(context) {

  private fun showSoftInput(): Boolean {
    val imm = lynxContext.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager
    return imm.showSoftInput(mView, InputMethodManager.SHOW_IMPLICIT, null)
  }

  @LynxUIMethod
  fun focus(params: ReadableMap, callback: Callback) {
    if (mView.requestFocus()) {
      if (showSoftInput()) {
        callback.invoke(LynxUIMethodConstants.SUCCESS)
      } else {
        callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to show keyboard")
      }
    } else {
      callback.invoke(LynxUIMethodConstants.UNKNOWN, "fail to focus")
    }
  }

  override fun createView(context: Context): AppCompatEditText {
    return AppCompatEditText(context).apply {
      addTextChangedListener(object : TextWatcher {
        override fun beforeTextChanged(s: CharSequence?, start: Int, count: Int, after: Int) {}

        override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {}

        override fun afterTextChanged(s: Editable?) {
          emitEvent("input", mapOf("value" to (s?.toString() ?: "")))
        }
      })
    }
  }

  private fun emitEvent(name: String, value: Map<String, Any>?) {
    val detail = LynxCustomEvent(sign, name)
    value?.forEach { (key, v) ->
      detail.addDetail(key, v)
    }
    lynxContext.eventEmitter.sendCustomEvent(detail)
  }

  override fun onLayoutUpdated() {
    super.onLayoutUpdated()
    val paddingTop = mPaddingTop + mBorderTopWidth
    val paddingBottom = mPaddingBottom + mBorderBottomWidth
    val paddingLeft = mPaddingLeft + mBorderLeftWidth
    val paddingRight = mPaddingRight + mBorderRightWidth
    mView.setPadding(paddingLeft, paddingTop, paddingRight, paddingBottom)
  }

  @LynxProp(name = "value")
  fun setValue(value: String) {
    if (value != mView.text.toString()) {
      mView.setText(value)
    }
  }
}

```

#### Method Callback Return Values
When implementing the focus method, component developers need to return a status code to the frontend to indicate whether the operation was successful. For instance, the frontend call might fail, in which case an appropriate error status should be returned so that the frontend can handle it in the `fail` callback.
Lynx Engine predefines some common error codes, and the element developer can return the appropriate status code in the method callback:
```java
enum LynxUIMethodErrorCode {
  kUIMethodSuccess, // Succeeded
  kUIMethodUnknown, // Unknown error
  kUIMethodNodeNotFound, // Cannot find corresponding element
  kUIMethodMethodNotFound, // No corresponding method on this element
  kUIMethodParamInvalid, // Invalid method parameters
  kUIMethodSelectorNotSupported, // Selector not supported
}
```
The implementation of custom native elements can be broken down into several steps, including: declaring and registering elements, creating native views, handling styles and properties, event binding, etc. Let's take a simple custom input element `<explorer-input>` as an example to briefly introduce the implementation process of custom elements.

The complete implementation can be found in the [LynxExplorer/input module](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony/lynx_explorer/src/main/ets/component). You can compile and run the [LynxExplorer sample project](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) to preview element behavior in real-time.

### Declare and Register Elements
#### Declare Custom Elements
A declared custom element needs to inherit from `UIBase`. Below is the implementation of the `<explorer-input>` element:
```typescript title="LynxExplorerInput.ets" {20-23}
import { UIBase, EventHandlerArray, LynxUIMethodConstants } from '@lynx/lynx';

@ComponentV2
struct InputView {
  build() {
    Stack() {
      TextInput({})
    }
    .width('100%')
    .height('100%')
  }
}

@Builder
export function buildInput(ui: UIBase) {
  if (ui as LynxExplorerInput) {
    InputView();
  }
}

export class LynxExplorerInput extends UIBase {
  readonly builder: WrappedBuilder<[UIBase]> = wrapBuilder<[UIBase]>(buildInput);
}
```
#### Register Custom Element
Elements can be registered in two ways: globally and locally.
##### Global Registration
Globally registered elements can be shared across multiple `LynxView` instances.
```typescript {3,17}
import { BUILTIN_BEHAVIORS } from '@lynx/lynx/src/main/ets/tasm/behavior/Behavior';

export class CustomElement {
  private static initialized = false;

  static initialize() {
    if (CustomElement.initialized) {
      return;
    }
    BUILTIN_BEHAVIORS.set(
      'explorer-input',
      new Behavior(LynxExplorerInput, undefined),
    );
    CustomElement.initialized = true;
  }
}

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    CustomElement.initialize();
  }
}
```
##### Local Registration
Locally registered elements are only applicable to the current `LynxView` instance. Component names and their component instances are associated through `BehaviorRegistryMap`. `Behavior` defines the specific implementation of the component, including `UI Class` and `ShadowNode Class`.
```typescript
export class Behavior {
  uiClass?: Function;
  shadowNodeClass?: Function;
  customData?: Object;
  type?: NodeType;
}
```
Corresponding parameter description:
`uiClass`: The `UI` class corresponding to the component, which is used for rendering-related operations;
`shadowNodeClass`: Optional parameter, the `ShadowNode` class corresponding to the component， if implemented, it indicates that this node can provide measurement capabilities to the Lynx layout engine (such as `text` nodes);
`customData`: Optional parameter, some custom data;
`type`: Optional parameter, specifies the type of this component, generally not required. Currently, the following three types are defined:
`- COMMON` indicates having a `UI` node
`- VIRTUAL` indicates having only a `ShadowNode` without a `UI`
`- CUSTOM` indicates having both `UI` and `ShadowNode`
```typescript title="Lynx.ets"
import {
  Behavior,
  BehaviorRegistryMap,
} from '@lynx/lynx';
import { LynxExplorerInput } from '../component/LynxExplorerInput';

build() {
  LynxView({
    ...
    behaviors: new Map([['explorer-input', new Behavior(LynxExplorerInput, undefined)]]),
    ...
  }).height('100%')
  ...
}
```
Where `"input"` corresponds to the tag name in the front-end DSL. When Lynx Engine parses this tag, it will look for the registered native element and create an instance.
### Create Native `Component` Instance
Each custom element needs to implement the `Builder` method, which returns a corresponding native `Component` instance.
Here is the implementation for the `<explorer-input>` element:
```typescript title="LynxExplorerInput.ets" {31-37,43}
@ObservedV2
class InputParams {
  constructor(ui: LynxExplorerInput) {
    this.ui = ui;
  }

  @Trace inputText: string = '';
  @Trace placeholder: string = '';
  ui: LynxExplorerInput;
}

@ComponentV2
struct InputView {
  @Param @Require inputParams: InputParams;

  build() {
    Stack() {
      TextInput({
        controller: this.inputParams.ui.controller,
        text: this.inputParams.inputText,
        placeholder: this.inputParams.placeholder
      })
      .id(this.inputParams.ui.sign.toString())
      .style(TextContentStyle.DEFAULT)
      .focusable(true)
    }
    .width('100%')
    .height('100%')
  }
}

@Builder
export function buildInput(ui: UIBase) {
  if (ui as LynxExplorerInput) {
    InputView({ inputParams: (ui as LynxExplorerInput).inputParams });
  }
}

export class LynxExplorerInput extends UIBase {
  controller: TextInputController = new TextInputController();
  inputParams: InputParams = new InputParams(this)
  focused: boolean = false;
  readonly builder: WrappedBuilder<[UIBase]> = wrapBuilder<[UIBase]>(buildInput);
}
```
### Handle Front-End Style and Property Updates
You can inherit and override `update(props: Object, events?: EventHandlerArray[])` to listen for property changes passed from the front-end and update the native view. For example, handling the `value` property of the `<explorer-input>` element:
```typescript title="LynxExplorerInput.ets" {16}
export class LynxExplorerInput extends UIBase {
  controller: TextInputController = new TextInputController();
  inputParams: InputParams = new InputParams(this);
  focused: boolean = false;
  readonly builder: WrappedBuilder<[UIBase]> =
    wrapBuilder<[UIBase]>(buildInput);

  static PropSetter: Map<string, Function> = new Map([
    [
      'value',
      (ui: LynxExplorerInput, value: Object) => {
        ui.updateInputTextIfNecessary(value, true);
      },
    ],
    [
      'placeholder',
      (ui: LynxExplorerInput, value: Object) => {
        ui.inputParams.placeholder = value as string;
      },
    ],
    [
      'text-color',
      (ui: LynxExplorerInput, value: Object) => {
        ui.inputParams.fontColor = value as string;
      },
    ],
  ]);

  update(prop: Record<string, Object>, events?: EventHandlerArray[]): void {
    for (const entry of Object.entries(prop)) {
      LynxExplorerInput.PropSetter.get(entry[0])?.(this, entry[1]);
    }
  }
}
```
### Handle Layout Information (Optional)
#### Handle Lynx Engine Layout Results
Typically, Lynx Engine automatically calculates and updates the `Component` layout information, so developers do not need to manually handle this. However, in some special cases, such as when additional adjustments to the `Component` are required, you can obtain the latest layout information in the `layout` function and apply custom logic.
```typescript title="LynxExplorerInput.ets" {12}

export class LynxExplorerInput extends UIBase {
  controller: TextInputController = new TextInputController();
  inputParams: InputParams = new InputParams(this)
  focused: boolean = false;
  readonly builder: WrappedBuilder<[UIBase]> = wrapBuilder<[UIBase]>(buildInput);

  update(prop: Record<string, Object>, events?: EventHandlerArray[]): void {
    ...
  }

  layout(x: number, y: number, width: number, height: number, paddingLeft: number,
  paddingTop: number, paddingRight: number, paddingBottom: number, marginLeft: number, marginTop: number,
  marginRight: number, marginBottom: number, sticky?: number[]): void {
   ...
   // Generally, no special handling is required!
 }
}
```
### Custom `measure` (Optional)
:::warning
If a component's size needs to be determined by the component itself, you need to implement a `ShadowNode` to provide `Measure` capability and return it to the Lynx layout engine. The most typical example is the `text` component, whose size can be calculated from the text content.
:::
:::tip
Note: `ShadowNode` capabilities are only supported for leaf node Components!!
:::
#### Declare and Implement ShadowNode
The following is the implementation of `<LynxExplorerInputShadowNode>`, which needs to inherit from `ShadowNode`.
```typescript title="LynxExplorerInputShadowNode.ets"  {4,7,10}

import { ShadowNode, MeasureMode, IContext } from '@lynx/lynx';

export class LynxExplorerInputShadowNode extends ShadowNode {
  constructor(context: IContext) {
    super(context);
    this.setMeasureFunc(this.measure, null);
  }

  measure(width: number, widthMode: number, height: number, heightMode: number): [number, number, number] {
    let res = 0;
    ...
    return [width, res, 0];
  }
}
```
#### Handle Front-End Style and Property Updates
You can inherit and override `updateProps(props: Record<string, Object>)` method of `ShadowNode` to listen for property changes passed from the front-end and update the native view.
```typescript title="LynxExplorerInputShadowNode.ets"  {10}

import { ShadowNode, MeasureMode, IContext } from '@lynx/lynx';

export class LynxExplorerInputShadowNode extends ShadowNode {
  constructor(context: IContext) {
    super(context);
    this.setMeasureFunc(this.measure, null);
  }

  override updateProps(props: Record<string, Object>) {
    // Props-related processing
    if (prop['text-maxline'] !== undefined) {
      this.maxLength = prop['max-length'] as number;
    }
    ...
    // Call the super method
    super.update(props, events);
  }

  measure(width: number, widthMode: number, height: number, heightMode: number): [number, number, number] {
    let res = 0;
    ...
    return [width, res, 0];
  }
}
```
#### Override the `measure` method to return a custom size
You can inherit and override `measure` method of `ShadowNode` to return a custom size.
```typescript title="LynxExplorerInputShadowNode.ets"  {20}

import { ShadowNode, MeasureMode, IContext } from '@lynx/lynx';

export class LynxExplorerInputShadowNode extends ShadowNode {
  constructor(context: IContext) {
    super(context);
    this.setMeasureFunc(this.measure, null);
  }

  override updateProps(props: Record<string, Object>) {
    // Props-related processing
    if (prop['text-maxline'] !== undefined) {
      this.maxLength = prop['max-length'] as number;
    }
    ...
    // Call the super method
    super.update(props, events);
  }

  override measure(width: number, widthMode: number, height: number, heightMode: number): [number, number, number] {
    let res = height;
    if (heightMode === MeasureMode.DEFINITE) {
      res = height;
    } else if (heightMode === MeasureMode.AT_MOST) {
      res = Math.min(res, height);
    }
    return [width, res, 0];
  }
}
```
Parameter descriptions:
`width`: Width constraint;
`widthMode`: Width constraint mode, type is `MeasureMode`;
`height`: Height constraint;
`heightMode`: Height constraint mode, type is `MeasureMode`;
Return Value Description:
The return value is an array that needs to return 3 values: width, height, and Baseline (affects vertical alignment, default is 0)
#### Communication between `UI` and `ShadowNode`
Currently, only the measurement results of `ShadowNode` can be passed to `UI` for rendering. `ShadowNode` implements `setExtraDataFunc(func: () => Object): void`, where the `getExtraBundle` method returned to `UI` is provided
```typescript title="LynxExplorerInputShadowNode.ets"  {8,11}

import { ShadowNode, MeasureMode, IContext } from '@lynx/lynx';

export class LynxExplorerInputShadowNode extends ShadowNode {
  constructor(context: IContext) {
    super(context);
    this.setMeasureFunc(this.measure, null);
    this.setExtraDataFunc(this.getExtraBundle);
  }

  getExtraBundle(): Object {
    return "This is from extra bundle"
  }

  override updateProps(props: Record<string, Object>) {
    // Props-related processing
    if (prop['text-maxline'] !== undefined) {
      this.maxLength = prop['max-length'] as number;
    }
    ...
    // Call the super method
    super.update(props, events);
  }

  override measure(width: number, widthMode: number, height: number, heightMode: number): [number, number, number] {
    let res = height;
    if (heightMode === MeasureMode.DEFINITE) {
      res = height;
    } else if (heightMode === MeasureMode.AT_MOST) {
      res = Math.min(res, height);
    }
    return [width, res, 0];
  }
}
```
The corresponding `UI` inherits and overrides the `updateExtraData` method of `UIBase`, which allows it to receive the `ExtraBundle` passed by `ShadowNode` after the `Layout` process.
```typescript title="LynxExplorerInput.ets" {13}
import { UIBase, EventHandlerArray, LynxUIMethodConstants } from '@lynx/lynx';
...
@Builder
export function buildInput(ui: UIBase) {
  if (ui as LynxExplorerInput) {
    InputView();
  }
}

export class LynxExplorerInput extends UIBase {
  readonly builder: WrappedBuilder<[UIBase]> = wrapBuilder<[UIBase]>(buildInput);

override updateExtraData(data: Object): void {
...
}
}

```
### Handle Event Binding (Optional)
In some scenarios, the front-end may need to respond to events from custom elements. For example, when the user types in the input box, the front-end might need to capture and process the input data.
Here is an example of how to send a text input event from the `<explorer-input>` element to the front-end and how the front-end listens for the event.
#### Client-Side Event Sending
The client listens to text input callbacks from the native view, and when the text changes, it uses `sendCustomEvent(name: string, params: Object, paramName?: string)` method of `UIBase` to send the event to the front-end for handling.
```typescript title="LynxExplorerInput.ets" {16-25}

@ComponentV2
struct InputView {
  @Param @Require inputParams: InputParams;

  build() {
    Stack() {
      TextInput({
        controller: this.inputParams.ui.controller,
        text: this.inputParams.inputText,
        placeholder: this.inputParams.placeholder
      })
      .id(this.inputParams.ui.sign.toString())
      .style(TextContentStyle.DEFAULT)
      .focusable(true)
      .onChange((value: string) => {
        // update input text
        this.inputParams.inputText = value;
        this.inputParams.ui.sendCustomEvent('input', {
          value: value,
          cursor: this.inputParams.ui.controller.getCaretOffset()
            .index,
          compositing: false
        } as InputEvent, 'detail');
      })
    }
    .width('100%')
    .height('100%')
  }
}

export class LynxExplorerInput extends UIBase {
  controller: TextInputController = new TextInputController();
  inputParams: InputParams = new InputParams(this)
  focused: boolean = false;
  readonly builder: WrappedBuilder<[UIBase]> = wrapBuilder<[UIBase]>(buildInput);

  update(prop: Record<string, Object>, events?: EventHandlerArray[]): void {
    ...
  }

  layout(x: number, y: number, width: number, height: number, paddingLeft: number,
    paddingTop: number, paddingRight: number, paddingBottom: number, marginLeft: number, marginTop: number,
    marginRight: number, marginBottom: number, sticky?: number[]): void {
   ...
 }
}

```
#### Front-End DSL Event Binding
On the front-end, bind the corresponding input event to listen for and handle the text input data sent by the client.
```jsx title="App.tsx"
const handleInput = (e) => {
  const currentValue = e.detail.value.trim();
  setInputValue(currentValue);
};

<explorer-input
  className="input-box"
  bindinput={handleInput}
  value={inputValue}
/>;
```
> **Note**: The front-end DSL uses `bindxxx` for event binding, such as `bindinput` to bind the `input` event.
### Support Direct Element Manipulation (Optional)
In some cases, the front-end may need to directly manipulate custom elements via imperative APIs. You can make elements support such operations with `LYNX_UI_METHOD`.
#### Front-End Call Example
The following code shows how to use [SelectorQuery](/api/lynx-api/selector-query.md) to call the `focus` method and focus the `<explorer-input>` element:
```jsx title="App.tsx"
lynx
  .createSelectorQuery()
  .select('#input-id')
  .invoke({
    method: 'focus',
    params: {},
    success: function (res) {
      console.log('lynx', 'request focus success');
    },
    fail: function (res : {code: number, data: any}) {
      console.log('lynx', 'request focus fail');
    },
  })
  .exec();
```
#### Client-Side Implementation
On the client side, you need to override the `invokeMethod` of `UIBase` to add a `focus` method to the custom element to handle front-end call.
```typescript title="LynxExplorerInput.ets" {15}
export class LynxExplorerInput extends UIBase {
  controller: TextInputController = new TextInputController();
  inputParams: InputParams = new InputParams(this);
  focused: boolean = false;
  readonly builder: WrappedBuilder<[UIBase]> =
    wrapBuilder<[UIBase]>(buildInput);

  focus(callback: (code: number, res: Object) => void) {
    focusControl.requestFocus(this.sign.toString());
    this.focused = true;
    this.setFocusedUI();
    callback(LynxUIMethodConstants.SUCCESS, new Object());
  }

  override invokeMethod(
    method: string,
    params: Object,
    callback: (code: number, res: Object) => void,
  ): boolean {
    switch (method) {
      case 'focus':
        this.focus(callback);
        break;
      default:
        return false;
    }
    return true;
  }
}
```
#### Method Callback Return Values
When implementing the focus method, component developers need to return a status code to the frontend to indicate whether the operation was successful. For instance, the frontend call might fail, in which case an appropriate error status should be returned so that the frontend can handle it in the `fail` callback.
Lynx Engine defines several common error codes, and developers can return the appropriate status code in the method callback:
```objc
enum LynxUIMethodErrorCode {
  kUIMethodSuccess = 0, // Succeeded
  kUIMethodUnknown, // Unknown error
  kUIMethodNodeNotFound, // Cannot find corresponding element
  kUIMethodMethodNotFound, // No corresponding method on this element
  kUIMethodParamInvalid, // Invalid method parameters
  kUIMethodSelectorNotSupported, // Selector not supported
};
```
The way to customize elements in the web can directly refer to [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

## Use your Native Element

Once you have completed the development of a custom element, you can use it just like a built-in element. Below is a simple example of using an `<explorer-input>` element:

**This is an example below: native-element**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {33-39}
import { useState } from "@lynx-js/react";
import * as Lynx from "@lynx-js/types";

import "./App.css";

export function App() {
  const [inputValue, setInputValue] = useState("");

  const handleInput = (e: Lynx.BaseEvent<"input", { value: string }>) => {
    const currentValue = e.detail.value.trim();
    setInputValue(currentValue);
  };

  const requestFocus = () => {
    lynx
      .createSelectorQuery()
      .select("#input-id")
      .invoke({
        method: "focus",
        params: {},
        success: function(res) {
          console.log("lynx", "request focus success");
        },
        fail: function(res) {
          console.log("lynx", "request focus fail");
        },
      })
      .exec();
  };

  return (
    <view className="input-card-url">
      <text className="bold-text">Card URL</text>
      <explorer-input
        id="input-id"
        className="input-box"
        bindinput={handleInput}
        value={inputValue}
        placeholder="Enter Card URL"
      />
      <view className="connect-button" bindtap={requestFocus}>
        <text className="button-text">Go</text>
      </view>
    </view>
  );
}

```





---
url: /guide/autolink.md
---

# Autolink Native Libraries

Autolink is a mechanism that lets a Lynx app discover Elements, Native Modules, and Services provided by native libraries installed from `node_modules`, and register them automatically on Android and iOS during Lynx initialization. Each library is an npm package that declares its native entry points in `lynx.lib.json`; the host app enables the Autolink build integration once, and the generated registry replaces per-library manual wiring.

Autolink currently covers native Android and iOS libraries only. It does not generate Web or HarmonyOS integration code.

:::info Prerequisites

✅ Completed [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md)

✅ Familiar with [Native Modules](/guide/use-native-modules.md) and [Custom Native Element](/guide/custom-native-component.md)

:::

:::note Tooling Availability

Use Autolink tooling from the same Lynx release channel as your app. The package and plugin names are:

- npm: `create-lynx-library` and `@lynx-js/autolink-codegen` (`lynx-autolink-codegen` binary)
- Android: Gradle plugins `org.lynxsdk.library-settings` and `org.lynxsdk.library-build`
- iOS: Ruby gem `cocoapods-lynx-library`

If one of these packages cannot be resolved from your configured registries, your current Lynx SDK release does not include Native Autolink in that registry yet. Keep using the existing manual native registration flow until the matching release is available.

:::

## Host App Project Structure

Before enabling Autolink, make sure the host app has a project root that can install npm packages and expose the native app build entry points. A typical host app looks like this:

```text
lynx-app/
├── package.json
├── android/
│   ├── settings.gradle
│   └── app/
│       └── build.gradle
├── ios/
│   └── Podfile
└── src/
```

- `package.json` is required so the app can declare Autolink library packages as dependencies.
- For Android, the project needs a Gradle settings file, such as `settings.gradle` or `settings.gradle.kts`, and an Android application build file, such as `app/build.gradle` or `app/build.gradle.kts`.
- For iOS, the project needs a CocoaPods entry point, usually `Podfile`. If your team manages Ruby dependencies with Bundler, keep the `cocoapods-lynx-library` gem in `Gemfile`.

After you install dependencies, Autolink scans the installed npm packages for `lynx.lib.json` files at package roots. A lockfile such as `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock` is recommended for reproducible installs, but it is not required by Autolink.

## Set Up Autolink in an App

Set up Autolink once in the host app. After that, installed library packages can be discovered from `node_modules` and registered through the generated registry during Lynx initialization.

iOSAndroidEnable the settings plugin in `settings.gradle` so library Android projects can be discovered from `lynx.lib.json` and included:
```groovy
plugins {
  id 'org.lynxsdk.library-settings'
}
```
Enable the build plugin in the Android application project so the generated registry is added to the app and library projects are wired as dependencies:
```groovy
plugins {
  id 'com.android.application'
  id 'org.lynxsdk.library-build'
}
```
After Gradle sync/build, Autolink generates a fixed Android registry entry and adds it to the app sources. When the app initializes `LynxEnv`, that entry is loaded automatically, and Elements, Native Modules, and Services from installed libraries are registered app-wide. App code does not need any additional native initialization.
Install the `cocoapods-lynx-library` gem in your iOS build environment. Then add the CocoaPods plugin to the app's Podfile and call `use_lynx_library!` so podspecs from installed libraries and the generated registry pod are added during `pod install`:
```ruby
plugin 'cocoapods-lynx-library'

target 'LynxApp' do
  use_lynx_library!
end
```
After `pod install`, Autolink generates the registry pod and hooks it into the Lynx initialization flow. When the app creates `LynxConfig` or initializes `LynxEnv`, Elements, Native Modules, and Services from installed libraries are registered automatically. App code does not need to import generated files or add extra native initialization.

## Use a Library

After the app has set up Autolink, install the library package in your Lynx app:

```bash
npm install @example/lynx-button
```

Each library package exposes a `lynx.lib.json` manifest at the package root. Autolink scans installed npm packages for this file.

```json
{
  "platforms": {
    "android": {
      "packageName": "com.example.button",
      "sourceDir": "android"
    },
    "ios": {
      "sourceDir": "ios",
      "podspecPath": "ios/build.podspec"
    }
  }
}
```

For Android, `platforms.android.packageName` is required, and `sourceDir` defaults to `android`. For iOS, `sourceDir` defaults to `ios`, and `podspecPath` defaults to the first `.podspec` found under the iOS source directory.

After installing or updating a library package, sync/build the Android app and run `pod install` for iOS so the generated registry and native dependencies are refreshed. You do not need to add per-library manual registration code in the app.

## Library Package Role and Structure

An Autolink library package is an npm package that bundles the JavaScript facade, type declarations, native implementation, and Autolink manifest for one reusable capability. App teams install the package as a normal dependency; the Android Gradle plugins and iOS CocoaPods plugin read `lynx.lib.json` and link the native code into the host app.

A typical library package looks like this:

```text
lynx-button/
├── package.json
├── lynx.lib.json
├── types/
│   └── index.d.ts
├── src/
│   └── index.ts
├── generated/
│   └── ButtonModule.ts
├── android/
│   └── src/main/java/com/example/button/
│       ├── ButtonElement.java
│       ├── ButtonModule.java
│       ├── ButtonService.java
│       └── generated/ButtonModuleSpec.java
├── ios/
│   ├── build.podspec
│   └── src/
│       ├── ButtonElement.m
│       ├── ButtonModule.m
│       ├── ButtonService.m
│       └── generated/
│           ├── ButtonModuleSpec.h
│           └── ButtonModuleSpec.m
└── example/
```

- `package.json` makes the package installable from npm and usually provides the `codegen` script.
- `lynx.lib.json` is the Autolink contract. It tells the host app where Android and iOS source code lives.
- `types/index.d.ts` describes typed Native Module APIs, if the library exposes any. Codegen uses these declarations to create platform specs and the JavaScript facade.
- `src/index.ts` exports the JavaScript API that app code imports.
- `android/` and `ios/` contain native implementations and generated native specs.
- `example/` is a local app used by the library author to verify the package.

## Create a Library

Create a new library package interactively:

```bash
npm create lynx-library
```

For scripts and tests, the same scaffold can run without prompts:

```bash
npm create lynx-library -- \
  --dir ./lynx-button \
  --types native-module,element,service \
  --package-name @example/lynx-button \
  --android-package com.example.button \
  --module-name ButtonModule \
  --element-name x-button \
  --service-name ButtonService
```

The generated package includes:

- `package.json` with `"codegen": "lynx-autolink-codegen"`
- `lynx.lib.json` for Android and iOS Autolink discovery
- `types/index.d.ts` for typed Native Module declarations, when the library exposes Native Modules
- `src/index.ts` for the JavaScript facade
- `android/` and `ios/` native source folders
- `example/`, `tsconfig.json`, and `README.md`

Run codegen from the library root:

```bash
npm run codegen
```

`lynx-autolink-codegen` reads `lynx.lib.json`. For Native Modules, it scans `types/**/*.d.ts` for `@lynxmodule` declarations:

```ts
/** @lynxmodule */
export declare class ButtonModule {
  getLabel(id: string): string;
  setEnabled(id: string, enabled: boolean): void;
}
```

It generates:

- `generated/<ModuleName>.ts` for the JavaScript facade
- Android `<ModuleName>Spec.java`
- iOS `<ModuleName>Spec.h` and `<ModuleName>Spec.m`

The first version supports `void`, `string`, `number`, `boolean`, and nullable unions with `null`.

## Write Native APIs

Use the Autolink annotations and markers in library packages. Native Modules usually extend the spec generated by `lynx-autolink-codegen`; Elements and Services are discovered from their native markers.

iOSAndroidNative Module example:
```java
package com.example.button;

import com.example.button.generated.ButtonModuleSpec;
import com.lynx.jsbridge.LynxAutolinkNativeModule;
import com.lynx.jsbridge.LynxMethod;
import com.lynx.tasm.behavior.LynxContext;
import java.util.HashMap;
import java.util.Map;

@LynxAutolinkNativeModule(name = "ButtonModule")
public final class ButtonModule extends ButtonModuleSpec {
  private final Map<String, Boolean> enabledState = new HashMap<>();

  public ButtonModule(LynxContext context) {
    super(context);
  }

  @Override
  @LynxMethod
  public String getLabel(String id) {
    return "Button " + id;
  }

  @Override
  @LynxMethod
  public void setEnabled(String id, boolean enabled) {
    enabledState.put(id, enabled);
  }
}
```
Element example:
```java
package com.example.button;

import android.content.Context;
import android.view.Gravity;
import android.widget.TextView;
import com.lynx.tasm.behavior.LynxAutolinkElement;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

@LynxAutolinkElement(name = "x-button")
public final class ButtonElement extends LynxUI<TextView> {
  public ButtonElement(LynxContext context) {
    super(context);
  }

  @Override
  protected TextView createView(Context context) {
    TextView view = new TextView(context);
    view.setGravity(Gravity.CENTER);
    view.setText("x-button");
    return view;
  }

  @LynxProp(name = "text")
  public void setText(String text) {
    mView.setText(text == null ? "" : text);
  }
}
```
Service example:
```java
package com.example.button;

import android.content.Context;
import com.lynx.tasm.service.IServiceProvider;
import com.lynx.tasm.service.LynxAutolinkService;

@LynxAutolinkService
public final class ButtonService implements IServiceProvider {
  private Context appContext;

  @Override
  public Class<? extends IServiceProvider> getServiceClass() {
    return ButtonService.class;
  }

  @Override
  public void onInitialize(Context context) {
    appContext = context.getApplicationContext();
  }

  public void recordClick(String id) {
    // Send analytics or call platform capabilities here.
  }
}
```
Native Module example:
```objc
// ButtonModule.h
#import <Foundation/Foundation.h>
#import <Lynx/LynxModule.h>
#import "generated/ButtonModuleSpec.h"

NS_ASSUME_NONNULL_BEGIN

@LynxAutolinkNativeModule("ButtonModule")
@interface ButtonModule : NSObject <ButtonModuleSpec>

@end

NS_ASSUME_NONNULL_END

// ButtonModule.m
#import "ButtonModule.h"

@implementation ButtonModule {
  NSMutableDictionary<NSString *, NSNumber *> *_enabledState;
}

- (instancetype)init {
  self = [super init];
  if (self) {
    _enabledState = [NSMutableDictionary dictionary];
  }
  return self;
}

- (NSString *)getLabel:(NSString *)buttonId {
  return [NSString stringWithFormat:@"Button %@", buttonId];
}

- (void)setEnabled:(NSString *)buttonId enabled:(BOOL)enabled {
  _enabledState[buttonId] = @(enabled);
}

@end
```
Element example:
```objc
// ButtonElement.h
#import <UIKit/UIKit.h>
#import <Lynx/LynxUI.h>

NS_ASSUME_NONNULL_BEGIN

@interface ButtonElement : LynxUI<UILabel *>

@end

NS_ASSUME_NONNULL_END

// ButtonElement.m
#import "ButtonElement.h"
#import <Lynx/LynxPropsProcessor.h>

@LynxAutolinkUI("x-button")
@implementation ButtonElement

LYNX_PROP_SETTER("text", setText, NSString *) {
  self.view.text = value ?: @"";
}

- (UILabel *)createView {
  UILabel *label = [[UILabel alloc] init];
  label.textAlignment = NSTextAlignmentCenter;
  label.text = @"x-button";
  return label;
}

@end
```
Service example:
```objc
// ButtonService.h
#import <Foundation/Foundation.h>
#import <LynxServiceAPI/ServiceAPI.h>

NS_ASSUME_NONNULL_BEGIN

@protocol ButtonServiceProtocol <LynxServiceProtocol>

- (void)recordClick:(NSString *)buttonId;

@end

@interface ButtonService : NSObject <ButtonServiceProtocol>

@end

NS_ASSUME_NONNULL_END

// ButtonService.m
#import "ButtonService.h"

@LynxAutolinkService(ButtonService, ButtonServiceProtocol)
@implementation ButtonService

+ (instancetype)sharedInstance {
  static ButtonService *service;
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    service = [[ButtonService alloc] init];
  });
  return service;
}

- (void)recordClick:(NSString *)buttonId {
  // Send analytics or call platform capabilities here.
}

@end
```
## 


Autolink exposes the `LynxAutolink*` annotations and markers as the public authoring API for Lynx libraries.

For iOS packages that already use Lynx native registration macros, Autolink also scans existing `LYNX_LAZY_REGISTER_UI`, `LYNX_LAZY_REGISTER_SHADOW_NODE`, and `@LynxServiceRegister(...)` declarations so those packages can be linked without rewriting their native code.



---
url: /guide/embed-lynx-to-native.md
---

# Embedding LynxView into Native View

[LynxView](/guide/spec.md#lynxview) itself is a native view that can easily be used as a full-screen view, or be [embedded](/guide/spec.md#embedded) within a non-full-screen native view.

LynxView corresponds to the [Page](/api/elements/built-in/page.md) element. It only allows the client to set size constraints on LynxView, and you generally cannot directly modify the Page's style to set its size.

The client sets different size constraints on LynxView, which translates to setting size constraints on the Page.
The Lynx [layout engine](/guide/spec.md#starlight) uses these constraints to calculate the size of the Page node and all its child nodes.

## Constrain the size of LynxView \{#Constraining-LynxView}

### Constraint mode

iOSAndroidHarmonyOSYou should proactively set its size constraints, when creating a LynxView on iOS.

There are two ways to set size constraints for LynxView.

- Using `updateViewportWithPreferredLayoutWidth` and `setLayoutWidthMode、setLayoutHeightMode` to set fixed or flexible sizes.
- Using `lynxviewbuilder#frame` to set fixed size.

Supported constraint modes:

```objective-c
typedef NS_ENUM(NSInteger, LynxViewSizeMode) {
  LynxViewSizeModeUndefined = 0,
  LynxViewSizeModeExact,
  LynxViewSizeModeMax
};
```

- `LynxViewSizeModeUndefined`

  LynxView's size is determined by Page content, with no parent constraints.

- `LynxViewSizeModeExact`

  LynxView's size is fixed, same as the Page element's size.

- `LynxViewSizeModeMax`

  LynxView's maximum width or height.
### Get size constraints in the `onMeasure` method.

Android system provides an [onMeasure](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) for views, during which LynxView receives size constraints from its parent view.
Lynx will complete the layout of all elements and calculate the size of LynxView within the system's `onMeasure` function, and then set the correct value using [setMeasuredDimension](https://developer.android.com/reference/android/view/View#setMeasuredDimension\(int,%20int\)).

[View.MeasureSpec](https://developer.android.com/reference/android/view/View.MeasureSpec) values:

- `UNSPECIFIED`

  LynxView's size is determined by Page content, with no parent constraints.

- `EXACTLY`

  LynxView's size is fixed, same as the Page element's size.

- `AT_MOST`

  LynxView's maximum width or height.

When the content of the page needs to be re-layout, Lynx will call the system's [requestLayout](https://developer.android.com/reference/android/view/View#requestLayout\(\)), which triggers `onMeasure` to execute again.

### Preset Width and Height, Trigger Layout Early

When creating LynxView, you can preset its size constraints using `LynxViewBuilder#setPresetMeasuredSpec`, with parameters identical to`onMeasure`. This triggers layout during the [rendering pipeline](/guide/spec.md#pipeline) instead of waiting for `onMeasure`.

If a change in `measureSpec` is detected, the layout will re-trigger to ensure LynxView's size is correct.

For example, you can preset a fixed size of 400x200 with the following code:

```java
LynxViewBuilder viewBuilder = new LynxViewBuilder();
viewBuilder = viewBuilder.setPresetMeasuredSpec(View.MeasureSpec.makeMeasureSpec(400, View.MeasureSpec.EXACTLY),
        View.MeasureSpec.makeMeasureSpec(200, View.MeasureSpec.EXACTLY));

LynxView lynxview = viewBuilder.build(this);;
```
### Getting Size Constraints in `onMeasureSize`

The ArkUI framework passes node information and size ranges to custom components through [onMeasureSize](https://developer.huawei.com/consumer/en/doc/harmonyos-references/ts-custom-component-layout#onmeasuresize10\)) when determining component dimensions.

At this stage, the size constraints given to LynxView by the outer view can be obtained. Lynx will complete the layout of all nodes within the system's `onMeasureSize` function and calculate the size of LynxView

### LynxView with fixed size

iOSAndroidHarmonyOS### Use the `LynxViewBuilder#frame`

You can set the `frame` property size when creating LynxView, so the size of LynxView is fixed.

For example, if you want to fix the size of LynxView to 400x200, you can do it as follows:

```objective-c
   LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
       builder.frame =  CGRectMake(0, 0, 400, 200);
         ...
    }];
```

### Use `preferredLayoutWidth/preferredLayoutHeight` and `layoutWidthMode/layoutHeightMode`

For example:

```objective-c
_lynxView.layoutWidthMode = LynxViewSizeModeExact;
_lynxView.layoutHeightMode = LynxViewSizeModeExact;

_lynxView.preferredLayoutWidth = 400;
_lynxView.preferredLayoutHeight = 200;
```
As long as the outer container constraint for LynxView is `EXACTLY`, the size of LynxView will be fixed.

For example, if you want to set a 400x200 sized LynxView:

```java
//You can directly specify the size of LynxView
parentView.addView(lynxview, new ViewGroup.LayoutParams(400, 200));

//You can also fix the parent node's size and set it to MATCH_PARENT
parentView.addView(lynxview,
   new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.MATCH_PARENT));

```
You can give LynxView a fixed size.

For example, if you want to set a LynxView with a size of 400\*200:

```ts
// You can directly specify the size of LynxView
LynxView({}).width('400px').height('200px');
// You can also fix the parent node size and set percentage mode
LynxView({}).width('100%').height('100%');
```
## 


### LynxView with flexible size

iOSAndroidHarmonyOSIf you want LynxView to adapt its size based on its content, you can either avoid setting `LynxViewBuilder#frame`, or set `setLayoutWidth/HeightMode` to `LynxViewSizeModeUndefined` or `LynxViewSizeModeMax`.

```objective-c
_lynxView.layoutWidthMode = LynxViewSizeModeUndefined;
_lynxView.layoutHeightMode = LynxViewSizeModeUndefined;

//Alternatively, limit the width to 400 and the height to 750.
_lynxView.preferredLayoutWidth = 400;
_lynxView.preferredLayoutHeight = 750;
_lynxView.layoutWidthMode = LynxViewSizeModeMax;
_lynxView.layoutHeightMode = LynxViewSizeModeMax;
```
The layout constraints here are consistent with the Android views.

For example, setting the layout parameters for LynxView to [WRAP\_CONTENT](https://developer.android.com/reference/android/view/ViewGroup.LayoutParams#WRAP_CONTENT) will make LynxView size adapt to its content.

```java
parentView.addView(lynxview,
    new ViewGroup.LayoutParams(ViewGroup.LayoutParams.WRAP_CONTENT,ViewGroup.LayoutParams.WRAP_CONTENT));
```
You can set the `fitContentWidth` and `fitContentHeight` properties for LynxView to make its size adapt to the content's width and height:

```ts
LynxView({ fitContentWidth: true, fitContentHeight: true });
```



---
url: /guide/use-data-from-host-platform.md
---

# Using Data from Host Platform

Lynx allows the client to provide an initial set of data when the page loads, and then update this data at any time afterward.
This initial data is called `initData`.

## Provide and Update Data

:::note Prerequisites
You need to complete the instructions in [Integrate with existing applications](/guide/start/integrate-with-existing-apps.md) to ensure that your application has integrated Lynx and have a basic understanding of Lynx's Native API.
:::

When using [`LynxView.loadTemplate()`] to load a Bundle, you have the opportunity to pass in some data:

iOSAndroidHarmonyOS```objective-c {5}
LynxLoadMeta* meta = [LynxLoadMeta init];
// meta.url = @"";
// meta.binaryData = nil;
// meta.templateBundle = nil;
meta.initialData = __YOUR_DATA__;
// meta.loadOption = LynxLoadOptionDumpElement | LynxLoadOptionRecycleTemplateBundle;
[lynxView loadTemplate:meta];
```
```java {5}
LynxLoadMeta.Builder builder = new LynxLoadMeta.Builder();
// builder.setUrl();
// builder.setBinaryData();
// builder.setTemplateBundle();
builder.setInitialData(__YOUR_DATA__);
// builder.addLoadOption();
LynxLoadMeta meta = builder.build();
lynxView.loadTemplate(meta);
```
```typescript {4,11}
@Entry
@Component
struct Index {
  private metaData: MetaData = new MetaData(new TemplateData(__YOUR_DATA__));

  build() {
    Column() {
      LynxView({
        // url: this.url,
        // buffer: this.buffer,
        metadata: this.metaData,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```
## 


You can update this data later through [`LynxView.updateData()`] (or [`LynxContext.updateData()`] on HarmonyOS) when needed:

iOSAndroidHarmonyOS```objc {2}
LynxUpdateMeta* meta = [LynxUpdateMeta init];
meta.data = __YOUR_DATA__;
[lynxView updateData:meta];
```
```java {2}
LynxUpdateMeta.Builder builder = new LynxUpdateMeta.Builder();
builder.setUpdatedData(__YOUR_DATA__);
LynxUpdateMeta meta = builder.build();
lynxView.updateMetaData(meta);
```
```typescript {4-5,13-16}
@Entry
@Component
struct Index {
  private metaData: MetaData = new MetaData(new TemplateData(__YOUR_DATA__));
  private context?: LynxContext;

  build() {
    Column() {
      LynxView({
        // url: this.url,
        // buffer: this.buffer,
        metadata: this.metaData,
        onCreate: (context: LynxContext) => {
          this.context = context;
          this.context.updateMetaData(new MetaData(new TemplateData(__YOUR_DATA__)));
        }
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```

The data you pass in when loading and the data you pass in when updating can be used on the frontend. Below is how to use this data on the front end.

## Consuming the Data

On the frontend, you can retrieve `initData` by using [`useInitData()`].
When the client updates the data, these components will automatically re-render.

```tsx title="src/App.jsx"
import { useInitData } from '@lynx-js/react';

export function App() {
  const initData = useInitData();
  return (
    <view>
      <text>{initData.greeting}</text>
    </view>
  );
}
```

If you are using class components, you can use [`InitDataConsumer`].

```tsx
import { Component, InitDataProvider, InitDataConsumer } from '@lynx-js/react';

class C extends Component {
  render() {
    return (
      <InitDataConsumer>
        {(initData) => (
          <view>
            <text>{initData.greeting}</text>
          </view>
        )}
      </InitDataConsumer>
    );
  }
}
```

[`InitDataConsumer`] must be used as a child node of [`InitDataProvider`].

```tsx
<InitDataProvider>
  <view>
    <C />
  </view>
</InitDataProvider>
```

## Process Data Before Using It

While [`useInitData()`] gives you the `initData` from the client, it may not be in the format you expect.

Image you have the following disorganized `initData`:

- On Android or HarmonyOS:

  ```json
  {
    "pageTitle": "Hello Lynx"
  }
  ```

- But, on iOS:
  ```json
  {
    "page_title": "Hello Lynx"
  }
  ```

Your code may become less cleaner if you want to be compatible with these platforms:

```tsx {7}
import { useInitData } from '@lynx-js/react';

export function App() {
  const initData = useInitData();
  return (
    <view>
      <text>{initData.pageTitle || initData.page_title}</text>
    </view>
  );
}
```

The above scenarios are just examples, but Lynx do provide a way to process the `initData` before it is used, it is called `dataProcessor`.

### Using default `dataProcessor`

If you (or the client developer) did not specify a `processorName`, Lynx will use the `defaultDataProcessor` to process the `initData`.

:::info
See [`lynx.registerDataProcessors`] for more examples.
:::

```tsx title="src/index.tsx" {4-12}
import { root } from '@lynx-js/react';
import { App } from './App.js';

lynx.registerDataProcessors({
  defaultDataProcessor: function (rawInitData) {
    const { pageTitle, page_title, ...rest } = rawInitData;
    return {
      ...rest,
      pageTitle: pageTitle || page_title,
    };
  },
});
root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}
```

Then, in your component, you can use the `initData` directly:

```tsx title="src/App.jsx" {7}
import { useInitData } from '@lynx-js/react';

export function App() {
  const initData = useInitData();
  return (
    <view>
      <text>{initData.pageTitle}</text>
    </view>
  );
}
```

### Using named `dataProcessor`

You (or the client developer) can also specify a `processorName` when calling [`LynxView.updateData()`] (or [`LynxContext.updateData()`] on HarmonyOS):

iOSAndroidHarmonyOS```objc
LynxUpdateMeta *meta = [[LynxUpdateMeta alloc] init];

[lynxView updateData:meta];
```
```java
LynxUpdateMeta meta = new LynxUpdateMeta();

lynxView.updateMetaData(meta);
```
```typescript {4-5,14-16}
@Entry
@Component
struct Index {
  private metaData: MetaData = new MetaData(new TemplateData(__YOUR_DATA__));
  private context?: LynxContext;

  build() {
    Column() {
      LynxView({
        // url: this.url,
        // buffer: this.buffer,
        metadata: this.metaData,
        onCreate: (context: LynxContext) => {
          const templateData: TemplateData = new TemplateData('', 'someDataProcessor');
          this.context = context;
          this.context.updateMetaData(new MetaData(templateData));
        }
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```
## 


Accordingly, a named `dataProcessor` you defined will be called to process the `initData`, you can define multiple `dataProcessor`s with syntax below:

```tsx title="src/index.tsx" {5-14}
import { root } from '@lynx-js/react';
import { App } from './App.js';

lynx.registerDataProcessors({
  dataProcessors: {
    someDataProcessor: function (rawInitData) {
      // process rawInitData
      return processedInitData;
    },
    anotherDataProcessor: function (rawInitData) {
      // process rawInitData
      return processedInitData;
    },
  },
});
root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}
```

This allows you (or the client developer) to decide on the client which `dataProcessor` to use if the business logic requires it.

[`LynxView.loadTemplate()`]: /api/lynx-native-api/lynx-view/load-template.md

[`LynxView.updateData()`]: /api/lynx-native-api/lynx-view/update-meta-data.md

[`useInitData()`]: /api/react/Function.useInitData.md

[`InitDataConsumer`]: /api/react/Function.InitDataConsumer.md

[`InitDataProvider`]: /api/react/Function.InitDataProvider.md

[`lynx.registerdataprocessors`]: /api/react/Interface.Lynx.md#registerdataprocessors

[`LynxContext.updateData()`]: /api/lynx-native-api/lynx-context/update-meta-data.md



---
url: /guide/spec.md
---

# 





---
url: /guide/glossary.md
---


# Glossary

This glossary is intended to provide descriptive guidance about the meanings of technical terms commonly used in the context of Lynx development. For the latest consensus on a more formal definitions of these terms, please refer to the [Lynx Living Specification](/guide/spec.md).


## SDK

The Lynx [Software Development Kit (SDK)](https://en.wikipedia.org/wiki/Software_development_kit) is a collection of tools, libraries, and APIs that enable developers to build applications for Lynx. It encapsulates two distinct layers -- one native layer: the [Engine](#engine), and one scripting (or frontend) layer: the [Framework](#framework).

### Engine

The part of the SDK that is responsible for converting Lynx pages into pixels onther screen, and provides APIs that forms [the Lynx Platform](#the-lynx-platform).

It is written as a C++ core along with platform-specific layers written in platform native languages (e.g. Objective-C for iOS, Java/Kotlin for Android, etc.), ensuring high performance and access to underlying system resources, and needs to be integrated natively and shipped together with the host application.

### Framework

The part of the SDK that offers the runtime libraries and high-level UI programming model that enable Lynx application developers to write application logic and UI components. It is written in JavaScript and is loaded together with the application code on-demand from the file system or memory.

## The Lynx Platform

Similar to the [Web Platform](https://en.wikipedia.org/wiki/Web_platform), the **Lynx Platform** is the set of APIs and functionalities, e.g. [Elements](#element), [Events](#event), [Styles](#style), [Scripting Runtime Environment](#scripting-runtime-environment), etc., offered by the Lynx Engine to the scripting developers.

### Template

Template is the historical name of bundle of compiled code loaded by Lynx engine to power the execution of a Lynx page (or application).

We may investigate a better name for it in the future.

### Element

### Event

### Style

### Scripting Runtime Environment

Scripting is the process where developers program a script.

A **scripting runtime environment** is used to execute scripts with a scripting engine. In the context of Lynx, there are currently two types of scriping and so correspondingly, two types of scripting runtime environment.

### Background Thread

Background threads are threads that are not the main thread. They are used to execute background scripts.

### Main Thread

The **main thread**, or the "lynx main thread", is where Lynx processes user events and emit "paints". By default (the default threading model of Lynx), the Lynx engine uses a single thread to run main thread scripts, as well as to perform layout, paints, etc.. This means that long-running main thread scripts can block the thread, leading to an unresponsive page and a bad user experience.

### JS Thread

The word historically used to refer to the **background thread**. It is deprecated because it is not clear which thread it refers to as Lynx is now capable of running JavaScript on the main thread via **main thread scripts**.

### UI Thread

The thread corresponds to the physical thread regarded as the main thread of the underlying platform (OS). Similar to Web, the **main thread** of Lynx does not necessarily map directly to the UI thread, depending on Lynx's threading model.

### Lepus

### Lepus VM

### PrimJS VM



---
url: /guide/interaction/storage.md
---

# 




---
url: /guide/performance/analysis-performance/reactlynx-render-process.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# ReactLynx Rendering Pipeline

This article uses the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example to explain the ReactLynx rendering process in detail:

- Demonstrate the complete execution flow from the first-frame render to component updates in ReactLynx
- Understand the event distribution and timing relationships of each key stage in the Trace view
- Learn how to use the Trace tool to accurately locate performance bottlenecks in the rendering process

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/reactlynx-overview-trace.png)
## First Screen Rendering

[First Screen Rendering](/guide/spec.md#first-screen-rendering-or-fsr) includes stages such as downloading the [Bundle](/guide/spec.md#lynx-bundle-or-bundle), loading the bundle, and drawing.

### Download Bundle

After the page starts, it first [downloads](/guide/spec.md#load) the Bundle。

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/download_lynx_bundle_trace.png)
### Load Bundle

Once the bundle is downloaded, it enters the loading stage.

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/first-screen-render-pipeline-in-trace-latest.png)
#### Parse Bundle

During the bundle loading stage, the content of the bundle—such as CSS stylesheets, scripts, and page configurations—is first [parsed](/guide/spec.md#parse)

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/decode-lynx-bundle-trace.png)
#### Execute MTS

After parsing the bundle, the [Engine thread](/guide/spec.md#engine-thread-historically-known-as-tasm-thread) virtual machine executes the [MTS](/guide/spec.md#main-thread-script-or-mts).

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/execute-main-scripts-latest.png)
#### Execute BTS

Meanwhile, the [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread) virtual machine loads, parses, and executes the [BTS](/guide/spec.md#background-thread-script-or-bts).

![Execute Background Script](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/backgound-script-execute-latest.png)
During BTS execution, you can observe the creation process of components.

![Background Thread Create Component](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/background-thread-create-component-thread-latest.png)
:::tip
The background thread does not block the Engine thread’s Element tree construction, resolve, layout, and other flows.
:::

#### Construct the Element Tree

During the [Element tree](/guide/spec.md#element-tree) construction stage, the [Element PAPI](/guide/spec.md#element-papi) is called to convert the page structure into an Element tree.

Taking the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example, the first frame creates 1 page element, 6 view elements, 2 image elements, and 5 text elements.

```html
<page>
  <view className="Background" />
  <view className="App">
    <view className="Banner">
      <view className="Logo" bindtap={onTap}>
        <image src={lynxLogo} className="Logo--lynx" />
      </view>
      <text className="Title">React</text>
      <text className="Subtitle">on Lynx</text>
  </view>
  <view className="Content">
    <image src={arrow} className="Arrow" />
    <text className="Description">Tap the logo and have fun!</text>
    <text className="Hint">
      Edit<text style={{ fontStyle: "italic" }}>{" src/App.tsx "}</text>
      to see updates!
    </text>
  </view>
  <view style={{ flex: 1 }}></view>
  </view>
</page>
```

In Trace, you can observe the complete process of creating Elements and setting their Events, Classes, and other attributes.

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/construct-element-tree-trace.jpeg)
#### Resolve

During the [Resolve](/guide/spec.md#resolve) stage, the Element’s className, inline styles, and other attributes are parsed to determine the Element’s style, and the [layout node tree](/guide/spec.md#layout-node-tree) is created.
As shown below, the Resolve stage covers the complete execution flow and the parsing of styles for `<view className="Background" />`.

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/resolve-in-trace.png)
#### Layout

The [layout](/guide/spec.md#layout) stage measures and lays out the layout nodes. The following example shows the layout process of the `<text>Tap the logo and have fun!</text>` node.

![Trace Render Pipeline](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/layout-in-trace.png)
#### Flush

After the layout is complete, [platform UIs](/guide/spec.md#platform-ui) are created, with various attributes and layout information set.

![Create Platform UI](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/create-platform-ui-trace.png)
:::tip

Element nodes containing only layout attributes will not create platform UI nodes.
[Nested text](/api/elements/built-in/text.md#嵌套text) will be merged with their parent text node to create a single platform UI.

:::

In the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project, the following nodes create platform UI on the first screen:

```html
<page>
  <view className="Background" />
  <view className="Banner">
    <view className="Logo" bindtap="{onTap}">
      <image src="{lynxLogo}" className="Logo--lynx" />}
    </view>
  </view>
  <text className="Title">React</text>
  <text className="Subtitle">on Lynx</text>
  <image src="{arrow}" className="Arrow" />
  <text className="Description">Tap the logo and have fun!</text>
  <text className="Hint"> Edit " src/App.tsx " to see updates!</text>
</page>
```

### Draw

When the system’s rendering callback occurs, the platform UI completes its first-screen drawing.

![Draw Platform UI](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/draw-in-trace.png)
## Update Rendering Process

Taking the [hello-world](https://github.com/lynx-family/lynx-examples/blob/main/examples/hello-world/) project as an example, clicking the Logo triggers an update, which demonstrates the component update rendering flow.

![Draw Platform UI](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/reactlynx-re-rendering-trace.png)
### Trigger the Click Event

After clicking the Logo, LynxView processes the [click event](/guide/spec.md#event-propagation) and sends the event to the background thread, triggering the corresponding node’s click [event handler](/guide/spec.md#event-handler).

To better observe the execution timing of the click event callback in Trace, you can use the [Trace API](/guide/performance/analysis-performance/trace-api.md) to add custom Trace events.

```javascript {3,5}
const onTap = useCallback(() => {
  'background only';
  lynx.performance.profileStart('onTap');
  setAlterLogo(!alterLogo);
  lynx.performance.profileEnd();
}, [alterLogo]);
```

![Touch Event Process](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/touch-event-trace.png)
The App component updates the state of alterLogo in the click event callback.

### Diff Component Diff

After updating the component state, the component diff process is triggered, and the image node changes:

```html
<view className="Logo" bindtap="{onTap}">
  + <image src="{reactLynxLogo}" className="Logo--react" /> - -
  <image src="{lynxLogo}" className="Logo--lynx" />
</view>
```

The following image shows the diff process for the App component:

![Component Diff Process](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/component-diff-process.png)
### Component Update Synchronization

After the component diff is complete, the update information is synchronized to the Engine thread, driving subsequent UI changes. In Trace, clicking the `CallLepusMethod` event allows you to see the UI update process after component diff is complete.

![Sync Diff To UI Thread](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/sync-change-to-ui-thread-latest.png)
### UI Update

The Engine thread shows the update process of the Element tree. As shown below, the Element tree removes one element and adds a new image element.

![Sync Diff To UI Thread](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/element-update-process.png)
After the Element update is complete, the layout and UI are updated again.

![Sync Diff To UI Thread](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ui-update-process.png)
### Trigger useEffect Callback

After the Element tree update is complete, the background thread is notified to trigger the component’s useEffect callback.

To better observe the execution timing of the useEffect callback in Trace, use the [Trace API](/guide/performance/analysis-performance/trace-api.md) to add custom trace events.

```javascript {6-8}
useEffect(() => {
  console.info('Hello, ReactLynx');
}, []);

useEffect(() => {
  lynx.performance.profileMark('useEffect', {
    args: { alterLogo: `${alterLogo}` },
  });
}, [alterLogo]);
```

![useEffect Callback](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/useeffect-callback-trace.png)


---
url: /guide/performance/analysis-performance/trace-api.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Using Trace API

Trace allows you to add custom trace events to your code, helping you track specific operations or logic flows. This is useful for profiling custom business logic, measuring durations, or marking important points in your app.

- For Frontend Developers: You might want to measure the execution timing of a hook or component lifecycle method to understand rendering delays or side effect durations. For example, tracking how long a `useEffect` hook takes;
- For Android/iOS Developers: You may want to profile how long it takes to load a Lynx Bundle, parse resources, or execute a specific NativeModule call. Custom trace events help you pinpoint slow operations within complex workflows;

By adding custom trace events, you transform opaque code sections into visible, measurable segments in Trace’s timeline, enabling precise performance tuning.

## How to Use

iOSAndroidHarmonyOSReactLynx### Slice Events
![Slice Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png)- Definition: Slice events have both a start and end timestamp, representing a duration.
- Nesting: On the same thread, slice events can be nested like a call stack.
  - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
  - Important: Child events must always end before their parent ends (i.e., B must end before A).
- Use case: Suitable for profiling code sections where execution time matters.
```objc {3,5,10,12}
// Basic usage
- (void)measure {
  [LynxTraceEvent beginSection:@"render" withName:@"measure"]; // 'measure' slice start
  // ... your code ...
  [LynxTraceEvent endSection:@"render" withName:@"measure"]; // 'measure' slice end
}

// With custom arguments
- (void)draw {
  [LynxTraceEvent beginSection:@"render" withName:@"draw-image" debugInfo:@{@"component": @"Image", @"size": @"large"}];
  // ... your code ...
  [LynxTraceEvent endSection:@"render" withName:@"draw-image"];
}
```
### Instant Events
![Instant Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png)- Definition: Instant events have only a single timestamp and no duration. - Use
  case: Suitable for marking significant moments or points in your code (such as
  state changes, cross-thread/async boundaries, etc.).
```objc {4,11}
// Basic usage
- (void)requestBegin {
  // ...
  [LynxTraceEvent instant:@"network" withName:@"request-begin"];
  // ...
}

// With custom arguments
- (void)requestFinished {
  // ...
  [LynxTraceEvent instant:@"network" withName:@"request-finished" debugInfo:@{@"url": @"https://example.com", @"method": @"GET"}];
  // ...
}
```
## Best Practices
### Begin/End Must Match on the Same Thread
- Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
- Do not let exceptions or early returns prevent `endSection` from being called.
#### Bad Examples
```objc {6-7,13-14,19-20,23}
// Exception causes endSection not to be called
- (void)measureWithError:(BOOL)shouldThrow {
  [LynxTraceEvent beginSection:@"measure"];
  // ...
  @throw [NSException exceptionWithName:@"TestException" reason:@"Error occurred" userInfo:nil];
  // endSection will not be called due to exception
  [LynxTraceEvent endSection:@"measure"];
}

// Early return causes endSection not to be called
- (void)measureWithFastExit:(BOOL)fastExit {
  [LynxTraceEvent beginSection:@"measure"];
  // Early return, endSection not called
  if (fastExit) return;
  // ...
  [LynxTraceEvent endSection:@"measure"];
}

// Cross-thread begin/end mismatch
[LynxTraceEvent beginSection:@"background-task"];
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
  // ...
  [LynxTraceEvent endSection:@"background-task"]; // Error: not same thread
});
```
#### Good Examples
```objc {7-10,16-18,25-26,28}
- (void)measureWithError:(BOOL)shouldThrow {
  @try {
    [LynxTraceEvent beginSection:@"measure"];
    // ...
    @throw [NSException exceptionWithName:@"TestException" reason:@"Error occurred" userInfo:nil];
  }
  @finally {
    // Exception safe: ensure endSection is always called
    [LynxTraceEvent endSection:@"measure"];
  }
}

- (void)measureWithFastExit:(BOOL)fastExit {
  [LynxTraceEvent beginSection:@"measure"];
  if (fastExit) {
    // Early return safe
    [LynxTraceEvent endSection:@"measure"];
    return;
  }
  // ...
  [LynxTraceEvent endSection:@"measure"];
}

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
  // Thread safe: begin/end on the same thread
  [LynxTraceEvent beginSection:@"background-task"];
  // ...
  [LynxTraceEvent endSection:@"background-task"];
});
```
### Do Not Use Slice Events Across Async Boundaries
- Do not use `beginSection`/`endSection` across asynchronous boundaries like timers or callbacks.
- Slice events require start and end to be in the same synchronous context.
- Use Instant events if you need to trace both sides of an async boundary.
#### Bad Examples
```objc {2,5,9,11}
// Timer/callback
[LynxTraceEvent beginSection:@"async-function"];
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, time), dispatch_get_main_queue(), ^{
    // ...
    [LynxTraceEvent endSection:@"async-function"];
});

// Async task
[LynxTraceEvent beginSection:@"await-task"];
[someAsyncFunction waitUntilFinished];
[LynxTraceEvent endSection:@"await-task"];
```
#### Good Examples
```objc {3,5,9,11}
// Timer/callback: use begin/end inside callback
dispatch_after(dispatch_time(DISPATCH_TIME_NOW, time), dispatch_get_main_queue(), ^{
    [LynxTraceEvent beginSection:@"async-function"];
    // ...
    [LynxTraceEvent endSection:@"async-function"];
});

// Async task: use instant events
[LynxTraceEvent instant:@"async-task" withName:@"start"];
[someAsyncFunction waitUntilFinished];
[LynxTraceEvent instant:@"async-task" withName:@"end"];
```
### Slice Events
![Slice Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png)- Definition: Slice events have both a start and end timestamp, representing a duration.
- Nesting: On the same thread, slice events can be nested like a call stack.
  - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
  - Important: Child events must always end before their parent ends (i.e., B must end before A).
- Use case: Suitable for profiling code sections where execution time matters.
```java {3,5,10-13,15}
// Basic usage
void measure() {
  TraceEvent.beginSection("render", "measure");
  // ... your code ...
  TraceEvent.endSection("render", "measure");
}

// With custom arguments
void draw() {
  Map<String, String> args = new HashMap<>();
  args.put("component", "Image");
  args.put("size", "large");
  TraceEvent.beginSection("render", "draw-image", args);
  // ... your code ...
  TraceEvent.endSection("render", "draw-image");
}
```
### Instant Events
![Instant Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png)- Definition: Instant events have only a single timestamp and no duration.
- Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).
```java {4,11-14}
// Basic usage
void requestBegin() {
  // ...
  TraceEvent.instant("network", "request-begin");
  // ...
}

// With custom arguments
void requestFinished() {
  // ...
  Map<String, String> args = new HashMap<>();
  args.put("url", "https://example.com");
  args.put("method", "GET");
  TraceEvent.instant("network", "request-finished", args);
  //...
}
```
## Best Practices
### Begin/End Must Match on the Same Thread
- Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
- Do not let exceptions or early returns prevent `endSection` from being called.
#### Bad Examples
```java {5-6,11-12,17-18,21}
public void measure() throws Exception {
  TraceEvent.beginSection("measure");
  // ...
  exceptionFunction(); // May throw exception
  // endSection not called due to exception
  TraceEvent.endSection("measure");
}

public void measure(boolean fastExit) {
  TraceEvent.beginSection("measure");
  // Early return causes endSection not to be called
  if (fastExit) return;
  // ...
  TraceEvent.endSection("measure");
}

// Cross-thread: begin/end not in the same thread
TraceEvent.beginSection("background-task");
new Thread(() -> {
  // ...
  TraceEvent.endSection("background-task");
}).start();
```
#### Good Examples
```java {6-9,15-17,24-25,27}
public void measure() throws Exception {
  try {
    TraceEvent.beginSection("measure");
    // ...
    exceptionFunction();
  } finally {
    // Exception safe
    TraceEvent.endSection("measure");
  }
}

public void measure() {
  TraceEvent.beginSection("measure");
  if (fastExit) {
    // Early return safe
    TraceEvent.endSection("measure");
    return;
  }
  // ...
  TraceEvent.endSection("measure");
}

new Thread(() -> {
  // Thread safe: begin/end in the same thread
  TraceEvent.beginSection("background-task");
  // ...
  TraceEvent.endSection("background-task");
}).start();
```
### Do Not Use Slice Events Across Async Boundaries
- Do not use `beginSection`/`endSection` across asynchronous boundaries like timers or callbacks.
- Slice events require start and end to be in the same synchronous context.
- Use Instant events if you need to trace both sides of an async boundary.
#### Bad Examples
```java {2,5,9,11}
// Timer/callback
TraceEvent.beginSection("async-function");
new Handler().postDelayed(() -> {
  // ...
  TraceEvent.endSection("async-function");
}, 3000);

// Async task
TraceEvent.beginSection("await-task");
someAsyncFunction().get(); // Assume this is async wait
TraceEvent.endSection("await-task");
```
#### Good Examples
```java {3,5,9,11}
// Timer/callback: use begin/end inside callback
new Handler().postDelayed(() -> {
  TraceEvent.beginSection("async-function");
  // ...
  TraceEvent.endSection("async-function");
}, 3000);

// Async task: use instant events
TraceEvent.instant("async-task", "async-task-start");
someAsyncFunction().get();
TraceEvent.instant("async-task", "async-task-end");
```
### Slice Events
![Slice Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png)- Definition: Slice events have both a start and end timestamp, representing a duration.
- Nesting: On the same thread, slice events can be nested like a call stack.
  - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
  - Important: Child events must always end before their parent ends (i.e., B must end before A).
- Use case: Suitable for profiling code sections where execution time matters.
```javascript {3,5,10-14,16}
// Basic usage
function measure() {
  TraceEvent.beginSection(TraceCategory.Other, "measure");
  // ... your code ...
  TraceEvent.endSection(TraceCategory.Other, "measure");
}

// With custom arguments
function draw() {
  const args: Record<string, string> = {
    "component": "Image",
    "size": "large"
  }
  TraceEvent.beginSection(TraceCategory.Other, "draw-image", args);
  // ... your code ...
  TraceEvent.endSection(TraceCategory.Other, "draw-image");
}
```
### Instant Events
![Instant Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png)- Definition: Instant events have only a single timestamp and no duration.
- Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).
```javascript {4,11-15}
// Basic usage
function requestBegin() {
  // ...
  TraceEvent.instant(TraceCategory.Other, "request-begin")
  // ...
}

// With custom arguments
function requestFinished() {
  // ...
  const args: Record<string, string> = {
    "url": "https://example.com",
    "method": "GET"
  }
  TraceEvent.instant(TraceCategory.Other, "request-finished", args);
  //...
}
```
## Best Practices
### Begin/End Must Match on the Same Thread
- Every `beginSection` must have a corresponding `endSection`, and both calls must occur on the same thread.
- Do not let exceptions or early returns prevent `endSection` from being called.
#### Bad Examples
```javascript {5-6,11-12,17-18,21}
function measure() {
  TraceEvent.beginSection(TraceCategory.Other, 'measure');
  // ...
  throw new Error('Error occurred');
  // profileEnd not called due to exception
  TraceEvent.endSection(TraceCategory.Other, 'measure');
}

function measureWithFastExit(fastExit) {
  TraceEvent.beginSection(TraceCategory.Other, 'measure');
  // Early return causes profileEnd not to be called
  if (fastExit) return;
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'measure');
}

// Cross-async/thread begin/end mismatch
TraceEvent.beginSection(TraceCategory.Other, 'background-task');
setTimeout(() => {
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'background-task');
}, 1000);
```
#### Good Examples
```javascript {6-9,15-17,24-25,27}
function measure(shouldThrow) {
  try {
    TraceEvent.beginSection(TraceCategory.Other, 'measure');
    // ...
    throw new Error('Error occurred');
  } finally {
    // Exception safe: ensure profileEnd is always called
    TraceEvent.endSection(TraceCategory.Other, 'measure');
  }
}

function measureWithFastExit(fastExit) {
  TraceEvent.beginSection(TraceCategory.Other, 'measure');
  if (fastExit) {
    // Early return safe
    TraceEvent.endSection(TraceCategory.Other, 'measure');
    return;
  }
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'measure');
}

setTimeout(() => {
  // Thread safe: begin/end in the same execution context
  TraceEvent.beginSection(TraceCategory.Other, 'background-task');
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'background-task');
}, 0);
```
### Do Not Use Slice Events Across Async Boundaries
- Do not use `beginSection`/`endSection` across asynchronous boundaries such as timers, callbacks, or `await`/`Promise`.
- Slice events require start and end to be in the same synchronous context.
- Use Instant events if you need to trace both sides of an async boundary.
#### Incorrect Examples
```javascript {2,5,9,11}
// Timer/callback
TraceEvent.beginSection(TraceCategory.Other, 'async function');
setTimeout(() => {
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'async function');
}, 3000);

// await/promise
TraceEvent.beginSection(TraceCategory.Other, 'await-task');
await someAsyncFunc();
TraceEvent.endSection(TraceCategory.Other, 'await-task');
```
#### Correct Examples
```javascript {3,5,9,11}
// Timer/callback: use begin/end inside the callback
setTimeout(() => {
  TraceEvent.beginSection(TraceCategory.Other, 'async function');
  // ...
  TraceEvent.endSection(TraceCategory.Other, 'async function');
}, 3000);

// await/promise: use instant trace events
TraceEvent.instant(TraceCategory.Other, 'await-task:begin');
await someAsyncFunc();
TraceEvent.instant(TraceCategory.Other, 'await-task:end');
```
### Slice Events
![Slice Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/slice-event.png)- Definition: Slice events have both a start and end timestamp, representing a duration.
- Nesting: On the same thread, slice events can be nested like a call stack.
  - For example, if event B starts after event A but before A ends, B is considered a child of A and will be displayed nested under A in the Trace UI.
  - Important: Child events must always end before their parent ends (i.e., B must end before A).
- Use case: Suitable for profiling code sections where execution time matters.
```javascript {3,5,10-12,14}
// Basic usage
function handleClick() {
  lynx.performance.profileStart('handle-click');
  // ... your code ...
  lynx.performance.profileEnd();
}

// With custom arguments
useEffect(() => {
  lynx.performance.profileStart('useEffect', {
    args: { count },
  });
  // ... your code ...
  lynx.performance.profileEnd();
}, [count]);
```
### Instant Events
![Instant Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/instant-event.png)- Definition: Instant events have only a single timestamp and no duration.
- Use case: Suitable for marking significant moments or points in your code (such as state changes, cross-thread/async boundaries, etc.).
```javascript {3,6-8}
function fetchData() {
  // Basic usage
  lynx.performance.profileMark('fetch-data-begin');
  fetch(url).then((res) => {
    // With custom arguments
    lynx.performance.profileMark('fetch-data-end', {
      args: { url: 'https://example.com', method: 'GET' },
    });
  });
}
```
#### Flow Events
![Flow Events](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/flow-event.png)- Description: Flows are used to link two (or more) logically related events (Slice or Instant) that may occur on different threads or at different times.
- Visualization: In the Trace UI, flows are displayed as arrows connecting related events. When you select one event, the arrow highlights its related events.
- Use case: Flows are especially useful for tracking the lifecycle of asynchronous tasks, request/response pairs, or any operation spanning multiple phases or contexts.
```javascript {1-2,7}
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileMark('user-action-begin', { flowId });

// ...later, in an async callback
setTimeout(() => {
  // ...
  lynx.performance.profileMark('user-action-end', { flowId });
}, 1000);
```
## Best Practices
### Begin/End Must Match on the Same Thread
- Every `profileStart` must have a corresponding `profileEnd`, and both calls must occur on the same thread.
- Do not let exceptions or early returns prevent `profileEnd` from being called.
#### Bad Examples
```javascript {5-6,11-12,17-18,21}
function measure() {
  lynx.performance.profileStart('measure');
  // ...
  throw new Error('Error occurred');
  // profileEnd not called due to exception
  lynx.performance.profileEnd();
}

function measureWithFastExit(fastExit) {
  lynx.performance.profileStart('measure');
  // Early return causes profileEnd not to be called
  if (fastExit) return;
  // ...
  lynx.performance.profileEnd();
}

// Cross-async/thread begin/end mismatch
lynx.performance.profileStart('background-task');
setTimeout(() => {
  // ...
  lynx.performance.profileEnd();
}, 1000);
```
#### Good Examples
```javascript {6-9,15-17,24-25,27}
function measure(shouldThrow) {
  try {
    lynx.performance.profileStart('measure');
    // ...
    throw new Error('Error occurred');
  } finally {
    // Exception safe: ensure profileEnd is always called
    lynx.performance.profileEnd();
  }
}

function measureWithFastExit(fastExit) {
  lynx.performance.profileStart('measure');
  if (fastExit) {
    // Early return safe
    lynx.performance.profileEnd();
    return;
  }
  // ...
  lynx.performance.profileEnd();
}

setTimeout(() => {
  // Thread safe: begin/end in the same execution context
  lynx.performance.profileStart('background-task');
  // ...
  lynx.performance.profileEnd();
}, 0);
```
### Do Not Use Slice Events Across Async Boundaries
- Do not use `profileStart`/`profileEnd` across asynchronous boundaries such as timers, callbacks, or `await`/`Promise`.
- Slice events require start and end to be in the same synchronous context.
- Use Instant events if you need to trace both sides of an async boundary.
#### Incorrect Examples
```javascript {2,5,9,11}
// Timer/callback
lynx.performance.profileStart('async function');
setTimeout(() => {
  // ...
  lynx.performance.profileEnd();
}, 3000);

// await/promise
lynx.performance.profileStart('await-task');
await someAsyncFunc();
lynx.performance.profileEnd();
```
#### Correct Examples
```javascript {3,5,9,11}
// Timer/callback: use begin/end inside the callback
setTimeout(() => {
  lynx.performance.profileStart('async function');
  // ...
  lynx.performance.profileEnd();
}, 3000);

// await/promise: use instant trace events
lynx.performance.profileMark('async-task:start');
await someAsyncFunc();
lynx.performance.profileMark('async-task:end');
```
## 




---
url: /guide/performance/analysis-performance/trace-track.md
---


.full_image {
  width: 750px;
  margin: 20px;
}

# Track Overview

## What is a Track

In the Trace UI, a Track is the basic unit that displays Trace data. Each Track represents a type of events or data stream, such as thread activity, CPU frequency, memory changes, and key timing markers. Tracks let developers clearly see the occurrence order, duration, and distribution across threads on a timeline, enabling analysis of application behavior and performance bottlenecks.
A Track is shown as a horizontal bar in the Trace UI, with its name displayed on the left.

![Trace Track Overview](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/track-overview-trace.png)
## Common Tracks

### Process Track

The Process Track is typically named using the process name and process id (iOS and macOS Traces use `Process {pid}`). In Lynx Trace, there is usually only one Process Track, serving as the top-level container for all other Tracks.

![Process Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/process-track.png)
### Thread Track

Thread Tracks are typically named using the thread name and thread id. Lynx Trace includes multiple thread Tracks such as the [UI thread](/guide/spec.md#ui-thread), [Engine thread](/guide/spec.md#engine-thread-historically-known-as-tasm-thread), and [background thread](/guide/spec.md#background-scripting-thread-historically-known-as-js-thread). Below are common Thread Tracks that help developers see the order, duration, and thread distribution of events to analyze behavior and bottlenecks.

#### UI Thread Track

The UI Thread Track shows all events and tasks on the application’s UI thread, such as page rendering, UI operations, and the main loop. Analyzing the UI Thread Track helps locate performance issues like UI stutter and render blocking. In Lynx Trace, a process contains a single UI Thread Track.

By default, the top-most Thread Track is the UI Thread Track.

- On Android and Harmony, the UI Thread Track is named `process-name pid(main thread)`.
- On iOS and macOS, the Thread Track with the smallest thread id is the UI Thread Track.

![UI Thread Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/ui-thread-track.png)
#### Background Thread Track

The Background Thread Track shows [BTS](/guide/spec.md#background-thread-script-or-bts) execution. Use this Track to analyze BTS scheduling, execution, and duration.

:::info
For historical reasons, the background thread is named Lynx\_JS.
:::

![Background Thread Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/background-thread-track-trace.png)
#### Event Report Track

The Event Report Track shows Lynx’s internal event reporting process, helping locate issues like whether an event was reported.

![Event Report Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/event-report-thread-track.png)
### Performance Issue Track

The Performance Issue Track is used to mark performance anomalies and bottlenecks. Developers can quickly locate hot spots and abnormal behavior via this Track.

![Timing Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-issue-track.png)
### Timing Track

The Timing Track shows key timestamps (such as first screen render done and actual first meaningful paint), helping developers locate key milestones.

![Timing Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/timing-track.png)
### NativeModule Track

The [NativeModule](/guide/use-native-modules.md#原生模块) Track shows the NativeModule invocation process, including JS–Native communication and data conversion. Use it to analyze native module flows and performance bottlenecks.

![NativeModule Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-track.png)
### CPU Frequency Track

The CPU Frequency Track displays changes in CPU frequency over time as a line chart, helping developers analyze CPU resource usage under high load.

![CPU Frequency Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/cpu-frequency-track.png)
### Memory Track

The Memory Track shows Lynx page memory usage changes over time, with each Memory Track representing one Lynx page. Use it to analyze memory leaks, peaks, and abnormal growth.

![Memory Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/memory-track-latest.png)
## Common Track operations

### Pin Track

Pin Track fixes a Track at the top of the Trace view for easier comparison and continuous focus on key threads or events.

![Pin To Top](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/pin-to-top-track.png)
### Delete Track

Delete Track lets developers temporarily hide Tracks that are not of interest, simplifying the UI and leaving only the Tracks needed for analysis to improve efficiency. Deleted Tracks reappear after refreshing the Trace page.

![Delete Track](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/delete-track.png)
## More resources

For a more detailed guide on Trace Tracks and advanced features, see the official Perfetto documentation: [perfetto-ui](https://perfetto.dev/docs/visualization/perfetto-ui)



---
url: /guide/start/build-with-app-framework.md
---

# Build with an App Framework

[Try with ExplorerRun Lynx pages in the pre-built sandbox app](/guide/start/quick-start)[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|
**App frameworks** built on Lynx offer a complete development experience for shipping a new native application end to end, with native navigation, lifecycle management, and production-ready tooling, ideal for **Greenfield** projects.

### Sparkling iOS Android
**Lynx at TikTok scale.**
[Sparkling](https://tiktok.github.io/sparkling/) is TikTok's open-source mobile application framework built on Lynx, bringing the same cross-platform infrastructure that powers TikTok itself to developers. It pairs a type-safe JavaScript-to-native bridge with scheme-driven multi-page routing and project scaffolding, deploys to both **iOS and Android** from a single bundle, and is production-tested across TikTok's ecosystem. Visit the [Sparkling documentation](https://tiktok.github.io/sparkling/) to get started.

### Lynxtron Coming soon
**Lynx for desktop.**
Lynxtron is the upcoming desktop counterpart, an Electron-like framework with a lightweight Lynx renderer that ships the same UI across **macOS, Windows, and Web**, extensible through Node-API native modules.

***

:::tip Development Tip
During development, you can use **Lynx Explorer** to quickly preview and iterate on your Lynx pages. Switch to the [Try with Explorer](/guide/start/quick-start.md) approach to set it up.
:::



---
url: /guide/start/integrate-lynx-dev-version.md
---

# Integrate Lynx development version

During Lynx page development, you can use the Trace and Lynx Recorder tools for debugging, analysis, and locate issues.
To avoid impacting production performance, the official release version of Lynx does not include Trace and Recorder features.
For developer convenience, Lynx also provides a development version (with a `-dev` suffix in the version number). Starting from `release/3.4`, Lynx provides a dev version for each release version (the dev version uses the same release version number with a `-dev` suffix). You can integrate the Lynx development version by following the steps below.

:::info

You can find the development version corresponding to your release version at [github](https://github.com/lynx-family/lynx/tags).

:::

iOSAndroidHarmonyOS### Integrate Lynx
Refer to the [Lynx integration guide](/guide/start/integrate-with-existing-apps.md?platform=ios) for detailed steps on integrating Lynx.
### Integrate Lynx DevTool
Refer to the [Lynx DevTool integration guide](/guide/start/integrate-lynx-devtool.md#platform=ios) for detailed steps on integrating Lynx DevTool.
### Switch to the dev version of Lynx
Update your `Podfile` to use the dev version of the Lynx component.
```ruby title="Podfile"
pod 'Lynx', '{versionJson.LYNX_VERSION}' # [!code --]
pod 'Lynx', '{versionJson.LYNX_VERSION}-dev' # [!code ++]

pod 'LynxDevtool', '{versionJson.LYNX_VERSION}' # [!code --]
pod 'LynxDevtool', '{versionJson.LYNX_VERSION}-dev' # [!code ++]
```
### Install Dependencies
Run `pod install` to install dependencies, then open your Xcode project and rebuild.
### Integrate Lynx
Refer to the [Lynx integration guide](/guide/start/integrate-with-existing-apps.md?platform=android) for detailed steps on integrating Lynx.
### Integrate Lynx DevTool
Refer to the [Lynx DevTool integration guide](/guide/start/integrate-lynx-devtool.md#platform=android) for detailed steps on integrating Lynx DevTool.
### Switch to the dev version of lynx and lynx-trace
Update your `build.gradle` or `build.gradle.kts` to use the dev versions:

**build.gradle**

```groovy
- implementation ("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}-dev") {
+   // Exclude the lynx-trace module to avoid including it transitively
+  exclude group: 'org.lynxsdk.lynx', module: 'lynx-trace'
+ }

- implementation ("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}-dev")

- implementation ("org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}") {
+   // Exclude the lynx-trace and lynx module to avoid including it transitively
+   exclude group: 'org.lynxsdk.lynx', module: 'lynx-trace'
+   exclude group: 'org.lynxsdk.lynx', module: 'lynx'
+ }
```


**build.gradle.kts**

```kotlin
- implementation ("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}-dev") {
+   // Exclude the lynx-trace module to avoid including it transitively
+  exclude(group = "org.lynxsdk.lynx", module = "lynx-trace")
+ }

- implementation ("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}-dev")

- implementation ("org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}")
+ implementation ("org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}") {
+   // Exclude the lynx-trace and lynx module to avoid including it transitively
+   exclude(group = "org.lynxsdk.lynx", module = "lynx-trace")'
+   exclude(group = 'org.lynxsdk.lynx', module = 'lynx')
+ }
```

### Rebuild your application
Rebuild your application to ensure all changes take effect.
### Integrate Lynx
Refer to the [Lynx integration guide](/guide/start/integrate-with-existing-apps.md?platform=harmony) for detailed steps on integrating Lynx.
### Integrate Lynx DevTool
Refer to the [Lynx DevTool integration guide](/guide/start/integrate-lynx-devtool.md#platform=harmony) for detailed steps on integrating Lynx DevTool.
### Switch to the dev version of lynx and lynx\_devtool
Update your `oh-package.json5` to use the dev version of the Lynx component.
```json5
"dependencies": {
  "@lynx/lynx": "3.5.1", // [!code --]
  "@lynx/lynx_devtool": "3.5.1", // [!code --]
  "@lynx/lynx": "3.5.1-dev", // [!code ++]
  "@lynx/lynx_devtool": "3.5.1-dev", // [!code ++]
}
```
### Install Dependencies
Run `ohpm install` to install dependencies, then open your DevEco-Studio project and rebuild.
## 


Congratulations! You have completed the integration of the Lynx development version.
Now, you can launch the DevTool desktop application and start debugging and performance profiling using either the LynxTrace or LynxRecorder tool.



---
url: /guide/start/integrate-lynx-devtool-advanced.md
---

# Advanced DevTool Configurations

## Integrate DevTool Switch Page

We provide a switch page that helps you quickly view or set DevTool. If you want, you can integrate it into your app as well.


iOSAndroidHarmonyOS![Lynx DevTool Switch Page](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-ios.png)> The switch setting page is written in Lynx, and the DevTool component has already packaged the page.
Code example for integrating the devtool switch page:

**Objective-C**

```objective-c
#import <Lynx/LynxView.h>

#import "DebugSettingViewController.h"
#import "DemoLynxProvider.h"

@implementation DebugSettingViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
    builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
    builder.screenSize = self.view.frame.size;
    builder.fontScale = 1.0;
  }];

  lynxView.preferredLayoutWidth = self.view.frame.size.width;
  lynxView.preferredLayoutHeight = self.view.frame.size.height;
  lynxView.layoutWidthMode = LynxViewSizeModeExact;
  lynxView.layoutHeightMode = LynxViewSizeModeExact;

  [self.view addSubview:lynxView];

  NSString *bundlePath = [[NSBundle mainBundle] pathForResource:@"LynxDebugResources" ofType: @"bundle"];
  NSData *templateData = [[NSData alloc] initWithContentsOfFile:[bundlePath stringByAppendingString:@"/switchPage/devtoolSwitch.lynx.bundle"]];
  [lynxView loadTemplate:templateData withURL:@"devtool_switch/switchPage/devtoolSwitch.lynx.bundle"];
}

@end
```


**Swift**

```swift
import UIKit

class DebugSettingViewController: UIViewController {
  var url: String?

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
    self.view.addSubview(lynxView)

    let bundlePath = Bundle.main.path(forResource: "LynxDebugResources", ofType: "bundle")
    let templateData = NSData(contentsOfFile: bundlePath!.appending("/switchPage/devtoolSwitch.lynx.bundle"))
    lynxView.loadTemplate(templateData! as Data, withURL: "devtool_switch/switchPage/devtoolSwitch.lynx.bundle")
  }
}
```

![Lynx DevTool Switch Page](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-android.png)> The switch setting page is written in Lynx, and the DevTool component has already packaged the page.
Code example for integrating the devtool switch page:

**Java**

```java
public class SwitchActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
        byte[] array = null;
        try {
            InputStream inputStream = this.getAssets().open("devtool_switch/switchPage/devtoolSwitch.lynx.bundle");
            array = readBytes(inputStream);
            lynxView.renderTemplateWithBaseUrl(array, TemplateData.empty(), "devtool_switch/switchPage/devtoolSwitch.lynx.bundle");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider());
        return viewBuilder.build(this);
    }

    private byte[] readBytes(InputStream inputStream) throws IOException {
        byte[] buffer = new byte[1024];
        int bytesRead;
        ByteArrayOutputStream output = new ByteArrayOutputStream();
        while ((bytesRead = inputStream.read(buffer)) != -1) {
            output.write(buffer, 0, bytesRead);
        }
        return output.toByteArray();
    }

}

```


**Kotlin**

```kotlin
class SwitchActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
        try {
            val array = this.assets.open("devtool_switch/switchPage/devtoolSwitch.lynx.bundle").readBytes()
            lynxView.renderTemplateWithBaseUrl(
                array,
                TemplateData.empty(),
                "devtool_switch/switchPage/devtoolSwitch.lynx.bundle"
            )
        } catch (e: IOException) {
            e.printStackTrace()
        }
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder = LynxViewBuilder()
        viewBuilder.setTemplateProvider(DemoTemplateProvider())
        return viewBuilder.build(this)
    }
}
```

![Lynx DevTool Switch Page](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/debugging-devtool-switch-en-harmony.png)> The switch setting page is written in Lynx, and the DevTool component has already packaged the page.
Code example for integrating the devtool switch page:

**ETS**

```ts
class Param {
  url: string;
  constructor(url: string) {
    this.url = url;
  }
}
@Entry
@Component
struct SwitchPage {
  // ... existing code ...
  build() {
    Column() {
      Text('Lynx').fontSize(18).width('100%').height('5%').textAlign(TextAlign.Center)
      LynxView({
        clients: this.clients,
        url: this.url,
        genericResourceFetcher: this.genericFetcher,
        mediaResourceFetcher: this.mediaFetcher,
        templateResourceFetcher: this.templateFetcher,
        modules: this.modules,
        sendableModules: this.sendableModules,
        metaData: this.metaData,
        onCreate: (context: LynxContext) => {
          let param: Param = new Param(this.url);
          context.sendGlobalEvent('viewAppear', [param]);
          if (this.widthPixel > 0 && this.heightPixel > 0) {
            context.updateScreenMetrics(this.widthPixel * this.viewDensity / TEST_DENSITY,
              this.heightPixel * this.viewDensity / TEST_DENSITY);
          }
          context.setExtraTiming(this.extraTiming);
        }
      }).height(this.viewHeight).width(this.viewWidth)
    }.size({ width: '100%', height: '100%' }).alignItems(HorizontalAlign.Start)
  }
}

```


You can also customize the page according to your needs, making the configuration of DevTool more diverse.

## Compatibility

**Error:** No compatibility data found for `devtool.integration.switch`


---
url: /guide/start/integrate-lynx-devtool.md
---

# Integrating Lynx DevTool

When encountering issues during Lynx page development, you can use [DevTool](/guide/devtool/panels.md) for debugging.
However, you need to follow these steps to integrate DevTool first.

:::info
It is recommended to integrate DevTool in non-production environments to keep your production builds lightweight.

- **Package size**: DevTool will increase the package size.
- **Runtime**: Related modules are lazy loaded when enabled, which will increase memory overhead, and some features may affect the loading performance.

All code examples in this documentation can be found in the [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/main).
:::

iOSAndroidHarmonyOS### Adding Dependencies
You need to add these components: the `Devtool` subcomponent of `LynxService`, `LynxDevTool`, and `DebugRouter`.
```ruby title="Podfile" {2-8}
# Ensure Lynx DevTool version matches the Lynx version when integrating
target 'YourTarget' do
  pod 'LynxService', '{versionJson.LYNX_VERSION}', :subspecs => [
      'Devtool',
  ]
  pod 'LynxDevtool', '{versionJson.LYNX_VERSION}'

  pod 'DebugRouter', '5.0.15'
  pod 'DebugRouter/MessageTransceiverEnable', '5.0.15'
end
```
### Enabling DevTool
DevTool provides several debugging switches.
Here are three important switches:
- `Lynx Debug` is the switch that controls all DevTool debugging.
- `Lynx DevTool` controls main debugging features: element inspection and JavaScript debugging.
- `Lynx LogBox` manages the [LogBox](/guide/devtool/handle-errors.md).
These switches are disabled by default, you need to enable them.- `Lynx DevTool` and `Lynx LogBox` switches can only take effect after `Lynx Debug` is enabled.
- When debugging Lynx pages with the DevTool Desktop, `Lynx DevTool` needs to be enabled.
- LogBox helps you quickly identify and diagnose issues.
You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

**Objective-C**

```objective-c title=AppDelegate.m {9-18}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxService.h>
#import <Lynx/LynxServiceDevToolProtocol.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // ...
  LynxEnv *lynxEnv = [LynxEnv sharedInstance];
  // Enable all sessions debugging for DevTool (required for Lynx DevTool Desktop connection)
  [LynxService(LynxServiceDevToolProtocol) enableAllSessions];
  // Enable Lynx Debug
  lynxEnv.lynxDebugEnabled = YES;
  // Enable Lynx DevTool
  lynxEnv.devtoolEnabled = YES;
  // Enable Lynx LogBox
  [LynxService(LynxServiceDevToolProtocol) setLogBoxPresetValue:YES];
  lynxEnv.logBoxEnabled = YES;
  return YES;
}
```


**Swift**

```objective-c title="YourTarget-Bridging-Header.h"
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxService.h>
#import <Lynx/LynxServiceDevToolProtocol.h>
```
```swift title=AppDelegate.swift {5-14}
class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...
    let lynxEnv = LynxEnv.sharedInstance()
    // Enable all sessions debugging for DevTool (required for Lynx DevTool Desktop connection)
    (LynxServices.getInstanceWith(LynxServiceDevToolProtocol.self, bizID: DEFAULT_LYNX_SERVICE) as? LynxServiceDevToolProtocol)?.enableAllSessions()
    // Enable Lynx Debug
    lynxEnv.lynxDebugEnabled = true
    // Enable Lynx DevTool
    lynxEnv.devtoolEnabled = true
    // Enable Lynx LogBox
    (LynxServices.getInstanceWith(LynxServiceDevToolProtocol.self, bizID: DEFAULT_LYNX_SERVICE) as? LynxServiceDevToolProtocol)?.logBoxPresetValue = true
    lynxEnv.logBoxEnabled = true
    return true
  }
}
```

:::info
In addition to the three switches introduced earlier, there are more switches that can help you control the behavior of DevTool. Please refer to the [Lynx DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch).
:::
### Adding Dependencies
You need to integrate these two components: `lynx-service-devtool` and `lynx-devtool`

**build.gradle**

```groovy
// Ensure Lynx DevTool version matches the Lynx version when integrating
dependencies {
  implementation "org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}"
  implementation "org.lynxsdk.lynx:lynx-service-devtool:{versionJson.LYNX_VERSION}"
}
```


**build.gradle.kts**

```kotlin
// Ensure Lynx DevTool version matches the Lynx version when integrating
dependencies {
  implementation ("org.lynxsdk.lynx:lynx-devtool:{versionJson.LYNX_VERSION}")
  implementation ("org.lynxsdk.lynx:lynx-service-devtool:{versionJson.LYNX_VERSION}")
}
```

:::info
It is recommended to use the latest [Lynx version](https://github.com/lynx-family/lynx/releases) when integrating
:::
### Registering DevTool Service
DevTool Service provides some preset values to control default behaviors. You can configure them as needed.
In the next chapter, we will introduce these preset values in detail.

**Java**

```java title=YourApplication.java {3-13}
private void initLynxService() {
  // ...
  // enable all sessions debug for DevTool (required for Lynx DevTool Desktop connection)
  LynxDevToolService.getINSTANCE().enableAllSessions();

  // register DevTool service
  LynxServiceCenter.inst().registerService(LynxDevToolService.getINSTANCE());

  // set DevTool preset values
  LynxDevToolService.getINSTANCE().setLynxDebugPresetValue(true);
  LynxDevToolService.getINSTANCE().setLogBoxPresetValue(true);
  LynxDevToolService.getINSTANCE().setLoadQJSBridge(true);
  LynxDevToolService.getINSTANCE().setLoadV8Bridge(true);
}

```


**Kotlin**

```kotlin title=YourApplication.kt {3-13}
private fun initLynxService() {
  // ...
  // enable all sessions debug for DevTool (required for Lynx DevTool Desktop connection)
  LynxDevToolService.INSTANCE.enableAllSessions()

  // register DevTool service
  LynxServiceCenter.inst().registerService(LynxDevToolService.INSTANCE)

  // set DevTool preset values
  LynxDevToolService.INSTANCE.setLynxDebugPresetValue(true)
  LynxDevToolService.INSTANCE.setLogBoxPresetValue(true)
  LynxDevToolService.INSTANCE.setLoadQJSBridge(true)
  LynxDevToolService.INSTANCE.setLoadV8Bridge(true)
}
```

### Enabling DevTool
DevTool provides several debugging switches.
Here are three important switches:
- `Lynx Debug` is the switch that controls all DevTool debugging.
- `Lynx DevTool` controls main debugging features: element inspection and JavaScript debugging.
- `Lynx LogBox` manages the [LogBox](/guide/devtool/handle-errors.md).
These switches are disabled by default, you need to enable them.- `Lynx DevTool` and `Lynx LogBox` switches can only take effect after `Lynx Debug` is enabled.
- When debugging Lynx pages with the DevTool Desktop, `Lynx DevTool` needs to be enabled.
  - If you need to use JavaScript debugging, you also need to set the `LoadQJSBridge` or `LoadV8Bridge` preset value to `true`.
    - `LoadQJSBridge` controls loading the PrimJS engine debugging library.
    - `LoadV8Bridge` controls loading the V8 engine debugging library.
- LogBox helps you quickly identify and diagnose issues.
You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

**Java**

```java title=YourApplication.java {3-8}
private void initLynxEnv() {
  LynxEnv.inst().init(this, null, null, null);
  // Enable Lynx Debug
  LynxEnv.inst().enableLynxDebug(true);
  // Enable Lynx DevTool
  LynxEnv.inst().enableDevtool(true);
  // Enable Lynx LogBox
  LynxEnv.inst().enableLogBox(true);
}

```


**Kotlin**

```kotlin title=YourApplication.kt {3-8}
private fun initLynxEnv() {
  LynxEnv.inst().init(this, null, null, null)
  // Enable Lynx Debug
  LynxEnv.inst().enableLynxDebug(true)
  // Enable Lynx DevTool
  LynxEnv.inst().enableDevtool(true)
  // Enable Lynx LogBox
  LynxEnv.inst().enableLogBox(true)
}
```

:::info
In addition to the three switches introduced earlier, there are more that can help you control the behavior of DevTool. Please refer to the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch).
:::
### Adding Dependencies
You need to integrate these two components: `@lynx/lynx_devtool` and `@lynx/lynx_devtool_service`.

**oh-package.json5**

```json5
// Ensure Lynx DevTool version matches the Lynx version when integrating
"dependencies": {
  "@lynx/lynx_devtool": "@param:dependencies.lynx_version",
  "@lynx/lynx_devtool_service": "@param:dependencies.lynx_version"
}
```


**build-profile.json5**

```json5
// Since @lynx/lynx_devtool is dynamically imported via a variable,
// to include the devtool module in the build,
// you also need to add a runtimeOnly buildOption in buildOption within build-profile.json5.
"buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "packages": [
          "@lynx/lynx_devtool"
        ]
      }
    },
}
```

:::info
It is recommended to use the latest [Lynx version](https://github.com/lynx-family/lynx/releases) when integrating
:::
### Registering DevTool Service

**ETS**

```ts title=YourEntryAbility.ets {2 - 3}
// Initialize LynxDevToolService first, as LynxEnv initialization
// depends on LynxDevToolService from LynxService
LynxServiceCenter.registerService(
  LynxServiceType.DevTool,
  LynxDevToolService.instance,
);
```

### Enabling DevTool
DevTool provides several debugging switches.
Here are three important switches:
- `Lynx Debug` is the switch that controls all DevTool debugging.
- `Lynx DevTool` controls main debugging features: element inspection and JavaScript debugging.
- `Lynx LogBox` manages the [LogBox](/guide/devtool/handle-errors.md).
Lynx Debug and LogBox are on by default; DevTool is off. Enabling DevTool is recommended.- `Lynx DevTool` and `Lynx LogBox` switches can only take effect after `Lynx Debug` is enabled.
- When debugging Lynx pages with the DevTool Desktop, `Lynx DevTool` needs to be enabled.
- LogBox helps you quickly identify and diagnose issues.
You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

**ETS**

```ts title=YourEntryAbility.ets {4-9}
public initLynxEnv() {
  LynxEnv.initialize(this.context);

  // Enable Lynx Debug
  LynxEnv.enableLynxDebug(true);
  // Enable Lynx DevTool
  LynxEnv.enableDevtool(true);
  // Enable Lynx LogBox
  LynxEnv.setLogBoxEnabled(true);
}

```

:::info
In addition to the three switches introduced earlier, there are more that can help you control the behavior of DevTool. Please refer to the [DevTool Switch Page](/guide/start/integrate-lynx-devtool-advanced.md#debugging-devtool-switch).
:::
## 


Congratulations! You have completed the DevTool integration. Now, you may launch the Lynx DevTool Desktop and
connect your app via USB to start debugging.

![Integrate Lynx DevTool Successfully](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/devtool_connected_success.png)
[More DevTool Switches

Need more advanced configurations for DevTool?

](/guide/start/integrate-lynx-devtool-advanced)
## Compatibility

**Error:** No compatibility data found for `devtool.integration`
## Next Step

[Use DevTool

Learn how to use Lynx DevTool Desktop for in-depth debugging capabilities

](/guide/devtool/panels.html)


---
url: /guide/start/integrate-with-existing-apps.md
---

# Integrate with Existing Apps

[Try with ExplorerRun Lynx pages in the pre-built sandbox app](/guide/start/quick-start)Integrate with Existing AppsUse Lynx as a UI building block in your native or web app[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use Lynx as a high-performance, cross-platform UI rendering engine you can embed anywhere inside your existing application. This **Brownfield** approach offers the maximum flexibility, supports **all platforms**, lets you adopt Lynx incrementally without rewriting your app, and is commonly used for large-scale applications in production.

iOSAndroidHarmonyOSWebWindowsmacOS### Integrate Lynx with Existing Apps (iOS)

Lynx for iOS- This article assumes that you are familiar with the basic concepts of native iOS application development.
- You can refer to the project: <Link href={'https://github.com/lynx-family/integrating-lynx-demo-projects/tree/' + (versionJson.current_version === 'next' ? 'main': `release/${versionJson.current_version}`)}>integrating-lynx-demo-projects</Link> for all the code mentioned below.

## 1. Dependency configuration

Using [Cocoapods](https://cocoapods.org/) can easily integrate Lynx into your application

Recommended Versions- Cocoapods: >= 1.11.3
- Ruby: >= 2.6.10

### Configuring Deps
1. **Lynx**
The core capabilities of [Lynx Engine](/guide/spec.md#engine) include basic capabilities such as parsing [Bundle](/guide/spec.md#lynx-bundle-or-bundle), style parsing, layout, and rendering views
Get the latest version of Lynx from Cocoapods. Then add Lynx to your Podfile:
```ruby title="Podfile" {1,6-8,10}
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '{versionJson.LYNX_VERSION}', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '{versionJson.PRIMJS_VERSION}', :subspecs => ['quickjs', 'napi']
end
```
2. **Lynx Service**
Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, `LynxImageService` is implemented using the [SDWebImage](https://github.com/SDWebImage/SDWebImage) image library by default. Apps that do not integrate SDWebImage components can rely on other image libraries to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;
Get the latest version of Lynx Service from Cocoapods. Then add Lynx Service to your Podfile:
```ruby title="Podfile" {13-17,20-21}
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '{versionJson.LYNX_VERSION}', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '{versionJson.PRIMJS_VERSION}', :subspecs => ['quickjs', 'napi']

  # integrate image-service, log-service, and http-service
  pod 'LynxService', '{versionJson.LYNX_VERSION}', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService dependencies:
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'
end
```
3. **More Elements**
​​XElement​​ is an extend native elements library maintained by the Lynx team. It provides richer component capabilities, enabling faster adoption of Lynx in production environments and enhancing the vibrancy of the Lynx ecosystem.
```ruby title="Podfile" {23}
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '{versionJson.LYNX_VERSION}', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '{versionJson.PRIMJS_VERSION}', :subspecs => ['quickjs', 'napi']

  # integrate image-service, log-service, and http-service
  pod 'LynxService', '{versionJson.LYNX_VERSION}', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'

  pod 'XElement', '{versionJson.LYNX_VERSION}'
end
```
### Install Dependencies
Run `pod install` to install dependencies, then open your Xcode project. Additionally, make sure to disable the Sandbox Scripting capability.
:::note
In order to disable the **Sandbox scripting**, in Xcode click on your app, then on **build settings**. Filter for **script** and set the **User Script Sandboxing** to **NO**.
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/integration_ios_warning.png):::

## 2. Lynx Environment Initialization

### LynxEnv Initialization
LynxEnv provides a global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface call of the Lynx Engine.
For example, it can be initialized in `AppDelegate`

**Objective-C**

```objective-c title=AppDelegate.m {6}
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [LynxEnv sharedInstance];
  return YES;
}
```


**Swift**

```swift title=AppDelegate.swift {8}
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    LynxEnv.sharedInstance()
    return true
  }
}

```


## 3. Render LynxView

LynxView is the basic rendering unit provided by Lynx Engine. LynxView is an implementation inherited from iOS native [UIView](https://developer.apple.com/documentation/uikit/uiview). You can quickly construct a LynxView and add it to the [ViewController](https://developer.apple.com/documentation/uikit/uitab/viewcontroller/).

### Create Bundle Loader
Lynx Engine itself does not have the ability to load resources, so it is necessary to initialize LynxEnv, or when constructing [LynxView](/guide/spec.md#lynxview) to pass in the specific implementation of the `LynxTemplateProvider` protocol. Lynx will use the injected resource loader to obtain the Bundle content
You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.
1. First, please either generate the Bundle file from the [Quick Start](/guide/start/quick-start.md) phase or download the file below to your local machine, and then follow these steps to embed the file:
:::note
Bundle Example:
**[https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle](https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle)**
:::
:::note
Steps to embed files:
- In the target settings of the project, select the target;
- Select the **Build Phases** tab;
- In the **Copy Bundle Resources** section, click the add button (+) to add the file;
:::
2. Impl Bundle Loader

**Objective-C**

```objective-c title="DemoLynxProvider.h"
#import <Foundation/Foundation.h>
#import <Lynx/LynxTemplateProvider.h>

NS_ASSUME_NONNULL_BEGIN

@interface DemoLynxProvider : NSObject <LynxTemplateProvider>

@end

NS_ASSUME_NONNULL_END
```


**Swift**

:::tip
Use [Bridging Header](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift) to import the required Lynx header files if you are using a Swift project, since Lynx is a project built with Objective-C.
:::
```objective-c title="YourTarget-Bridging-Header.h"
#import <Lynx/LynxConfig.h>
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxTemplateProvider.h>
#import <Lynx/LynxView.h>
```


**Objective-C**

```objective-c title="DemoLynxProvider.m"
#import <Foundation/Foundation.h>

#import "DemoLynxProvider.h"

@implementation DemoLynxProvider

- (void)loadTemplateWithUrl:(NSString*)url onComplete:(LynxTemplateLoadBlock)callback {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:url ofType:@"bundle"];
    if (filePath) {
      NSError *error;
      NSData *data = [NSData dataWithContentsOfFile:filePath options:0 error:&error];
      if (error) {
        NSLog(@"Error reading file: %@", error.localizedDescription);
        callback(nil, error);
      } else {
        callback(data, nil);
      }
    } else {
      NSError *urlError = [NSError errorWithDomain:@"com.lynx"
                                                  code:400
                                                userInfo:@{NSLocalizedDescriptionKey : @"Invalid URL."}];
      callback(nil, urlError);
    }
}

@end
```


**Swift**

```swift title="DemoLynxProvider.swift"
import Foundation

class DemoLynxProvider: NSObject, LynxTemplateProvider {
  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
    if let filePath = Bundle.main.path(forResource: url, ofType: "bundle") {
      do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        callback(data, nil)
      } catch {
        print("Error reading file: \(error.localizedDescription)")
        callback(nil, error)
      }
    } else {
      let urlError = NSError(domain: "com.lynx", code: 400, userInfo: [NSLocalizedDescriptionKey: "Invalid URL."])
      callback(nil, urlError)
    }
  }
}
```

### Construct Basic LynxView
you may construct a basic LynxView as follows:

**Objective-C**

```objective-c title="ViewController.m" {10-18}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
      builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
      builder.screenSize = self.view.frame.size;
      builder.fontScale = 1.0;
    }];
    lynxView.preferredLayoutWidth = self.view.frame.size.width;
    lynxView.preferredLayoutHeight = self.view.frame.size.height;
    lynxView.layoutWidthMode = LynxViewSizeModeExact;
    lynxView.layoutHeightMode = LynxViewSizeModeExact;
}
@end
```


**Swift**

```swift title=ViewController.swift {8-17}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
  }
}
```

### Add LynxView To The Window:
and then, adding the LynxView to the window.

**Objective-C**

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [self.view addSubview:lynxView];
}

@end
```


**Swift**

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    self.view.addSubview(lynxView)
  }
}

```

### Render View
After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.loadTemplateFromURL` method to render the corresponding Bundle onto the LynxView.

**Objective-C**

```objective-c title="ViewController.m" {13}
#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView loadTemplateFromURL:@"main.lynx" initData:nil];
}

@end
```


**Swift**

```swift title="ViewController.swift" {10}
import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    lynxView.loadTemplate(fromURL: "main.lynx", initData: nil)
  }
}

```

Then you will see the following interface on the screen:
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-ios.png)
Congratulations, you have now completed all the work of integrating Lynx Engine!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start.md) and [debugging](/guide/devtool/panels.md) docs for in-depth insights on working with Lynx.
### Integrate Lynx with Existing Apps (Android)

Lynx for Android- This article assumes that you are familiar with the basic concepts of native Android application development.
- You can refer to the project: <Link href={'https://github.com/lynx-family/integrating-lynx-demo-projects/tree/' + (versionJson.current_version === 'next' ? 'main': `release/${versionJson.current_version}`)}>integrating-lynx-demo-projects</Link> for all the code mentioned below.

## 1. Dependency configuration

### Configuring Gradle
1. **Lynx**
The core capabilities of [Lynx Engine](/guide/spec.md#engine) include basic capabilities such as parsing [Bundle](/guide/spec.md#lynx-bundle-or-bundle), style parsing, layout, rendering views and the basic code of the javascript runtime that Lynx pages rely on

**build.gradle**

```groovy title=build.gradle {3-6}
dependencies {
    // lynx dependencies
    implementation "org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}"
}
```


**build.gradle.kts**

```groovy title=build.gradle.kts {3-6}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}")
}
```

2. **Lynx Service**
Lynx Service includes `LynxImageService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official.For example, `LynxImageService` is implemented using the [Fresco](https://github.com/facebook/fresco) image library by default. Apps that do not integrate Fresco components can rely on other image libraries, such as [Glide](https://github.com/bumptech/glide) to implement Image Service.
Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;
:::note
Since [Fresco](https://github.com/facebook/fresco) depends on [AndroidX](https://developer.android.com/jetpack/androidx), you also need to configure the following in gradle.properties:
```groovy
android.useAndroidX=true
```
:::

**build.gradle**

```groovy title=build.gradle {8-24}
dependencies {
    // lynx dependencies
    implementation "org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}"

    // integrating image-service
    implementation "org.lynxsdk.lynx:lynx-service-image:{versionJson.LYNX_VERSION}"

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation "com.facebook.fresco:fresco:2.3.0"
    implementation "com.facebook.fresco:animated-gif:2.3.0"
    implementation "com.facebook.fresco:animated-webp:2.3.0"
    implementation "com.facebook.fresco:webpsupport:2.3.0"
    implementation "com.facebook.fresco:animated-base:2.3.0"

    implementation "com.squareup.okhttp3:okhttp:4.9.0"

    // integrating log-service
    implementation "org.lynxsdk.lynx:lynx-service-log:{versionJson.LYNX_VERSION}"

    // integrating http-service
    implementation "org.lynxsdk.lynx:lynx-service-http:{versionJson.LYNX_VERSION}"
}
```


**build.gradle.kts**

```groovy title=build.gradle.kts {8-24}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}")

    // integrating image-service
    implementation("org.lynxsdk.lynx:lynx-service-image:{versionJson.LYNX_VERSION}")

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation("com.facebook.fresco:fresco:2.3.0")
    implementation("com.facebook.fresco:animated-gif:2.3.0")
    implementation("com.facebook.fresco:animated-webp:2.3.0")
    implementation("com.facebook.fresco:webpsupport:2.3.0")
    implementation("com.facebook.fresco:animated-base:2.3.0")

    // integrating log-service
    implementation("org.lynxsdk.lynx:lynx-service-log:{versionJson.LYNX_VERSION}")

    // integrating http-service
    implementation("org.lynxsdk.lynx:lynx-service-http:{versionJson.LYNX_VERSION}")

    implementation("com.squareup.okhttp3:okhttp:4.9.0")
}
```

### Configure obfuscation rules ([Proguard](https://developer.android.com/build/shrink-code))
The obfuscation rules for` Lynx Engine` are as follows. It is recommended to refer to the latest source code configuration.
```groovy title=proguard-rules.pro
# LYNX START
# use @Keep to annotate retained classes.
-dontwarn android.support.annotation.Keep
-keep @android.support.annotation.Keep class **
-keep @android.support.annotation.Keep class ** {
    @android.support.annotation.Keep <fields>;
    @android.support.annotation.Keep <methods>;
}
-dontwarn androidx.annotation.Keep
-keep @androidx.annotation.Keep class **
-keep @androidx.annotation.Keep class ** {
    @androidx.annotation.Keep <fields>;
    @androidx.annotation.Keep <methods>;
}
# native method call
-keepclasseswithmembers,includedescriptorclasses class * {
    native <methods>;
}
-keepclasseswithmembers class * {
    @com.lynx.tasm.base.CalledByNative <methods>;
}

# to customize a module, you need to keep the class name and the method annotated as LynxMethod.
-keepclasseswithmembers class * {
    @com.lynx.jsbridge.LynxMethod <methods>;
}

-keepclassmembers class *  {
    @com.lynx.tasm.behavior.LynxProp <methods>;
    @com.lynx.tasm.behavior.LynxPropGroup <methods>;
    @com.lynx.tasm.behavior.LynxUIMethod <methods>;
}

-keepclassmembers class com.lynx.tasm.behavior.ui.UIGroup {
    public boolean needCustomLayout();
}

# in case R8 compiler may remove mLoader in bytecode.
# as mLoader is not used in java and passed as a WeakRef in JNI.
-keepclassmembers class com.lynx.tasm.LynxTemplateRender {
    private com.lynx.tasm.core.resource.LynxResourceLoader mLoader;
    private com.lynx.tasm.core.resource.LynxResourceLoader mResourceLoader;
}

# the automatically generated setter classes use the class names of LynxBaseUI and ShadowNode and their subclasses.
-keep class com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class com.lynx.tasm.behavior.shadow.ShadowNode
-keep class com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.tasm.behavior.ui.LynxBaseUI
-keep class * extends com.lynx.tasm.behavior.shadow.ShadowNode
-keep class * extends com.lynx.jsbridge.LynxModule { *; }
-keep class * extends com.lynx.jsbridge.LynxContextModule
-keep class * implements com.lynx.tasm.behavior.utils.Settable
-keep class * implements com.lynx.tasm.behavior.utils.LynxUISetter
-keep class * implements com.lynx.tasm.behavior.utils.LynxUIMethodInvoker
-keep class com.lynx.tasm.rendernode.compat.**{
    *;
}
-keep class com.lynx.tasm.rendernode.compat.RenderNodeFactory{
    *;
}
# LYNX END
```

## 2. Environment Initialization

### Lynx Service Initialization
- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service during the `Application#onCreate` lifecycle of the application.
- Lynx Service needs to be actively injected
:::tip
Please specify your custom Application class in the AndroidManifest.xml file, since Lynx needs to perform some global initialization operations when the application starts.
```xml title="/app/src/main/AndroidManifest.xml" {2}
<application
  android:name=".YourApplication">
</application>
```
:::

**Java**

```java title=YourApplication.java {17,20-30}
import android.app.Application;

import com.facebook.drawee.backends.pipeline.Fresco;
import com.facebook.imagepipeline.core.ImagePipelineConfig;
import com.facebook.imagepipeline.memory.PoolConfig;
import com.facebook.imagepipeline.memory.PoolFactory;
import com.lynx.service.http.LynxHttpService;
import com.lynx.service.image.LynxImageService;
import com.lynx.service.log.LynxLogService;
import com.lynx.tasm.service.LynxServiceCenter;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
    }

    private void initLynxService() {
        // init Fresco which is needed by LynxImageService
        final PoolFactory factory = new PoolFactory(PoolConfig.newBuilder().build());
        ImagePipelineConfig.Builder builder =
                ImagePipelineConfig.newBuilder(getApplicationContext()).setPoolFactory(factory);
        Fresco.initialize(getApplicationContext(), builder.build());

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance());
        LynxServiceCenter.inst().registerService(LynxLogService.INSTANCE);
        LynxServiceCenter.inst().registerService(LynxHttpService.INSTANCE);
    }
}
```


**Kotlin**

```kotlin title=YourApplication.kt {15,18-27}
import android.app.Application
import com.facebook.drawee.backends.pipeline.Fresco
import com.facebook.imagepipeline.core.ImagePipelineConfig
import com.facebook.imagepipeline.memory.PoolConfig
import com.facebook.imagepipeline.memory.PoolFactory
import com.lynx.service.http.LynxHttpService
import com.lynx.service.image.LynxImageService
import com.lynx.service.log.LynxLogService
import com.lynx.tasm.service.LynxServiceCenter

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
    }

    private fun initLynxService() {
        // init Fresco which is needed by LynxImageService
        val factory = PoolFactory(PoolConfig.newBuilder().build())
        val builder = ImagePipelineConfig.newBuilder(applicationContext).setPoolFactory(factory)
        Fresco.initialize(applicationContext, builder.build())

        LynxServiceCenter.inst().registerService(LynxImageService.getInstance())
        LynxServiceCenter.inst().registerService(LynxLogService)
        LynxServiceCenter.inst().registerService(LynxHttpService)
    }
}
```

### LynxEnv Initialization
LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv during the Application#onCreate lifecycle of the application.

**Java**

```java title=YourApplication.java {9,12-19}
import com.lynx.tasm.LynxEnv;

public class YourApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        initLynxService();
        initLynxEnv();
    }

    private void initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        );
    }
}
```


**Kotlin**

```kotlin title=YourApplication.kt {8,11-18}
import com.lynx.tasm.LynxEnv

class YourApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        initLynxService()
        initLynxEnv()
    }

    private fun initLynxEnv() {
        LynxEnv.inst().init(
            this,
            null,
            null,
            null
        )
    }
}
```

:::tip
The parameters for the LynxEnv initialization method are described as follows:
- **appContext**: The context object for the application lifecycle, i.e., ApplicationContext.
- **libraryLoader**: The loader for native so files, the default value can be null, which will use the system default loader.
- **templateProvider**: The global AppBundle loader, the default value can be null;
- **behaviorBundle**: The list of custom components, the default value can be null. If there are customization requirements, please refer to [custom-native-component](/guide/custom-native-component.md)
:::

## 3. Render LynxView

### Create Bundle Loader
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `AbsTemplateProvider`, and inject it when initializing LynxEnv or constructing [LynxView](/guide/spec.md#lynxview). Lynx will use the injected resource loader to obtain the Bundle content
You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.
1. First, please place the Bundle file generated in the [Quick Start](/guide/start/quick-start.md) stage in the src/main/assets directory, or you can download the file below to your local machine and place it in the same directory:
:::note
Bundle Example:
**[https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle](https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle)**
:::
```
app
└── src
    └── main
        ├── java
        ├── res
        └── assets
            └── main.lynx.bundle
```
2. Impl Bundle Loader

**Java**

```java title="DemoTemplateProvider.java" {}
import android.content.Context;
import com.lynx.tasm.provider.AbsTemplateProvider;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;

public class DemoTemplateProvider extends AbsTemplateProvider {
    private Context mContext;

    DemoTemplateProvider(Context context) {
        this.mContext = context.getApplicationContext();
    }

    @Override
    public void loadTemplate(String uri, Callback callback) {
        new Thread(new Runnable() {
            @Override
            public void run() {
                try (InputStream inputStream = mContext.getAssets().open(uri);
                     ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream()) {
                    byte[] buffer = new byte[1024];
                    int length;
                    while ((length = inputStream.read(buffer)) != -1) {
                        byteArrayOutputStream.write(buffer, 0, length);
                    }
                    callback.onSuccess(byteArrayOutputStream.toByteArray());
                } catch (IOException e) {
                    callback.onFailed(e.getMessage());
                }
            }
        }).start();
    }
}
```


**Kotlin**

```kotlin title="DemoTemplateProvider.kt" {}
import android.content.Context
import com.lynx.tasm.provider.AbsTemplateProvider
import java.io.ByteArrayOutputStream
import java.io.IOException

class DemoTemplateProvider(context: Context) : AbsTemplateProvider() {

    private var mContext: Context = context.applicationContext

    override fun loadTemplate(uri: String, callback: Callback) {
        Thread {
            try {
                mContext.assets.open(uri).use { inputStream ->
                    ByteArrayOutputStream().use { byteArrayOutputStream ->
                        val buffer = ByteArray(1024)
                        var length: Int
                        while ((inputStream.read(buffer).also { length = it }) != -1) {
                            byteArrayOutputStream.write(buffer, 0, length)
                        }
                        callback.onSuccess(byteArrayOutputStream.toByteArray())
                    }
                }
            } catch (e: IOException) {
                callback.onFailed(e.message)
            }
        }.start()
    }
}
```

### Construct LynxView
`LynxView` is the basic rendering view provided by `Lynx Engine`. `LynxView` inherits from the native Android [View](https://developer.android.com/reference/android/view/View). You can quickly construct a LynxView and add it arbitrarily to the native Android view tree.

**Java**

```java title=MainActivity.java {12-13,16-20}
import android.app.Activity;
import android.os.Bundle;

import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewBuilder;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.setTemplateProvider(new DemoTemplateProvider(this));
        return viewBuilder.build(this);
    }
}
```


**Kotlin**

```kotlin title=MainActivity.kt {11-12,15-19}
import android.app.Activity
import android.os.Bundle
import com.lynx.tasm.LynxView
import com.lynx.tasm.LynxViewBuilder


class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder = LynxViewBuilder()
        viewBuilder.setTemplateProvider(DemoTemplateProvider(this))
        return viewBuilder.build(this)
    }
}
```

3. **More Elements**
​​XElement​​ is an extend native elements library maintained by the Lynx team. It provides richer component capabilities, enabling faster adoption of Lynx in production environments and enhancing the vibrancy of the Lynx ecosystem.

**build.gradle**

```groovy title=build.gradle {26-28}
dependencies {
    // lynx dependencies
    implementation "org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}"
    // integrating image-service
    implementation "org.lynxsdk.lynx:lynx-service-image:{versionJson.LYNX_VERSION}"
    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation "com.facebook.fresco:fresco:2.3.0"
    implementation "com.facebook.fresco:animated-gif:2.3.0"
    implementation "com.facebook.fresco:animated-webp:2.3.0"
    implementation "com.facebook.fresco:webpsupport:2.3.0"
    implementation "com.facebook.fresco:animated-base:2.3.0"
    implementation "com.squareup.okhttp3:okhttp:4.9.0"
    // integrating log-service
    implementation "org.lynxsdk.lynx:lynx-service-log:{versionJson.LYNX_VERSION}"
    // integrating http-service
    implementation "org.lynxsdk.lynx:lynx-service-http:{versionJson.LYNX_VERSION}"
    // integrating XElement
    implementation "org.lynxsdk.lynx:xelement:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:xelement-input:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:xelement-overlay:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:xelement-svg:{versionJson.LYNX_VERSION}"
    implementation "org.lynxsdk.lynx:servalsvg:0.0.1-alpha.3"
    implementation "org.lynxsdk.lynx:refresh:{versionJson.LYNX_VERSION}"
}
```


**build.gradle.kts**

```groovy title=build.gradle.kts {26-28}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-jssdk:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:lynx-trace:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:primjs:{versionJson.PRIMJS_VERSION}")

    // integrating image-service
    implementation("org.lynxsdk.lynx:lynx-service-image:{versionJson.LYNX_VERSION}")

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation("com.facebook.fresco:fresco:2.3.0")
    implementation("com.facebook.fresco:animated-gif:2.3.0")
    implementation("com.facebook.fresco:animated-webp:2.3.0")
    implementation("com.facebook.fresco:webpsupport:2.3.0")
    implementation("com.facebook.fresco:animated-base:2.3.0")

    // integrating log-service
    implementation("org.lynxsdk.lynx:lynx-service-log:{versionJson.LYNX_VERSION}")

    // integrating http-service
    implementation("org.lynxsdk.lynx:lynx-service-http:{versionJson.LYNX_VERSION}")

    implementation("com.squareup.okhttp3:okhttp:4.9.0")

    // integrating XElement
    implementation("org.lynxsdk.lynx:xelement:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:xelement-input:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:xelement-overlay:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:xelement-svg:{versionJson.LYNX_VERSION}")
    implementation("org.lynxsdk.lynx:servalsvg:0.0.1-alpha.3")
    implementation("org.lynxsdk.lynx:xelement-refresh:{versionJson.LYNX_VERSION}")
}
```

### Introduce XElement
XElement requires additional importation in the `LynxViewBuilder`:

**Java**

```java title=MainActivity.java {6,19}
import android.app.Activity;
import android.os.Bundle;

import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewBuilder;
import com.lynx.xelement.XElementBehaviors;

public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);
    }

    private LynxView buildLynxView() {
        LynxViewBuilder viewBuilder = new LynxViewBuilder();
        viewBuilder.addBehaviors(new XElementBehaviors().create());
        viewBuilder.setTemplateProvider(new DemoTemplateProvider(this));
        return viewBuilder.build(this);
    }
}
```


**Kotlin**

```kotlin title=MainActivity.kt {5,17}
import android.app.Activity
import android.os.Bundle
import com.lynx.tasm.LynxView
import com.lynx.tasm.LynxViewBuilder
import com.lynx.xelement.XElementBehaviors

class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)
    }

    private fun buildLynxView(): LynxView {
        val viewBuilder: LynxViewBuilder = LynxViewBuilder()
        viewBuilder.addBehaviors(XElementBehaviors().create())
        viewBuilder.setTemplateProvider(DemoTemplateProvider(this))
        return viewBuilder.build(this)
    }
}
```

### 4 Render view
After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView.renderTemplateUrl` method to render the corresponding Bundle onto the LynxView view.

**Java**

```java title=MainActivity.java {9-10}
public class MainActivity extends Activity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LynxView lynxView = buildLynxView();
        setContentView(lynxView);

        String url = "main.lynx.bundle";
        lynxView.renderTemplateUrl(url, "");
    }
}
```


**Kotlin**

```kotlin title=MainActivity.kt {8-9}
class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val lynxView = buildLynxView()
        setContentView(lynxView)

        val uri = "main.lynx.bundle";
        lynxView.renderTemplateUrl(uri, "")
    }
}
```

Then you will see the following interface on the screen:
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-android.png)
Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start.md) and [debugging](/guide/devtool/panels.md) docs for in-depth insights on working with Lynx.
### Integrate Lynx with Existing Apps (Harmony)

Lynx for Harmony- This article assumes that you are familiar with the basic concepts of native Harmony application development.
- You can refer to the project: [integrating-lynx-demo-projects](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/main/harmony/HarmonyEmptyProject) for all the code mentioned below.

## 1. Dependency Configuration

### Configuring Deps
1. **Lynx**
The core capabilities of [Lynx Engine](/guide/spec.md#engine) include basic capabilities such as parsing [Bundle](/guide/spec.md#lynx-bundle-or-bundle), style parsing, layout, rendering views and the basic code of the javascript runtime that Lynx pages rely on
```json5 title=oh-package.json5 {3-4}
"dependencies": {
  "@ohos/imageknife": "3.2.6",
  "@lynx/lynx": "3.6.0",
  "@lynx/primjs": "3.6.1",
},
```
2. **Lynx Service**
Lynx Service includes `LynxDevtoolService`, `LynxLogService`, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, `LynxHttpService` is implemented using the built-in HTTP module of HarmonyOS by default. Lynx provides standard native Log and HTTP service capabilities, which can be quickly accessed and used by the access party;
```json5 title=oh-package.json5 {3-8}
"dependencies": {
  "@ohos/imageknife": "3.2.6",
  "@lynx/lynx": "3.6.0",
  "@lynx/lynx_devtool": "3.6.0",
  "@lynx/lynx_devtool_service": "3.6.0",
  "@lynx/lynx_http_service": "3.6.0",
  "@lynx/lynx_log_service": "3.6.0",
  "@lynx/primjs": "3.6.1",
},
```
### Capability Dependencies
1. **Native C++ Configuration**
To import `libc++_shared.so`, you need to configure Native C++. This requires defining a `CMakeLists.txt` file.
```cmake title=CMakeLists.txt
# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(MyApplication)
```
And modify the `buildOptions` in `entry/build-profile.json5`:
```json5 title=build-profile.json5 {3-7}
{
  buildOption: {
    externalNativeOptions: {
      path: './src/main/cpp/CMakeLists.txt',
      arguments: '',
      cppFlags: '',
    },
  },
}
```
2. **Network Request Configuration**
If you need to request network resources, configure `requestPermissions` in `module.json5` to enable network requests.
```json5 title=module.json5 {3-14}
{
  module: {
    requestPermissions: [
      {
        name: 'ohos.permission.INTERNET',
        reason: '$string:network',
        usedScene: {
          abilities: ['FormAbility'],
          when: 'inuse',
        },
      },
    ],
  },
}
```
And configure the `network` key field in `entry/src/main/resources/base/element/string.json`:
```json title=string.json {3-6}
{
  "string": [
    {
      "name": "network",
      "value": "Request network"
    }
  ]
}
```
3. **XElement OHPM Configuration**
```json5 title=oh-package.json5
"dependencies": {
  "@lynx/xelement_svg": "3.6.0",
},
```

## 2. Environment Initialization

### Lynx Service Initialization
- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service during the `UIAbility#onCreate` lifecycle of the application.
- Lynx Service needs to be actively injected.
```ts title=EntryAbility.ets
import { LLog, LynxServiceCenter, LynxEnv, LynxServiceType } from '@lynx/lynx';
import { LynxDevToolService } from '@lynx/lynx_devtool_service';
import { LynxLogService } from '@lynx/lynx_log_service';
import { LynxHttpService } from '@lynx/lynx_http_service';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Init LynxDevtoolService
    LynxServiceCenter.registerService(
      LynxServiceType.DevTool,
      LynxDevToolService.instance,
    );
    // Init LynxHttpService
    LynxServiceCenter.registerService(
      LynxServiceType.Http,
      LynxHttpService.instance,
    );
    // Init LynxLogService

    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');

    LynxServiceCenter.registerService(
      LynxServiceType.Log,
      LynxLogService.instance,
    );
  }
}
```
### LynxEnv Initialization
`LynxEnv` provides the global initialization interface for the `Lynx Engine`. Please ensure that the initialization of `LynxEnv` occurs before any interface calls to the `Lynx Engine`. It is recommended to complete the initialization of LynxEnv during the `UIAbility#onCreate` lifecycle of the application.
```ts title=EntryAbility.ets
import { LLog, LynxEnv } from '@lynx/lynx';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Init LynxService
    // ...
    // Init LynxEnv
    LLog.useSysLog(true);
    LynxEnv.initialize(this.context);
    let options = new Map<string, string>();
    options.set('App', 'LynxExplorer');
    options.set('AppVersion', '0.0.1');
    LynxEnv.setAppInfo(options);
    LynxEnv.enableDevtool(true);
  }
}
```

## 3. Rendering LynxView

### Create Bundle Loader
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `LynxResourceProvider`, and inject it when constructing [LynxView](/guide/spec.md#lynxview). Lynx will use the injected resource loader to obtain the Bundle content
You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.
First, please place the Bundle file generated in the [Quick Start](/guide/start/quick-start.md) stage in the src/main/resources/rawfile directory, or you can download the file below to your local machine and place it in the same directory:
:::note
Bundle Example:
**[https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle](https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle)**
:::
```
entry
└── src
    └── main
        └── resources
            └── rawfile
                 └── main.lynx.bundle
```
1. **LynxTemplateResourceFetcher**
`LynxTemplateResourceFetcher` provides the capability to load Bundle template resources. You need to implement the `fetchTemplate` method to handle the loading.
```ts title=ExampleTemplateResourceFetcher.ets
import {
  LLog,
  LynxResourceRequest,
  LynxTemplateResourceFetcher,
  TemplateProviderResult,
} from '@lynx/lynx';
import { AsyncCallback, BusinessError } from '@ohos.base';
import http from '@ohos.net.http';
import resourceManager from '@ohos.resourceManager';

export class ExampleTemplateResourceFetcher extends LynxTemplateResourceFetcher {
  fetchTemplate(
    request: LynxResourceRequest,
    callback: AsyncCallback<TemplateProviderResult, void>,
  ) {
    if (request.url.startsWith('http')) {
      let httpRequest = http.createHttp();
      httpRequest.request(
        request.url,
        {
          expectDataType: http.HttpDataType.ARRAY_BUFFER,
        },
        (err: BusinessError, data: http.HttpResponse) => {
          callback(err, {
            binary: data?.result as ArrayBuffer,
          });
          httpRequest.destroy();
        },
      );
    } else {
      // local file
      const context: Context = getContext(this);
      const resourceMgr: resourceManager.ResourceManager =
        context.resourceManager;
      resourceMgr.getRawFileContent(
        request.url,
        (err: BusinessError, data: Uint8Array) => {
          callback(err, {
            binary: data?.buffer as ArrayBuffer,
          });
        },
      );
    }
  }

  fetchSSRData(
    request: LynxResourceRequest,
    callback: AsyncCallback<ArrayBuffer, void>,
  ) {
    let httpRequest = http.createHttp();
    httpRequest.request(
      request.url,
      {
        expectDataType: http.HttpDataType.ARRAY_BUFFER,
      },
      (err: BusinessError, data: http.HttpResponse) => {
        callback(err, data?.result as ArrayBuffer);
        httpRequest.destroy();
      },
    );
  }
}
```
2. **LynxMediaResourceFetcher**
`LynxMediaResourceFetcher` provides the capability to load media resources.
```ts title=ExampleMediaResourceFetcher.ets
import {
  LynxMediaResourceFetcher,
  LynxResourceRequest,
  LynxOptionalBool,
} from '@lynx/lynx';

export class ExampleMediaResourceFetcher extends LynxMediaResourceFetcher {
  shouldRedirectUrl(request: LynxResourceRequest): string {
    // just return the input url;
    return request.url;
  }

  isLocalResource(url: string): LynxOptionalBool {
    return LynxOptionalBool.UNDEFINED;
  }
}
```
3. **LynxGenericResourceFetcher**
`LynxGenericResourceFetcher` provides the capability to load generic resources. You need to implement the `fetchResource` method to handle the loading.
```ts title=ExampleGenericResourceFetcher.ets
import {
  LynxError,
  LynxSubErrorCode,
  LynxGenericResourceFetcher,
  LynxResourceRequest,
  LynxResourceType,
  LynxStreamDelegate,
} from '@lynx/lynx';
import { AsyncCallback, BusinessError } from '@ohos.base';
import http from '@ohos.net.http';
import { ImageKnife, ImageKnifeOption, CacheStrategy } from '@ohos/imageknife';

export class ExampleGenericResourceFetcher extends LynxGenericResourceFetcher {
  fetchResource(
    request: LynxResourceRequest,
    callback: AsyncCallback<ArrayBuffer, void>,
  ): void {
    let httpRequest = http.createHttp();
    httpRequest.request(
      request.url,
      {
        expectDataType: http.HttpDataType.ARRAY_BUFFER,
      },
      (err: BusinessError, data: http.HttpResponse) => {
        callback(err, data?.result as ArrayBuffer);
        httpRequest.destroy();
      },
    );
  }

  fetchResourcePath(
    request: LynxResourceRequest,
    callback: AsyncCallback<string, void>,
  ): void {
    if (request.type === LynxResourceType.LYNX_RESOURCE_TYPE_IMAGE) {
      let option = new ImageKnifeOption();
      option.loadSrc = request.url;
      option.writeCacheStrategy = CacheStrategy.File;
      let error: BusinessError | undefined = undefined;
      ImageKnife.getInstance()
        .preLoadCache(option)
        .then((data: string) => {
          if (data.length > 0) {
            callback(error, data);
          } else {
            error = {
              code: LynxSubErrorCode.E_RESOURCE_IMAGE_PIC_SOURCE,
              message: 'Image path is invalid',
              name: 'Image Error',
            };
            callback(error, '');
          }
        })
        .catch((e: string) => {
          error = {
            code: LynxSubErrorCode.E_RESOURCE_IMAGE_FROM_NETWORK_OR_OTHERS,
            message: e,
            name: 'Image Error',
          };
          callback(error, '');
        });
    } else {
      callback(
        {
          code: LynxError.LYNX_ERROR_CODE_RESOURCE,
          message: 'unsupported type: ' + request.type,
          name: 'Resource Error',
        },
        '',
      );
    }
  }

  fetchStream(
    request: LynxResourceRequest,
    delegate: LynxStreamDelegate,
  ): void {
    // TODO(Lynx): support fetching stream.
    delegate.onStart(100);
    let a = new ArrayBuffer(10);
    delegate.onData(a, 0, 10);
    delegate.onEnd();
  }

  cancel(request: LynxResourceRequest): void {
    // TODO(Lynx)
  }
}
```
### Construct LynxView and Render the View
Once you have completed the steps above, you have finished all the necessary work for creating the `LynxView` and reading its resources. You can now render the corresponding Bundle content onto the `LynxView`.
```ts title=Index.ets
import {
  LynxTemplateResourceFetcher,
  LynxMediaResourceFetcher,
  LynxGenericResourceFetcher,
  LynxView,
} from '@lynx/lynx';

import { ExampleTemplateResourceFetcher } from '../provider/ExampleTemplateResourceFetcher';
import { ExampleMediaResourceFetcher } from '../provider/ExampleMediaResourceFetcher';
import { ExampleGenericResourceFetcher } from  '../provider/ExampleGenericResourceFetcher';

@Entry
@Component
struct Index {
  templateResourceFetcher: LynxTemplateResourceFetcher = new ExampleTemplateResourceFetcher();
  mediaResourceFetcher: LynxMediaResourceFetcher = new ExampleMediaResourceFetcher();
  genericResourceFetcher: LynxGenericResourceFetcher = new ExampleGenericResourceFetcher();
  private url: string = 'your bundle file';

  build() {
    Column() {
      LynxView({
        templateResourceFetcher: this.templateResourceFetcher,
        mediaResourceFetcher: this.mediaResourceFetcher,
        genericResourceFetcher: this.genericResourceFetcher,
        url: this.url,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```
You will then see the following content on your screen:
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-harmony.png)
Congratulations! You have now completed the full integration of the Lynx Engine.

## 4. Now what?

Now that you have integrated Lynx into your application, please refer to the [Development](/guide/start/quick-start.md) and [Debugging](/guide/devtool/panels.md) documentation to further explore the world of Lynx!
### Integrate Lynx with Existing Apps (Web)

Lynx for WebLynx for Web implements the Lynx engine in web browsers. With Lynx for Web,
you can easily integrate Lynx apps into any existing web project, regardless
of whether the project uses React, Vue, Svelte, or plain HTML.

## 1. Development & Debugging

We need you to have read and created a Lynx project according to [Quick Start](/guide/start/quick-start.md).

### Add web configuration
1. Enter the previously created Lynx project:
```bash
cd <lynx-project-name>
```
2. Add web configuration (`environments.web`) to `lynx.config.ts`:
```ts
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [pluginReactLynx()],
  environments: {
    web: {},
    lynx: {},
  },
});
```
### Start development server
Run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You can now visit the development page locally.
### Build & Preview
You can also use Web Explorer to quickly preview the web bundle of a page in production mode.
First, run:

```sh [npm]
npm run build
```

```sh [yarn]
yarn run build
```

```sh [pnpm]
pnpm run build
```

```sh [bun]
bun run build
```

```sh [deno]
deno run npm:build
```
You will see an additional `dist/main.web.bundle` file in this project, which is the final web build artifact.
Open [Lynx Explorer Web Edition](https://www.unpkg.com/@lynx-js/web-explorer@0.0.15/index.html), fill in the accessible URL of your artifact, and you can see the effect in production mode.

## 2. Integrate with a new web project

Now that you have a Lynx for Web build artifact, we need to create a web project to use it. Here we use Rsbuild.

### Create a web project
Create a new project at the same level as the Lynx project above and run:

```sh [npm]
npm create rsbuild@latest
```

```sh [yarn]
yarn create rsbuild
```

```sh [pnpm]
pnpm create rsbuild@latest
```

```sh [bun]
bun create rsbuild@latest
```

```sh [deno]
deno init --npm rsbuild@latest
```
Follow the prompts to create a React project.
### Configure the project
1. Navigate to the created project:
```bash
cd <web-project-name>
```
2. Install dependencies

```sh [npm]
npm install @lynx-js/web-core
```

```sh [yarn]
yarn add @lynx-js/web-core
```

```sh [pnpm]
pnpm add @lynx-js/web-core
```

```sh [bun]
bun add @lynx-js/web-core
```

```sh [deno]
deno add npm:@lynx-js/web-core
```
3. Import these dependencies in `src/App.tsx`
```tsx
import './App.css';
import '@lynx-js/web-core/client';
import type { LynxViewElement as LynxView } from '@lynx-js/web-core/client';

const App = () => {
  return (
    <lynx-view
      style={{ height: '100vh', width: '100vw' }}
      url="/main.web.bundle"
    ></lynx-view>
  );
};

export default App;
```
4. Update `rsbuild.config.ts`
:::warning
`server.publicDir` needs to be replaced with your actual Lynx project path.
:::
```ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    publicDir: [
      {
        name: path.join(
          __dirname,
          '../',
          // Please replace this with your actual Lynx project name
          'lynx-project',
          'dist',
        ),
      },
    ],
  },
});
```
### Start the project
Run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
Visit `http://localhost:3000` to see your Lynx application.

## 3. API Reference

See [LynxView](/api/lynx-native-api/lynx-view/lynx-view.md) for more API details.
### Integrate Lynx with Existing Apps (Windows)

Lynx for Windows- This article assumes that you are familiar with the basic concepts of native
  Windows application development.
- You can also refer to the official [LynxExplorer](https://github.com/lynx-family/lynx/tree/develop/explorer/windows/lynx_explorer)
  project.

## 1. Dependency configuration

### Download or Build LynxSDK
- Download the LynxSDK from [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).
- Extract the downloaded file to a subdirectory of your project, such as the `thirdparty` directory.
Or, you may build from source by following the [Build Lynx Explorer for Windows](https://github.com/lynx-family/lynx/tree/develop/explorer/windows) guide.
### Configuring CMake
This manual assumes you have a CMake-based project already and wish to integrate LynxSDK. If you are using a different build system, you can refer to this guide and proceed with integration on your own.
1. Based on your project configuration, set up the basic settings of the CMake project.
```cmake title=CMakeLists.txt {17,20-30}
# Set the C++ standard to at least 17 if you are using the C++ wrapper apis of LynxSDK.
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
```
2. Setup LynxSDK.
```cmake title=CMakeLists.txt {17,20-30}
set(LYNX_LIB_PATH ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx) # Or your location of LynxSDK
# Set include directory of LynxSDK.
include_directories(${LYNX_LIB_PATH}/include)
# Set library of LynxSDK that needs to be linked.
target_link_libraries(${PROJECT_NAME} ${LYNX_LIB_PATH}/lib/lynx.dll.lib)
```
3. Add custom command to copy data and resources after build.
```cmake title=CMakeLists.txt {17,20-30}
# Copy lynx.dll to output directory.
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx/lib/lynx.dll
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
# Copy data to output directory.
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx/data
        $<TARGET_FILE_DIR:${PROJECT_NAME}>/data)
# Copy lynx_core.js to output directory.
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx/lynx_core.js
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
# Copy lynx_core_dev.js to output directory.
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx/lynx_core_dev.js
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
```

## 2. Environment Initialization - Optional

### Lynx Service Initialization
- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service before LynxView creation.
- Lynx Service needs to be actively injected
```c++ title=main.cc {17,20-30}

#include "lynx_env.h"
#include "lynx_http_service.h"
#include "lynx_view.h"
#include "lynx_generic_resource_fetcher.h"

// Implements the http service if needed.
class LynxHttpServiceImpl : public lynx::pub::LynxHttpService {
public:
LynxHttpServiceImpl() = default;
~LynxHttpServiceImpl() = default;

void Request(std::shared_ptr<lynx::pub::LynxHttpRequest> request,
std::shared_ptr<lynx::pub::LynxHttpResponse> response) override {
// TODO
}

};

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
// Register http service for lynx.fetch.
lynx::pub::LynxServiceCenter::GetInstance().
RegisterService(std::make_shared<LynxHttpServiceImpl>());

// TODO: create window and construct LynxView.

return 0;
}

```
### LynxEnv Initialization
LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv before LynxView creation.
```c++ title=main.cc {9,12-19}

#include <windows.h>

#include "lynx_env.h"
#include "lynx_http_service.h"
#include "lynx_view.h"
#include "lynx_generic_resource_fetcher.h"

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
    // Register http service for lynx.fetch.
  lynx::pub::LynxServiceCenter::GetInstance().
    RegisterService(std::make_shared<LynxHttpServiceImpl>());

  // Initialize LynxEnv
  auto& lynx_env = lynx::pub::LynxEnv::GetInstance();
  // Enable devtool.
  lynx_env.SetDevtoolEnabled(true);
  lynx_env.SetDevtoolAppInfo("App", "LynxExplorer");
  lynx_env.SetDevtoolAppInfo("AppVersion", "1.0.0");
  // Register global native module if needed.
  // lynx_env.RegisterNativeModule("ExplorerModule", ExplorerModuleCreator, nullptr);

  // TODO: create window and construct LynxView.

  return 0;
}

```

## 3. Render LynxView

### Create Resource Fetcher
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `LynxGenericResourceFetcher`, and inject it when constructing `LynxView`. Lynx will use the injected resource fetcher to obtain the Bundle content
You can use various methods to obtain the contents of the Bundle. Here, we choose to load the contents of the Bundle from local file system.
Download the Bundle file below.
:::note
Bundle Example:
**[https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle](https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle)**
:::
Impl Resource Fetcher (Optional)
```c++ title=GenericResourceFetcher.cc {9,12-19}

#include "lynx_env.h"
#include "lynx_http_service.h"
#include "lynx_view.h"
#include "lynx_generic_resource_fetcher.h"

class ExampleGenericResourceFetcher : public lynx::pub::LynxGenericResourceFetcher {
public:
void FetchResource(
std::shared_ptr<lynx::pub::LynxResourceRequest> request,
std::shared_ptr<lynx::pub::LynxResourceResponse> response) override {
// Implements fetching logic if you want to load Bundle from net.
}
};

```
### Construct LynxView
`LynxView` is the basic rendering view provided by `Lynx Engine`. You can quickly construct a LynxView and provide a NSView as it's parent.
```c++ title=main.cc {9,12-19}
#include <windows.h>

#include "lynx_env.h"
#include "lynx_http_service.h"
#include "lynx_view.h"
#include "lynx_generic_resource_fetcher.h"

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
  // TODO: create window.

  // Construct LynxView.
  lynx::pub::LynxView::Builder builder;
  builder.SetScreenSize(800, 600, 1.0)
      .SetFrame(0, 0, 800, 600)
      .SetParent(hwnd);
  // Set Resource fetcher if needed.
  // builder.SetGenericResourceFetcher(std::make_shared<ExampleGenericResourceFetcher>());
  auto lynx_view = builder.Build();

  // Run message.
  MSG msg = {0};
  while (GetMessage(&msg, NULL, 0, 0)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);
  }
  return 0;
}

```
### Render view
After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView->LoadTemplate` method to render the corresponding Bundle onto the LynxView.
```c++ title=main.cc {9,12-19}
#include <windows.h>

#include "lynx_env.h"
#include "lynx_http_service.h"
#include "lynx_view.h"
#include "lynx_generic_resource_fetcher.h"

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {
// TODO: create window.

// Construct LynxView.
lynx::pub::LynxView::Builder builder;
builder.SetScreenSize(800, 600, 1.0)
.SetFrame(0, 0, 800, 600)
.SetParent(hwnd);
// Set Resource fetcher if needed.
// builder.SetGenericResourceFetcher(std::make_shared<ExampleGenericResourceFetcher>());
auto lynx_view = builder.Build();

auto load_meta = std::make_shared<lynx::pub::LynxLoadMeta>();
// Set to your location.
load_meta->SetUrl("file://C:\\Users\\Admin\\Documents\\main.lynx.bundle");
lynx_view->LoadTemplate(load_meta);

// Run message.
MSG msg = {0};
while (GetMessage(&msg, NULL, 0, 0)) {
TranslateMessage(&msg);
DispatchMessage(&msg);
}
return 0;
}

```
Then you will see the following interface on the screen:
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/hello-world-showcase-windows.jpg)
Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start.md) and [debugging](/guide/devtool/panels.md) docs for in-depth insights on working with Lynx.

```
```
### Integrate Lynx with Existing Apps (macOS)

Lynx for macOS- This article assumes that you are familiar with the basic concepts of native
  macOS application development.
- You can also refer to the official [LynxExplorer](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/macos/lynx_explorer)
  project.

## 1. Dependency configuration

### Download or Build LynxSDK
- Download the LynxSDK from [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).
- Extract the downloaded file to a subdirectory of your project, such as the `thirdparty` directory.
Or, you may build from source by following the [Build Lynx Explorer for macOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/macos) guide.
### Configuring CMake
This manual assumes you have a CMake-based project already and wish to integrate LynxSDK. If you are using a different build system, you can refer to this guide and proceed with integration on your own.
1. Based on your project configuration, set up the basic settings of the CMake project.
```cmake title=CMakeLists.txt {17,20-30}
# Set the C++ standard to at least 17 if you are using the C++ wrapper apis of LynxSDK.
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_OBJCXX_STANDARD 17)
set(CMAKE_OBJCXX_STANDARD_REQUIRED ON)
```
2. Setup LynxSDK.
```cmake title=CMakeLists.txt {17,20-30}
set(LYNX_LIB_PATH ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/lynx) # Or your location of LynxSDK
# Set include directory of LynxSDK.
include_directories(${LYNX_LIB_PATH}/include)
# Set library of LynxSDK that needs to be linked.
target_link_libraries(${PROJECT_NAME} PRIVATE ${LYNX_LIB_PATH}/lib/libLynx.dylib)
```
3. Add custom command to copy data and resources after build.
```cmake title=CMakeLists.txt {17,20-30}
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    # Create Frameworks directory if needed.
    COMMAND mkdir -p "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Frameworks"

    # Copy libLynx.dylib to Frameworks directory of application bundle.
    COMMAND cp "${LYNX_LIB_PATH}/lib/libLynx.dylib" "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Frameworks/"

    # Create Resources directory if needed.
    COMMAND mkdir -p "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Resources"

    # Copy resource bundles to Resources directory of application bundle.
    COMMAND cp -R "${LYNX_LIB_PATH}/bundles/" "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Resources/"

    # Copy data to Resources directory of application bundle.
    COMMAND cp -R "${LYNX_LIB_PATH}/data/" "$<TARGET_BUNDLE_CONTENT_DIR:${PROJECT_NAME}>/Resources/"

    COMMENT "Copying Lynx library and resources to application bundle"
)

# Set the rpath to ensure the application can find dynamic libraries in the internal Frameworks directory.
target_link_options(${PROJECT_NAME} PRIVATE
    "-Wl,-rpath,@executable_path/../Frameworks"
)
```

## 2. Environment Initialization - Optional

### Lynx Service Initialization
- Lynx Service provides host feature-related capabilities and it is recommended to complete the initialization of Lynx Service before LynxView creation.
- Lynx Service needs to be actively injected
```objective-c title=AppDelegate.mm {17,20-30}
#import "AppDelegate.h"
#import "ViewController.h"

#import "lynx_env.h"
#import "lynx_http_service.h"
#import "lynx_view.h"

// Implements the http service if needed.
class LynxHttpServiceImpl : public lynx::pub::LynxHttpService {
public:
LynxHttpServiceImpl() = default;
~LynxHttpServiceImpl() = default;
void Request(std::shared_ptr<lynx::pub::LynxHttpRequest> request, std::shared_ptr<lynx::pub::LynxHttpResponse> response) override {
// TODO
}
};

@interface AppDelegate ()
@end

@implementation AppDelegate {
}

- (void)applicationDidFinishLaunching:(NSNotification \*)aNotification {
  // Register http service for lynx.fetch.
  lynx::pub::LynxServiceCenter::GetInstance().RegisterService(std::make_shared<LynxHttpServiceImpl>());

  }

```
### LynxEnv Initialization
LynxEnv provides the global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface calls to the Lynx Engine. It is recommended to complete the initialization of LynxEnv before LynxView creation.
```objective-c title=AppDelegate.mm {9,12-19}
#import "AppDelegate.h"
#import "ViewController.h"

#import "lynx_env.h"
#import "lynx_http_service.h"
#import "lynx_view.h"

@interface AppDelegate ()
@end

@implementation AppDelegate {
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
  // Register http service for lynx.fetch.
  lynx::pub::LynxServiceCenter::GetInstance().RegisterService(std::make_shared<LynxHttpServiceImpl>());

  // Initialize LynxEnv
  auto& lynx_env = lynx::pub::LynxEnv::GetInstance();
  // Enable devtool.
  lynx_env.SetDevtoolEnabled(true);
  lynx_env.SetDevtoolAppInfo("App", "LynxExplorer");
  lynx_env.SetDevtoolAppInfo("AppVersion", "1.0.0");
  // Register global native module if needed.
  // lynx_env.RegisterNativeModule("ExplorerModule", ExplorerModuleCreator, nullptr);
}

```

## 3. Render LynxView

### Create Resource Fetcher
Lynx Engine itself does not have the ability to integrate downloading resources, so the existing app needs to provide the specific implementation of `LynxGenericResourceFetcher`, and inject it when constructing `LynxView`. Lynx will use the injected resource fetcher to obtain the Bundle content
:::note
Bundle Example:
**[https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle](https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle)**
:::
Impl Resource Fetcher
```objective-c title=ExampleGenericResourceFetcher.h {9,12-19}
#import <Foundation/Foundation.h>
#import "lynx_generic_resource_fetcher.h"

class ExampleGenericResourceFetcher : public lynx::pub::LynxGenericResourceFetcher {
public:
void FetchResource(std::shared_ptr<lynx::pub::LynxResourceRequest> request, std::shared_ptr<lynx::pub::LynxResourceResponse> response) override;
};

```
```objective-c title=ExampleGenericResourceFetcher.mm {9,12-19}
#import <Foundation/Foundation.h>
#import "ExampleGenericResourceFetcher.h"

void ExampleGenericResourceFetcher::FetchResource(std::shared_ptr<lynx::pub::LynxResourceRequest> request, std::shared_ptr<lynx::pub::LynxResourceResponse> response) {
  const char *url_str = request->GetUrl();
  NSString *ns_string = [NSString stringWithUTF8String:url_str];

  NSURL *url = [NSURL URLWithString:ns_string];
  NSMutableURLRequest *nsRequest = [NSMutableURLRequest requestWithURL:url];
  NSURLSession *session = [NSURLSession sharedSession];
  NSURLSessionDataTask *dataTask =
    [session dataTaskWithRequest:nsRequest
              completionHandler:^(NSData *_Nullable data, NSURLResponse *_Nullable nsResponse,
                                  NSError *_Nullable error) {
                if (data && data.length > 0) {
                  response->SetCode(0);
                  response->SetData(
                      (uint8_t *)data.bytes, data.length,
                      [](uint8_t *body, size_t length, void *opaque) { CFRelease(opaque); },
                      (__bridge_retained void *)data);
                } else {
                  response->SetCode(-1);
                  response->SetErrorMessage("error");
                }
                response->Complete();
              }];

  [dataTask resume];
}

```
### Construct LynxView
`LynxView` is the basic rendering view provided by `Lynx Engine`. You can quickly construct a LynxView and provide a NSView as it's parent.
```objective-c title=ViewController.mm {9,12-19}
#import "ViewController.h"
#import "ExampleGenericResourceFetcher.h"

#import "lynx_env.h"
#import "lynx_http_service.h"
#import "lynx_view.h"

@interface ViewController ()
@property(nonatomic) std::shared_ptr<lynx::pub::LynxView> lynxView;
@end

@implementation ViewController {
}

- (void)viewDidLoad {
  [super viewDidLoad];

  lynx::pub::LynxView::Builder builder;
  builder.SetScreenSize(self.view.frame.size.width, self.view.frame.size.height, 1.0)
  .SetFrame(0, 0, self.view.frame.size.width, self.view.frame.size.height)
  .SetParent((\_\_bridge NativeWindow)self.view)
  .SetGenericResourceFetcher(std::make_shared<ExampleGenericResourceFetcher>());
  self.lynxView = builder.Build();
  }

- (void)viewDidLayout {
  [super viewDidLayout];
  // It's necessary when resizing the Window.
  self.lynxView->UpdateScreenMetrics(self.view.frame.size.width, self.view.frame.size.height,
  1.0);
  self.lynxView->SetFrame(0, 0, self.view.frame.size.width, self.view.frame.size.height);
  }

```
### Render view
After completing the above steps, all the work of initializing LynxView have been completed. Call the `lynxView->LoadTemplate` method to render the corresponding Bundle onto the LynxView.
```objective-c title=ViewController.mm {9,12-19}
#import "ViewController.h"
#import "ExampleGenericResourceFetcher.h"

#import "lynx_env.h"
#import "lynx_http_service.h"
#import "lynx_view.h"

@interface ViewController ()
@property(nonatomic) std::shared_ptr<lynx::pub::LynxView> lynxView;
@end

@implementation ViewController {
}

- (void)viewDidLoad {
  [super viewDidLoad];

  lynx::pub::LynxView::Builder builder;
  builder.SetScreenSize(self.view.frame.size.width, self.view.frame.size.height, 1.0)
    .SetFrame(0, 0, self.view.frame.size.width, self.view.frame.size.height)
    .SetParent((__bridge NativeWindow)self.view)
    .SetGenericResourceFetcher(std::make_shared<ExampleGenericResourceFetcher>());
  self.lynxView = builder.Build();
  [self loadTemplate];
  }

- (void)loadTemplate {
  // Call `loadTemplate` where you want.
  auto meta_data = std::make_shared<lynx::pub::LynxLoadMeta>();
  meta_data->SetUrl("https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle");
  // Load template with meta_data
  self.lynxView->LoadTemplate(meta_data);
  }

```
Then you will see the following interface on the screen:
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/hello-world-showcase-macos.png)
Congratulations, you have now completed all the work of rendering the LynxView!

## 4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our [developing](/guide/start/quick-start.md) and [debugging](/guide/devtool/panels.md) docs for in-depth insights on working with Lynx.

```
```

***

:::tip Development Tip
During development, you can use **Lynx Explorer** to quickly preview and iterate on your Lynx pages before integrating them into your native app. Switch to the [Try with Explorer](/guide/start/quick-start.md) approach to set it up.
:::

## Next Steps

[Integrate Lynx DevTool

Integrate Lynx DevTool to debug Lynx pages

](/guide/start/integrate-lynx-devtool)


---
url: /guide/start/quick-start.md
---

# Try with Explorer

Try with ExplorerRun Lynx pages in the pre-built sandbox app[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use [Lynx Explorer](https://github.com/lynx-family/lynx), a pre-built sandbox app, to start developing and previewing Lynx pages instantly, no native toolchain required. Great for learning, prototyping, and development. For production deployment, [integrate with your existing app](/guide/start/integrate-with-existing-apps.md) or [build a new app on an app framework](/guide/start/build-with-app-framework.md).

### System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

### Create a new Lynx project
We use Rspeedy (a Rspack-based Lynx build tool) to build Lynx projects.
It is recommended to start a new project using [`create-rspeedy`](https://npmjs.org/package/create-rspeedy),
which sets up everything automatically for you. To create a project, run:

```sh [npm]
npm create rspeedy@latest
```

```sh [yarn]
yarn create rspeedy
```

```sh [pnpm]
pnpm create rspeedy@latest
```

```sh [bun]
bun create rspeedy@latest
```

```sh [deno]
deno init --npm rspeedy@latest
```
After completing the prompts, `create-rspeedy` will create a folder with your project name.
### Prepare Lynx Explorer
Lynx Explorer is a sandbox for trying out Lynx quickly.
iOS SimulatorAndroidHarmonyOSWe currently only provide pre-built binaries for the iOS simulator. If you need to run Lynx Explorer on a real iOS device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide.
:::info
A version of Lynx Explorer is also available on the [App Store](https://apps.apple.com/us/app/lynx-go-dev-explorer/id6743227790), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on iOS.
:::
1. **Install Xcode**
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click Install (or Update if you have it already).
2. **<div id="download-lynx-explorer,ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator">Download LynxExplorer</div>**
macOS (arm64)macOS (x86_64)Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-arm64.app.tar.gz).
Then extract the downloaded archive:
```bash
mkdir -p LynxExplorer-arm64.app/
tar -zxf LynxExplorer-arm64.app.tar.gz -C LynxExplorer-arm64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-arm64.app" into it.
Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-x86_64.app.tar.gz).
Then, extract the downloaded archive:
```bash
mkdir -p LynxExplorer-x86_64.app/
tar -zxf LynxExplorer-x86_64.app.tar.gz -C LynxExplorer-x86_64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-x86\_64.app" into it.
Scan the QR code to download the pre-built app from [GitHub Release 3.7.0](https://github.com/lynx-family/lynx/releases/tag/3.7.0).
Or, you may build from source by following the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide.
:::info
A version of Lynx Explorer is also available on the [Play Store](https://play.google.com/store/apps/details?id=com.funcs.io.lynx.go), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on Android.
:::
We currently only provide pre-built binaries for the harmony simulator. If you need to run Lynx Explorer on a real harmony device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
1. **Install DevEco Studio**
Download the latest DevEco Studio from the [official website](https://developer.huawei.com/consumer/en/deveco-studio/).
2. **<div id="download-lynx-explorer">Download Lynx Explorer</div>**
Download the pre-built app [`lynx_explorer-default-unsigned.hap`](https://github.com/lynx-family/lynx/releases/download/3.7.0/lynx_explorer-default-unsigned.hap).
Or, you may build from source by following the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
3. **Install Lynx Explorer on Simulator**
```bash
hdc install lynx_explorer-default-unsigned.hap
```
## 

### Start developing
1. Navigate to the created project:
```bash
cd <project-name>
```
2. Install the NPM dependencies with package manager:

```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```
3. To start the development server, run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You will see a QR code showing up in the terminal, scan with your Lynx Explorer App or if you are using the simulator, just copy the bundle URL and paste it on the "Enter Card URL" input in the Lynx Explorer App and hit "Go".
4. Make your first change
Open the `src/App.tsx` file in your code editor and make a change.
You should see the UI on your Lynx Explorer being updated automatically.
**This is an example below: hello-world**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useEffect, useState } from "@lynx-js/react";

import "./App.css";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

export function App() {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
}

```



### Debugging
Visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to download and open the Lynx DevTool desktop application. Use a USB cable to connect the debugging device, and start debugging.
Visit [Debugging](/guide/devtool/panels.md), learn how to debug your Lynx app.

## Next Steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

[Tutorial

Step-by-step walkthrough of building a Gallery page with Lynx

](/learn/gallery)[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)
### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)


---
url: /guide/start/tutorial-payment-details.md
---

# 

# Tutorial: Payment Details

After completing the [Gallery](/learn/gallery.md) tutorial, you should have mastered the basics of Lynx. Now, let's learn some more advanced features through a payment details page, including:

- Building an interactive scrolling list
- How to create 3D interactive animations
- How to pass data between different components

## What are we building?

Let's first take a look at the final effect of this application. To experience it, please download and install [Lynx Explorer App](/guide/start/quick-start.md#ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator) first, then scan the QR code below.

**This is an example below: bankcards**

**Entry:** `src/final`
**Bundle:** `dist/final.lynx.bundle` | Web: `dist/final.web.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import Amount from "./Components/Amount.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view className="page">
      <Amount amount="1314" />
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



## Let's Get Started

Let's look at the composition of this page. If you want to build such a page, you can break it down into these three components and implement them step by step:

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_cards.gif)1. Card Details
   - The card can perform flip animation
   - Here we'll learn how to use CSS animations to create smooth flip effects

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_bankcards.gif)2. Card List, wrapped in a [scroll-view](/api/elements/built-in/scroll-view.md) element
   - Can scroll up and down to browse all cards
   - When clicking a card, the top card details will update with corresponding card information
   - Here we'll learn how to build an interactive scrolling list and how to pass data between components

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg)![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_pay.jpg)3. The top amount display and bottom buttons, these components are relatively simple, we'll implement them using the [view](/api/elements/built-in/view.md) element.

Let's focus on three technical points: building an interactive scrolling list, implementing 3D flip animation effects, and passing data between components.

### Building an Interactive Card List

First, let's create a bank card list. This list needs to display basic information for each card, including:

- Bank type (like Bac, Boc, etc.)
- Card number (showing first and last four digits)
- Cardholder name
- Whether it's a primary card

Let's organize this information into a data structure:

```tsx title="BankCardScrollView.tsx"
export interface BankCard {
  type: string; // Bank type (like Bac, Boc, etc.)
  number: string; // Card number
  name: string; // Cardholder name
}
```

Then, prepare some card data for display:

```tsx title="BankCardScrollView.tsx"
const cards = [
  { type: "bac", number: "4558 **** **** 6767", name: "Alex Quentin" },
  { type: "boc", number: "6222 **** **** 8058", name: "Alex Quentin" },
  ...
];
```

Next, let's use the `<scroll-view>` element to create a vertically scrollable list to display all card information:

```tsx title="BankCardScrollView.tsx" {6}
export default function BankCardScrollView() {
  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

To let users know which card they've selected, we need to add an icon to indicate selection:

```scss title="BankCardScrollView.tsx"
<image className="check-icon" src={checkIcon} />
```

Then, we need to define a `selectedCard` state to track the currently selected card:

```tsx title="BankCardScrollView.tsx"
const [selectedCard, setSelectedCard] = useState(cards[0]);
```

After that, we need to add a `handleCardSelect` function in the `<BankCardScrollView>` component to handle card selection events:

```tsx title="BankCardScrollView.tsx"
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
};
```

When a user clicks a card, it will trigger the `handleCardSelect` function, which will update the `selectedCard` state:

```tsx title="BankCardScrollView.tsx" {3}
<view
  className={`card ${selectedCard === card ? 'selected' : ''}`}
  bindtap={() => handleCardSelect(card)}
>
  ...
</view>
```

Let's combine the above logic. When a user selects a card, it will show a small check mark on the right to indicate the current selection:

```tsx title="BankCardScrollView.tsx {5,17}"
export default function BankCardScrollView() {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
              {selectedCard === card && (
                <image className="check-icon" src={checkIcon} />
              )}
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

Now, we've completed building this interactive card list. Let's see how it works!

**This is an example below: bankcards**

**Entry:** `src/step_1`
**Bundle:** `dist/step_1.lynx.bundle` | Web: `dist/step_1.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";

import "./index.scss";

function BankCards() {
  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <BankCardScrollView />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



### 3D Flip effects

Now let's recreate this interesting 3D flip effect. First, we need to understand the key steps to implement this effect — CSS animation.

:::info CSS Animation Collections in Lynx
Lynx supports various CSS animation collections. To explore more animation techniques, check out [CSS Animation](/api/css/properties/animation.md).
:::

To achieve this flip effect, we need two key steps:

First, let's create a `<Card/>` component

1. Define the flip animation:
   - Use [keyframes](/api/css/at-rule/keyframes.md) to describe the process of flipping the card from front to back (and vice versa), which includes rotation keyframes.
   - The [transform](/api/css/properties/transform.md) property defines the rotation angle of the element.

```scss title="Cards.scss" {11,15,21,25}
.front {
  animation: backToFront 0.5s both;
}

.back {
  animation: frontToBack 0.5s both;
}

@keyframes frontToBack {
  0% {
    transform: rotateY(0deg) translateZ(1);
  }

  100% {
    transform: rotateY(180deg) translateZ(0);
  }
}

@keyframes backToFront {
  0% {
    transform: rotateY(-180deg) translateZ(0);
  }

  100% {
    transform: rotateY(0deg) translateZ(1);
  }
}
```

2. Make the card responsive to clicks:
   - Trigger the flip animation when the bottom button is clicked
   - Control whether the card shows front or back by switching className

```tsx title="Cards.tsx" {5,10}
export default function Card({ isFront, isFirstRender }: CardProps) {
  return (
    <view className="card-content">
      <view className={`card-back ${isFront ? 'back' : 'front'}`}>...</view>
      <view
        className={`card-front ${!isFirstRender ? (isFront ? 'front' : 'back') : ''}`}
      >
        ...
      </view>
    </view>
  );
}
```

This way, we've created a practical and fun card flip effect! Every time users click the bottom button, they'll see a smooth flip animation, making the entire interaction experience more lively and engaging.

**This is an example below: bankcards**

**Entry:** `src/step_2`
**Bundle:** `dist/step_2.lynx.bundle` | Web: `dist/step_2.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import BottomNode from "../final/Components/BottomNode.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import Card from "./Components/Card.jsx";

import "./index.scss";

function BankCards() {
  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <Card
        isFirstRender={isFirstRender}
        isFront={isFront}
      />
      <BankCardScrollView />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



### Component Data Interaction

You might have noticed an issue: when clicking a card in the list, the card details don't update with the new card number. We need to solve this synchronization problem.

In this application, we have two main components:

- Card List: the `<BankCardScrollView/>` component that displays all available bank cards
- Card Details: the `<Card/>` component that shows detailed information of the currently selected card

When a user clicks a card in the list, the card details at the top need to synchronously update to display that card's information. To achieve this functionality, we need to enable data transmission between these two components.

First, let's define a callback function to notify other components which card the user has selected:

```tsx title="BankCardScrollView.tsx" {9}
export interface BankCardScrollViewProps {
  onCardSelect?: (card: BankCard) => void;
}
```

Then, we call this callback function in our previously defined `handleCardSelect` function:

```tsx title="BankCardScrollView.tsx" {3}
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
  onCardSelect?.(card);
};
```

Next, we add `onCardSelect` as a property in the `<BankCardScrollView>` component:

```tsx title="BankCardScrollView.tsx" {2}
export default function BankCardScrollView({
  onCardSelect,
}: BankCardScrollViewProps) {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    onCardSelect?.(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              ...
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

After handling the `<BankCardScrollView>` component, we need to handle the `<Card>` component to update the card number when switching cards in the list.

It receives a `selectedCard` property to display the details of the currently selected card, showing the last four digits of the card number.

```tsx title="Card.tsx" {4}
interface CardProps {
  isFront: boolean;
  isFirstRender: boolean;
  selectedCard: BankCard;
}
```

Let's define a utility function to extract the first and last four digits of the card number.

```tsx title="Card.tsx"
const getCardNumberParts = (number: string) => {
  const parts = number?.split(' ') || [];
  return {
    firstFour: parts[0] || '4558',
    lastFour: parts[3] || '6767',
  };
};
```

Then, we'll use this utility function to display the first and last four digits from the selectedCard number.

```tsx title="Card.tsx" {17,19}
export default function Card({
  selectedCard,
  isFront,
  isFirstRender,
}: CardProps) {
  const { firstFour, lastFour } = getCardNumberParts(selectedCard.number);

  return (
    <view className="card-content">
      <view
        className={`card-back ${!isFirstRender ? (isFront ? 'back' : 'front') : ''}`}
      >
        ...
      </view>

      <view
        className={`card-front ${!isFirstRender ? (isFront ? 'front' : 'back') : ''}`}
      >
        <view className="card-number">
          <text className="first-digits">{firstFour}</text>
          <text className="middle-digits">**** ****</text>
          <text className="last-digits">{lastFour}</text>
        </view>
        <view className="card-info">
          <text>{selectedCard?.name || 'Card holder'}</text>
        </view>
      </view>
    </view>
  );
}
```

Finally, let's combine these two components in the parent component:

1. Use `selectedCard` state to store the currently selected card
2. Update this state when the `onCardSelect` of `<BankCardScrollView>` notifies that a new card has been selected
3. Pass this state to `<Card>` to display the selected card's information

```tsx title="index.tsx" {12,26}
function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: 'visa',
    number: '4558 **** **** 6767',
    name: 'Alex Quentin',
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view class="page">
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}
```

This way, we've established an efficient collaboration mechanism:

1. User selects a card from the card list
2. Card list immediately notifies the parent component
3. Parent component updates the state and notifies the card details component
4. Card details component immediately updates its display

Let's see this seamless coordination in action:

**This is an example below: bankcards**

**Entry:** `src/step_3`
**Bundle:** `dist/step_3.lynx.bundle` | Web: `dist/step_3.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



We'll add the top amount display, and we're done!

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg)
**This is an example below: bankcards**

**Entry:** `src/final`
**Bundle:** `dist/final.lynx.bundle` | Web: `dist/final.web.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import Amount from "./Components/Amount.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view className="page">
      <Amount amount="1314" />
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



## Summary

Through implementing this payment details page, you've mastered these core technical points:

- Building interactive lists
- Developing complex CSS animation effects
- Implementing data transmission between components

Now you're ready to develop more complex applications with Lynx.



---
url: /api/index.md
---

# API Reference

## @lynx-js/react

### [Built-in Macros](/api/react/Document.built-in-macros.md)

- [`__BACKGROUND__`](/api/react/Document.built-in-macros.md#__background__)
- [`__MAIN_THREAD__`](/api/react/Document.built-in-macros.md#__main_thread__)

### [Directives](/api/react/Document.directives.md)

- [`'background only'`](/api/react/Document.directives.md#background-only)
- [`'main thread'`](/api/react/Document.directives.md#main-thread)

### [Global Events](/api/react/Document.global-events.md)

- [onGlobalPropsChanged](/api/react/Document.global-events.md#onglobalpropschanged)
- [onDataChanged](/api/react/Document.global-events.md#ondatachanged)

### [Import Attributes](/api/react/Document.import-attributes.md)

- [`runtime: 'shared'`](/api/react/Document.import-attributes.md#runtime-shared)

### [Class: Component\<P, S, SS\>](/api/react/Class.Component.md)

- [Extends](/api/react/Class.Component.md#extends)
- [Extended by](/api/react/Class.Component.md#extended-by)
- [Type Parameters](/api/react/Class.Component.md#type-parameters)
- [Constructors](/api/react/Class.Component.md#constructors)
- [Properties](/api/react/Class.Component.md#properties)
- [Methods](/api/react/Class.Component.md#methods)

### [Class: MainThreadRef\<T\>](/api/react/Class.MainThreadRef.md)

- [Extends](/api/react/Class.MainThreadRef.md#extends)
- [Type Parameters](/api/react/Class.MainThreadRef.md#type-parameters)
- [Constructors](/api/react/Class.MainThreadRef.md#constructors)
- [Accessors](/api/react/Class.MainThreadRef.md#accessors)

### [Class: PureComponent\<P, S, SS\>](/api/react/Class.PureComponent.md)

- [Extends](/api/react/Class.PureComponent.md#extends)
- [Type Parameters](/api/react/Class.PureComponent.md#type-parameters)
- [Constructors](/api/react/Class.PureComponent.md#constructors)
- [Properties](/api/react/Class.PureComponent.md#properties)
- [Methods](/api/react/Class.PureComponent.md#methods)

### [Function: cloneElement()](/api/react/Function.cloneElement.md)

- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-1)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-2)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-3)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-4)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-5)
- [cloneElement(element, props, children)](/api/react/Function.cloneElement.md#cloneelementelement-props-children-6)

### [Function: createContext()](/api/react/Function.createContext.md)

- [Type Parameters](/api/react/Function.createContext.md#type-parameters)
- [Parameters](/api/react/Function.createContext.md#parameters)
- [Returns](/api/react/Function.createContext.md#returns)
- [See](/api/react/Function.createContext.md#see)
- [Example](/api/react/Function.createContext.md#example)
- [Defined in](/api/react/Function.createContext.md#defined-in)

### [Function: createElement()](/api/react/Function.createElement.md)

- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-1)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-2)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-3)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-4)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-5)
- [createElement(type, props, children)](/api/react/Function.createElement.md#createelementtype-props-children-6)

### [Function: createPortal()](/api/react/Function.createPortal.md)

- [Parameters](/api/react/Function.createPortal.md#parameters)
- [Returns](/api/react/Function.createPortal.md#returns)
- [Defined in](/api/react/Function.createPortal.md#defined-in)

### [Function: createRef()](/api/react/Function.createRef.md)

- [Type Parameters](/api/react/Function.createRef.md#type-parameters)
- [Returns](/api/react/Function.createRef.md#returns)
- [Defined in](/api/react/Function.createRef.md#defined-in)

### [Function: forwardRef()](/api/react/Function.forwardRef.md)

- [Type Parameters](/api/react/Function.forwardRef.md#type-parameters)
- [Parameters](/api/react/Function.forwardRef.md#parameters)
- [Returns](/api/react/Function.forwardRef.md#returns)
- [See](/api/react/Function.forwardRef.md#see)
- [Example](/api/react/Function.forwardRef.md#example)
- [Defined in](/api/react/Function.forwardRef.md#defined-in)

### [Function: Fragment()](/api/react/Function.Fragment.md)

- [Parameters](/api/react/Function.Fragment.md#parameters)
- [Returns](/api/react/Function.Fragment.md#returns)
- [See](/api/react/Function.Fragment.md#see)
- [Examples](/api/react/Function.Fragment.md#examples)
- [Defined in](/api/react/Function.Fragment.md#defined-in)

### [Function: GlobalPropsConsumer()](/api/react/Function.GlobalPropsConsumer.md)

- [Parameters](/api/react/Function.GlobalPropsConsumer.md#parameters)
- [Returns](/api/react/Function.GlobalPropsConsumer.md#returns)
- [Defined in](/api/react/Function.GlobalPropsConsumer.md#defined-in)

### [Function: GlobalPropsProvider()](/api/react/Function.GlobalPropsProvider.md)

- [Parameters](/api/react/Function.GlobalPropsProvider.md#parameters)
- [Returns](/api/react/Function.GlobalPropsProvider.md#returns)
- [Example](/api/react/Function.GlobalPropsProvider.md#example)
- [Defined in](/api/react/Function.GlobalPropsProvider.md#defined-in)

### [Function: InitDataConsumer()](/api/react/Function.InitDataConsumer.md)

- [Parameters](/api/react/Function.InitDataConsumer.md#parameters)
- [Returns](/api/react/Function.InitDataConsumer.md#returns)
- [Defined in](/api/react/Function.InitDataConsumer.md#defined-in)

### [Function: InitDataProvider()](/api/react/Function.InitDataProvider.md)

- [Parameters](/api/react/Function.InitDataProvider.md#parameters)
- [Returns](/api/react/Function.InitDataProvider.md#returns)
- [Example](/api/react/Function.InitDataProvider.md#example)
- [Defined in](/api/react/Function.InitDataProvider.md#defined-in)

### [Function: isValidElement()](/api/react/Function.isValidElement.md)

- [Type Parameters](/api/react/Function.isValidElement.md#type-parameters)
- [Parameters](/api/react/Function.isValidElement.md#parameters)
- [Returns](/api/react/Function.isValidElement.md#returns)
- [Defined in](/api/react/Function.isValidElement.md#defined-in)

### [Function: lazy()](/api/react/Function.lazy.md)

- [Type Parameters](/api/react/Function.lazy.md#type-parameters)
- [Parameters](/api/react/Function.lazy.md#parameters)
- [Returns](/api/react/Function.lazy.md#returns)
- [See](/api/react/Function.lazy.md#see)
- [Example](/api/react/Function.lazy.md#example)
- [Defined in](/api/react/Function.lazy.md#defined-in)

### [Function: memo()](/api/react/Function.memo.md)

- [memo(Component, propsAreEqual)](/api/react/Function.memo.md#memocomponent-propsareequal)
- [memo(Component, propsAreEqual)](/api/react/Function.memo.md#memocomponent-propsareequal-1)

### [Function: runOnBackground()](/api/react/Function.runOnBackground.md)

- [Type Parameters](/api/react/Function.runOnBackground.md#type-parameters)
- [Parameters](/api/react/Function.runOnBackground.md#parameters)
- [Returns](/api/react/Function.runOnBackground.md#returns)
- [Example](/api/react/Function.runOnBackground.md#example)
- [Defined in](/api/react/Function.runOnBackground.md#defined-in)

### [Function: runOnMainThread()](/api/react/Function.runOnMainThread.md)

- [Type Parameters](/api/react/Function.runOnMainThread.md#type-parameters)
- [Parameters](/api/react/Function.runOnMainThread.md#parameters)
- [Returns](/api/react/Function.runOnMainThread.md#returns)
- [Example](/api/react/Function.runOnMainThread.md#example)
- [Defined in](/api/react/Function.runOnMainThread.md#defined-in)

### [Function: Suspense()](/api/react/Function.Suspense.md)

- [Parameters](/api/react/Function.Suspense.md#parameters)
- [Returns](/api/react/Function.Suspense.md#returns)
- [See](/api/react/Function.Suspense.md#see)
- [Example](/api/react/Function.Suspense.md#example)
- [Defined in](/api/react/Function.Suspense.md#defined-in)

### [Function: useCallback()](/api/react/Function.useCallback.md)

- [Type Parameters](/api/react/Function.useCallback.md#type-parameters)
- [Parameters](/api/react/Function.useCallback.md#parameters)
- [Returns](/api/react/Function.useCallback.md#returns)
- [Version](/api/react/Function.useCallback.md#version)
- [See](/api/react/Function.useCallback.md#see)
- [Defined in](/api/react/Function.useCallback.md#defined-in)

### [Function: useContext()](/api/react/Function.useContext.md)

- [Type Parameters](/api/react/Function.useContext.md#type-parameters)
- [Parameters](/api/react/Function.useContext.md#parameters)
- [Returns](/api/react/Function.useContext.md#returns)
- [Version](/api/react/Function.useContext.md#version)
- [See](/api/react/Function.useContext.md#see)
- [Defined in](/api/react/Function.useContext.md#defined-in)

### [Function: useDebugValue()](/api/react/Function.useDebugValue.md)

- [Type Parameters](/api/react/Function.useDebugValue.md#type-parameters)
- [Parameters](/api/react/Function.useDebugValue.md#parameters)
- [Returns](/api/react/Function.useDebugValue.md#returns)
- [Version](/api/react/Function.useDebugValue.md#version)
- [See](/api/react/Function.useDebugValue.md#see)
- [Defined in](/api/react/Function.useDebugValue.md#defined-in)

### [Function: useEffect()](/api/react/Function.useEffect.md)

- [Parameters](/api/react/Function.useEffect.md#parameters)
- [Returns](/api/react/Function.useEffect.md#returns)
- [Defined in](/api/react/Function.useEffect.md#defined-in)

### [Function: useGlobalProps()](/api/react/Function.useGlobalProps.md)

- [Returns](/api/react/Function.useGlobalProps.md#returns)
- [Example](/api/react/Function.useGlobalProps.md#example)
- [Defined in](/api/react/Function.useGlobalProps.md#defined-in)

### [Function: useGlobalPropsChanged()](/api/react/Function.useGlobalPropsChanged.md)

- [Parameters](/api/react/Function.useGlobalPropsChanged.md#parameters)
- [Returns](/api/react/Function.useGlobalPropsChanged.md#returns)
- [Example](/api/react/Function.useGlobalPropsChanged.md#example)
- [Defined in](/api/react/Function.useGlobalPropsChanged.md#defined-in)

### [Function: useImperativeHandle()](/api/react/Function.useImperativeHandle.md)

- [Type Parameters](/api/react/Function.useImperativeHandle.md#type-parameters)
- [Parameters](/api/react/Function.useImperativeHandle.md#parameters)
- [Returns](/api/react/Function.useImperativeHandle.md#returns)
- [Version](/api/react/Function.useImperativeHandle.md#version)
- [See](/api/react/Function.useImperativeHandle.md#see)
- [Defined in](/api/react/Function.useImperativeHandle.md#defined-in)

### [Function: useInitData()](/api/react/Function.useInitData.md)

- [Returns](/api/react/Function.useInitData.md#returns)
- [Example](/api/react/Function.useInitData.md#example)
- [Defined in](/api/react/Function.useInitData.md#defined-in)

### [Function: useInitDataChanged()](/api/react/Function.useInitDataChanged.md)

- [Parameters](/api/react/Function.useInitDataChanged.md#parameters)
- [Returns](/api/react/Function.useInitDataChanged.md#returns)
- [Example](/api/react/Function.useInitDataChanged.md#example)
- [Defined in](/api/react/Function.useInitDataChanged.md#defined-in)

### [Function: ~~useLayoutEffect()~~](/api/react/Function.useLayoutEffect.md)

- [Parameters](/api/react/Function.useLayoutEffect.md#parameters)
- [Returns](/api/react/Function.useLayoutEffect.md#returns)
- [Deprecated](/api/react/Function.useLayoutEffect.md#deprecated)
- [Defined in](/api/react/Function.useLayoutEffect.md#defined-in)

### [Function: useLynxGlobalEventListener()](/api/react/Function.useLynxGlobalEventListener.md)

- [Type Parameters](/api/react/Function.useLynxGlobalEventListener.md#type-parameters)
- [Parameters](/api/react/Function.useLynxGlobalEventListener.md#parameters)
- [Returns](/api/react/Function.useLynxGlobalEventListener.md#returns)
- [Example](/api/react/Function.useLynxGlobalEventListener.md#example)
- [Defined in](/api/react/Function.useLynxGlobalEventListener.md#defined-in)

### [Function: useMainThreadRef()](/api/react/Function.useMainThreadRef.md)

- [useMainThreadRef(initValue)](/api/react/Function.useMainThreadRef.md#usemainthreadrefinitvalue)
- [useMainThreadRef(initValue)](/api/react/Function.useMainThreadRef.md#usemainthreadrefinitvalue-1)
- [useMainThreadRef()](/api/react/Function.useMainThreadRef.md#usemainthreadref)

### [Function: useMemo()](/api/react/Function.useMemo.md)

- [Type Parameters](/api/react/Function.useMemo.md#type-parameters)
- [Parameters](/api/react/Function.useMemo.md#parameters)
- [Returns](/api/react/Function.useMemo.md#returns)
- [Version](/api/react/Function.useMemo.md#version)
- [See](/api/react/Function.useMemo.md#see)
- [Defined in](/api/react/Function.useMemo.md#defined-in)

### [Function: useReducer()](/api/react/Function.useReducer.md)

- [useReducer(reducer, initializerArg, initializer)](/api/react/Function.useReducer.md#usereducerreducer-initializerarg-initializer)
- [useReducer(reducer, initializerArg, initializer)](/api/react/Function.useReducer.md#usereducerreducer-initializerarg-initializer-1)
- [useReducer(reducer, initializerArg, initializer)](/api/react/Function.useReducer.md#usereducerreducer-initializerarg-initializer-2)
- [useReducer(reducer, initializerArg, initializer)](/api/react/Function.useReducer.md#usereducerreducer-initializerarg-initializer-3)
- [useReducer(reducer, initialState, initializer)](/api/react/Function.useReducer.md#usereducerreducer-initialstate-initializer)

### [Function: useRef()](/api/react/Function.useRef.md)

- [useRef(initialValue)](/api/react/Function.useRef.md#userefinitialvalue)
- [useRef(initialValue)](/api/react/Function.useRef.md#userefinitialvalue-1)
- [useRef(initialValue)](/api/react/Function.useRef.md#userefinitialvalue-2)

### [Function: useState()](/api/react/Function.useState.md)

- [useState(initialState)](/api/react/Function.useState.md#usestateinitialstate)
- [useState()](/api/react/Function.useState.md#usestate)

### [Function: useSyncExternalStore()](/api/react/Function.useSyncExternalStore.md)

- [Type Parameters](/api/react/Function.useSyncExternalStore.md#type-parameters)
- [Parameters](/api/react/Function.useSyncExternalStore.md#parameters)
- [Returns](/api/react/Function.useSyncExternalStore.md#returns)
- [See](/api/react/Function.useSyncExternalStore.md#see)
- [Defined in](/api/react/Function.useSyncExternalStore.md#defined-in)

### [Function: withInitDataInState()](/api/react/Function.withInitDataInState.md)

- [Type Parameters](/api/react/Function.withInitDataInState.md#type-parameters)
- [Parameters](/api/react/Function.withInitDataInState.md#parameters)
- [Returns](/api/react/Function.withInitDataInState.md#returns)
- [Example](/api/react/Function.withInitDataInState.md#example)
- [Defined in](/api/react/Function.withInitDataInState.md#defined-in)

### [Interface: DataProcessorDefinition](/api/react/Interface.DataProcessorDefinition.md)

- [Properties](/api/react/Interface.DataProcessorDefinition.md#properties)

### [Interface: DataProcessors](/api/react/Interface.DataProcessors.md)

- [Example](/api/react/Interface.DataProcessors.md#example)
- [Indexable](/api/react/Interface.DataProcessors.md#indexable)
- [Methods](/api/react/Interface.DataProcessors.md#methods)

### [Interface: GlobalProps](/api/react/Interface.GlobalProps.md)

### [Interface: InitData](/api/react/Interface.InitData.md)

### [Interface: InitDataRaw](/api/react/Interface.InitDataRaw.md)

### [Interface: Lynx](/api/react/Interface.Lynx.md)

- [Example](/api/react/Interface.Lynx.md#example)
- [Properties](/api/react/Interface.Lynx.md#properties)

### [Interface: Root](/api/react/Interface.Root.md)

- [Properties](/api/react/Interface.Root.md#properties)

### [Variable: root](/api/react/Variable.root.md)

- [Example](/api/react/Variable.root.md#example)
- [Defined in](/api/react/Variable.root.md#defined-in)

### [Variable: useErrorBoundary](/api/react/Variable.useErrorBoundary.md)
## lynx.config.js

### [environments](/api/rspeedy/rspeedy.config.environments.md)

- [Config.environments property](/api/rspeedy/rspeedy.config.environments.md#configenvironments-property)
- [Default Value](/api/rspeedy/rspeedy.config.environments.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.config.environments.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.config.environments.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.config.environments.md#example-2)

### [mode](/api/rspeedy/rspeedy.config.mode.md)

- [Config.mode property](/api/rspeedy/rspeedy.config.mode.md#configmode-property)
- [Default Value](/api/rspeedy/rspeedy.config.mode.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.config.mode.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.config.mode.md#example-2)

### [dev](/api/rspeedy/rspeedy.dev.md)

- [Dev interface](/api/rspeedy/rspeedy.dev.md#dev-interface)
- [Properties](/api/rspeedy/rspeedy.dev.md#properties)

### [output](/api/rspeedy/rspeedy.output.md)

- [Output interface](/api/rspeedy/rspeedy.output.md#output-interface)
- [Properties](/api/rspeedy/rspeedy.output.md#properties)

### [performance](/api/rspeedy/rspeedy.performance.md)

- [Performance interface](/api/rspeedy/rspeedy.performance.md#performance-interface)
- [Properties](/api/rspeedy/rspeedy.performance.md#properties)

### [resolve](/api/rspeedy/rspeedy.resolve.md)

- [Resolve interface](/api/rspeedy/rspeedy.resolve.md#resolve-interface)
- [Properties](/api/rspeedy/rspeedy.resolve.md#properties)

### [server](/api/rspeedy/rspeedy.server.md)

- [Server interface](/api/rspeedy/rspeedy.server.md#server-interface)
- [Properties](/api/rspeedy/rspeedy.server.md#properties)

### [source](/api/rspeedy/rspeedy.source.md)

- [Source interface](/api/rspeedy/rspeedy.source.md#source-interface)
- [Properties](/api/rspeedy/rspeedy.source.md#properties)

### [splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md)

- [Config.splitChunks property](/api/rspeedy/rspeedy.config.splitchunks.md#configsplitchunks-property)
- [Default Value](/api/rspeedy/rspeedy.config.splitchunks.md#default-value)

### [tools](/api/rspeedy/rspeedy.tools.md)

- [Tools interface](/api/rspeedy/rspeedy.tools.md#tools-interface)
- [Properties](/api/rspeedy/rspeedy.tools.md#properties)
## Rspeedy Plugins

### [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

### [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md)

### [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md)

- [external-bundle-rsbuild-plugin package](/api/rspeedy/external-bundle-rsbuild-plugin.md#external-bundle-rsbuild-plugin-package)
- [Functions](/api/rspeedy/external-bundle-rsbuild-plugin.md#functions)
- [Interfaces](/api/rspeedy/external-bundle-rsbuild-plugin.md#interfaces)
- [Variables](/api/rspeedy/external-bundle-rsbuild-plugin.md#variables)
- [Type Aliases](/api/rspeedy/external-bundle-rsbuild-plugin.md#type-aliases)

### [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md)

- [lynx-bundle-rslib-config package](/api/rspeedy/lynx-bundle-rslib-config.md#lynx-bundle-rslib-config-package)
- [Classes](/api/rspeedy/lynx-bundle-rslib-config.md#classes)
- [Functions](/api/rspeedy/lynx-bundle-rslib-config.md#functions)
- [Interfaces](/api/rspeedy/lynx-bundle-rslib-config.md#interfaces)
- [Variables](/api/rspeedy/lynx-bundle-rslib-config.md#variables)
- [Type Aliases](/api/rspeedy/lynx-bundle-rslib-config.md#type-aliases)
## Elements

### [<view>](/api/elements/built-in/view.md)

### [<text>](/api/elements/built-in/text.md)

### [<image>](/api/elements/built-in/image.md)

### [<scroll-view>](/api/elements/built-in/scroll-view.md)

### [<list>](/api/elements/built-in/list.md)

### [<page>](/api/elements/built-in/page.md)

### [<frame>](/api/elements/built-in/frame.md)

### [<input>](/api/elements/built-in/input.md)

### [<textarea>](/api/elements/built-in/textarea.md)

### [<overlay>](/api/elements/built-in/overlay.md)

### [<svg>](/api/elements/built-in/svg.md)

### [<refresh>](/api/elements/built-in/refresh.md)

### [<title-bar-view>](/api/elements/built-in/title-bar-view.md)
## Properties

### [-x-auto-font-size-line-ranges](/api/css/properties/-x-auto-font-size-line-ranges.md)

### [-x-auto-font-size-preset-sizes](/api/css/properties/-x-auto-font-size-preset-sizes.md)

### [-x-auto-font-size](/api/css/properties/-x-auto-font-size.md)

### [-x-handle-color](/api/css/properties/-x-handle-color.md)

### [-x-handle-size](/api/css/properties/-x-handle-size.md)

### [align-content](/api/css/properties/align-content.md)

### [align-items](/api/css/properties/align-items.md)

### [align-self](/api/css/properties/align-self.md)

### [animation-delay](/api/css/properties/animation-delay.md)

### [animation-direction](/api/css/properties/animation-direction.md)

### [animation-duration](/api/css/properties/animation-duration.md)

### [animation-fill-mode](/api/css/properties/animation-fill-mode.md)

### [animation-iteration-count](/api/css/properties/animation-iteration-count.md)

### [animation-name](/api/css/properties/animation-name.md)

### [animation-play-state](/api/css/properties/animation-play-state.md)

### [animation-timing-function](/api/css/properties/animation-timing-function.md)

### [animation](/api/css/properties/animation.md)

### [aspect-ratio](/api/css/properties/aspect-ratio.md)

### [background-clip](/api/css/properties/background-clip.md)

### [background-color](/api/css/properties/background-color.md)

### [background-image](/api/css/properties/background-image.md)

### [background-origin](/api/css/properties/background-origin.md)

### [background-position](/api/css/properties/background-position.md)

### [background-repeat](/api/css/properties/background-repeat.md)

### [background-size](/api/css/properties/background-size.md)

### [background](/api/css/properties/background.md)

### [border-bottom-color](/api/css/properties/border-bottom-color.md)

### [border-bottom-left-radius](/api/css/properties/border-bottom-left-radius.md)

### [border-bottom-right-radius](/api/css/properties/border-bottom-right-radius.md)

### [border-bottom-style](/api/css/properties/border-bottom-style.md)

### [border-bottom-width](/api/css/properties/border-bottom-width.md)

### [border-bottom](/api/css/properties/border-bottom.md)

### [border-color](/api/css/properties/border-color.md)

### [border-end-end-radius](/api/css/properties/border-end-end-radius.md)

### [border-end-start-radius](/api/css/properties/border-end-start-radius.md)

### [border-inline-end-color](/api/css/properties/border-inline-end-color.md)

### [border-inline-end-style](/api/css/properties/border-inline-end-style.md)

### [border-inline-end-width](/api/css/properties/border-inline-end-width.md)

### [border-inline-start-color](/api/css/properties/border-inline-start-color.md)

### [border-inline-start-style](/api/css/properties/border-inline-start-style.md)

### [border-inline-start-width](/api/css/properties/border-inline-start-width.md)

### [border-left-color](/api/css/properties/border-left-color.md)

### [border-left-style](/api/css/properties/border-left-style.md)

### [border-left-width](/api/css/properties/border-left-width.md)

### [border-left](/api/css/properties/border-left.md)

### [border-radius](/api/css/properties/border-radius.md)

### [border-right-color](/api/css/properties/border-right-color.md)

### [border-right-style](/api/css/properties/border-right-style.md)

### [border-right-width](/api/css/properties/border-right-width.md)

### [border-right](/api/css/properties/border-right.md)

### [border-start-end-radius](/api/css/properties/border-start-end-radius.md)

### [border-start-start-radius](/api/css/properties/border-start-start-radius.md)

### [border-style](/api/css/properties/border-style.md)

### [border-top-color](/api/css/properties/border-top-color.md)

### [border-top-left-radius](/api/css/properties/border-top-left-radius.md)

### [border-top-right-radius](/api/css/properties/border-top-right-radius.md)

### [border-top-style](/api/css/properties/border-top-style.md)

### [border-top-width](/api/css/properties/border-top-width.md)

### [border-top](/api/css/properties/border-top.md)

### [border-width](/api/css/properties/border-width.md)

### [border](/api/css/properties/border.md)

### [bottom](/api/css/properties/bottom.md)

### [box-shadow](/api/css/properties/box-shadow.md)

### [box-sizing](/api/css/properties/box-sizing.md)

### [clip-path](/api/css/properties/clip-path.md)

### [color](/api/css/properties/color.md)

### [column-gap (grid-column-gap)](/api/css/properties/column-gap.md)

### [Custom properties (`--*`): CSS variables](/api/css/properties/css-variable.md)

### [cursor](/api/css/properties/cursor.md)

### [direction](/api/css/properties/direction.md)

### [display](/api/css/properties/display.md)

### [filter](/api/css/properties/filter.md)

### [flex-basis](/api/css/properties/flex-basis.md)

### [flex-direction](/api/css/properties/flex-direction.md)

### [flex-flow](/api/css/properties/flex-flow.md)

### [flex-grow](/api/css/properties/flex-grow.md)

### [flex-shrink](/api/css/properties/flex-shrink.md)

### [flex-wrap](/api/css/properties/flex-wrap.md)

### [flex](/api/css/properties/flex.md)

### [font-family](/api/css/properties/font-family.md)

### [font-feature-settings](/api/css/properties/font-feature-settings.md)

### [font-optical-sizing](/api/css/properties/font-optical-sizing.md)

### [font-size](/api/css/properties/font-size.md)

### [font-style](/api/css/properties/font-style.md)

### [font-variation-settings](/api/css/properties/font-variation-settings.md)

### [font-weight](/api/css/properties/font-weight.md)

### [gap](/api/css/properties/gap.md)

### [grid-auto-columns](/api/css/properties/grid-auto-columns.md)

### [grid-auto-flow](/api/css/properties/grid-auto-flow.md)

### [grid-auto-rows](/api/css/properties/grid-auto-rows.md)

### [grid-column-end](/api/css/properties/grid-column-end.md)

### [grid-column-span](/api/css/properties/grid-column-span.md)

### [grid-column-start](/api/css/properties/grid-column-start.md)

### [grid-row-end](/api/css/properties/grid-row-end.md)

### [grid-row-span](/api/css/properties/grid-row-span.md)

### [grid-row-start](/api/css/properties/grid-row-start.md)

### [grid-template-columns](/api/css/properties/grid-template-columns.md)

### [grid-template-rows](/api/css/properties/grid-template-rows.md)

### [height](/api/css/properties/height.md)

### [image-rendering](/api/css/properties/image-rendering.md)

### [inset-inline-end](/api/css/properties/inset-inline-end.md)

### [inset-inline-start](/api/css/properties/inset-inline-start.md)

### [justify-content](/api/css/properties/justify-content.md)

### [justify-items](/api/css/properties/justify-items.md)

### [justify-self](/api/css/properties/justify-self.md)

### [left](/api/css/properties/left.md)

### [letter-spacing](/api/css/properties/letter-spacing.md)

### [line-height](/api/css/properties/line-height.md)

### [linear-cross-gravity](/api/css/properties/linear-cross-gravity.md)

### [linear-direction](/api/css/properties/linear-direction.md)

### [linear-gravity](/api/css/properties/linear-gravity.md)

### [linear-layout-gravity](/api/css/properties/linear-layout-gravity.md)

### [linear-weight-sum](/api/css/properties/linear-weight-sum.md)

### [linear-weight](/api/css/properties/linear-weight.md)

### [margin-bottom](/api/css/properties/margin-bottom.md)

### [margin-inline-end](/api/css/properties/margin-inline-end.md)

### [margin-inline-start](/api/css/properties/margin-inline-start.md)

### [margin-left](/api/css/properties/margin-left.md)

### [margin-right](/api/css/properties/margin-right.md)

### [margin-top](/api/css/properties/margin-top.md)

### [margin](/api/css/properties/margin.md)

### [mask-image](/api/css/properties/mask-image.md)

### [mask](/api/css/properties/mask.md)

### [max-height](/api/css/properties/max-height.md)

### [max-width](/api/css/properties/max-width.md)

### [min-height](/api/css/properties/min-height.md)

### [min-width](/api/css/properties/min-width.md)

### [opacity](/api/css/properties/opacity.md)

### [order](/api/css/properties/order.md)

### [overflow-x](/api/css/properties/overflow-x.md)

### [overflow-y](/api/css/properties/overflow-y.md)

### [overflow](/api/css/properties/overflow.md)

### [padding-bottom](/api/css/properties/padding-bottom.md)

### [padding-inline-end](/api/css/properties/padding-inline-end.md)

### [padding-inline-start](/api/css/properties/padding-inline-start.md)

### [padding-left](/api/css/properties/padding-left.md)

### [padding-right](/api/css/properties/padding-right.md)

### [padding-top](/api/css/properties/padding-top.md)

### [padding](/api/css/properties/padding.md)

### [perspective](/api/css/properties/perspective.md)

### [pointer-events](/api/css/properties/pointer-events.md)

### [position](/api/css/properties/position.md)

### [relative-align-bottom](/api/css/properties/relative-align-bottom.md)

### [relative-align-inline-end](/api/css/properties/relative-align-inline-end.md)

### [relative-align-inline-start](/api/css/properties/relative-align-inline-start.md)

### [relative-align-left](/api/css/properties/relative-align-left.md)

### [relative-align-right](/api/css/properties/relative-align-right.md)

### [relative-align-top](/api/css/properties/relative-align-top.md)

### [relative-bottom-of](/api/css/properties/relative-bottom-of.md)

### [relative-center](/api/css/properties/relative-center.md)

### [relative-id](/api/css/properties/relative-id.md)

### [relative-inline-end-of](/api/css/properties/relative-inline-end-of.md)

### [relative-inline-start-of](/api/css/properties/relative-inline-start-of.md)

### [relative-layout-once](/api/css/properties/relative-layout-once.md)

### [relative-left-of](/api/css/properties/relative-left-of.md)

### [relative-right-of](/api/css/properties/relative-right-of.md)

### [relative-top-of](/api/css/properties/relative-top-of.md)

### [right](/api/css/properties/right.md)

### [row-gap (grid-row-gap)](/api/css/properties/row-gap.md)

### [text-align](/api/css/properties/text-align.md)

### [text-decoration](/api/css/properties/text-decoration.md)

### [text-indent](/api/css/properties/text-indent.md)

### [text-overflow](/api/css/properties/text-overflow.md)

### [text-shadow](/api/css/properties/text-shadow.md)

### [text-stroke-color](/api/css/properties/text-stroke-color.md)

### [text-stroke-width](/api/css/properties/text-stroke-width.md)

### [text-stroke](/api/css/properties/text-stroke.md)

### [top](/api/css/properties/top.md)

### [transform-origin](/api/css/properties/transform-origin.md)

### [transform](/api/css/properties/transform.md)

### [transition-delay](/api/css/properties/transition-delay.md)

### [transition-duration](/api/css/properties/transition-duration.md)

### [transition-property](/api/css/properties/transition-property.md)

### [transition-timing-function](/api/css/properties/transition-timing-function.md)

### [transition](/api/css/properties/transition.md)

### [vertical-align](/api/css/properties/vertical-align.md)

### [visibility](/api/css/properties/visibility.md)

### [white-space](/api/css/properties/white-space.md)

### [width](/api/css/properties/width.md)

### [word-break](/api/css/properties/word-break.md)

### [z-index](/api/css/properties/z-index.md)
## At-rules

### [@font-face](/api/css/at-rule/font-face.md)

### [@import](/api/css/at-rule/import.md)

### [@keyframes](/api/css/at-rule/keyframes.md)
## Data types

### [`<angle>`](/api/css/data-type/angle.md)

### [`<color>`](/api/css/data-type/color.md)

### [`<fit-content>`](/api/css/data-type/fit-content.md)

### [`<gradient>`](/api/css/data-type/gradient.md)

### [`<length-percentage>`](/api/css/data-type/length-percentage.md)

### [`<length>`](/api/css/data-type/length.md)

### [`<max-content>`](/api/css/data-type/max-content.md)

### [`<number>`](/api/css/data-type/number.md)

### [`<percentage>`](/api/css/data-type/percentage.md)

### [`<string>`](/api/css/data-type/string.md)

### [`<time>`](/api/css/data-type/time.md)
## Selectors

### [Selectors](/api/css/selectors.md)

- [Selectors](/api/css/selectors.md#selectors)
- [Combinator](/api/css/selectors.md#combinator)
- [Pseudo](/api/css/selectors.md#pseudo)
- [Pseudo-element](/api/css/selectors.md#pseudo-element)
- [Troubleshooting](/api/css/selectors.md#troubleshooting)
## Event

### [AnimationEvent](/api/lynx-api/event/animation-event.md)

### [CustomEvent](/api/lynx-api/event/custom-event.md)

### [Event](/api/lynx-api/event/event.md)

### [GlobalEvent](/api/lynx-api/event/global-event.md)

### [KeyEvent](/api/lynx-api/event/key-event.md)

### [MemoryEvent](/api/lynx-api/event/memory-event.md)

### [MouseEvent](/api/lynx-api/event/mouse-event.md)

### [TouchEvent](/api/lynx-api/event/touch-event.md)

### [WheelEvent](/api/lynx-api/event/wheel-event.md)
## Global

### [clearInterval()](/api/lynx-api/global/clear-interval.md)

### [clearTimeout()](/api/lynx-api/global/clear-timeout.md)

### [console](/api/lynx-api/global/console/assert.md)

### [fetch](/api/lynx-api/global/fetch.md)

### [setInterval()](/api/lynx-api/global/set-interval.md)

### [setTimeout()](/api/lynx-api/global/set-timeout.md)

### [SystemInfo](/api/lynx-api/global/system-info.md)
## IntersectionObserver

### [disconnect()](/api/lynx-api/intersection-observer/intersection-observer-disconnect.md)

### [observe()](/api/lynx-api/intersection-observer/intersection-observer-observe.md)

### [relativeToScreen()](/api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md)

### [relativeToViewport()](/api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md)

### [relativeTo()](/api/lynx-api/intersection-observer/intersection-observer-relative-to.md)
## Lynx

### [accessibilityAnnounce()](/api/lynx-api/lynx/lynx-accessibility-announce.md)

### [addFont()](/api/lynx-api/lynx/lynx-add-font.md)

### [animate()](/api/lynx-api/lynx/lynx-animate-api.md)

### [BeforePublishEvent](/api/lynx-api/lynx/lynx-before-publish-event.md)

### [cancelAnimationFrame()](/api/lynx-api/lynx/lynx-cancel-animation-frame.md)

### [cancelResourcePrefetch()](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md)

### [createIntersectionObserver()](/api/lynx-api/lynx/lynx-create-intersection-observer.md)

### [createSelectorQuery()](/api/lynx-api/lynx/lynx-create-selector-query.md)

### [getElementById()](/api/lynx-api/lynx/lynx-get-element-by-id.md)

### [getJSModule()](/api/lynx-api/lynx/lynx-get-js-module.md)

### [getSessionStorageItem](/api/lynx-api/lynx/lynx-get-session-storage.md)

### [getTextInfo()](/api/lynx-api/lynx/lynx-get-text-info.md)

### [GlobalProps](/api/lynx-api/lynx/lynx-global-props.md)

### [performance](/api/lynx-api/lynx/lynx-performance.md)

### [queueMicrotask()](/api/lynx-api/lynx/lynx-queue-microtask.md)

### [registerModule()](/api/lynx-api/lynx/lynx-register-module.md)

### [reload()](/api/lynx-api/lynx/lynx-reload.md)

### [reportError()](/api/lynx-api/lynx/lynx-report-error.md)

### [requestAnimationFrame()](/api/lynx-api/lynx/lynx-request-animation-frame.md)

### [requestResourcePrefetch()](/api/lynx-api/lynx/lynx-request-resource-prefetch.md)

### [requireModuleAsync()](/api/lynx-api/lynx/lynx-require-module-async.md)

### [requireModule()](/api/lynx-api/lynx/lynx-require-module.md)

### [resumeExposure()](/api/lynx-api/lynx/lynx-resume-exposure.md)

### [setObserverFrameRate()](/api/lynx-api/lynx/lynx-set-observer-frame-rate.md)

### [setSessionStorageItem](/api/lynx-api/lynx/lynx-set-session-storage.md)

### [stopExposure()](/api/lynx-api/lynx/lynx-stop-exposure.md)

### [subscribeSessionStorage](/api/lynx-api/lynx/lynx-subscribe-session-storage.md)

### [unsubscribeSessionStorage](/api/lynx-api/lynx/lynx-unsubscribe-session-storage.md)
## NodesRef

### [fields()](/api/lynx-api/nodes-ref/nodes-ref-fields.md)

### [invoke()](/api/lynx-api/nodes-ref/nodes-ref-invoke.md)

### [path()](/api/lynx-api/nodes-ref/nodes-ref-path.md)

### [setNativeProps()](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
## MainThread

### [Element](/api/lynx-api/main-thread/main-thread-element.md)

### [Element.animate()](/api/lynx-api/main-thread/lynx-animate-api.md)

### [Element.getComputedStyleProperty()](/api/lynx-api/main-thread/element-get-computed-style.md)

### [lynx.getTextInfo()](/api/lynx-api/main-thread/lynx-get-text-info.md)

### [lynx.querySelector()](/api/lynx-api/main-thread/lynx-query-selector.md)

### [lynx.querySelectorAll()](/api/lynx-api/main-thread/lynx-query-select-all.md)

### [lynx.requestAnimationFrame()](/api/lynx-api/main-thread/lynx-request-animation-frame.md)

### [lynx.__globalProps](/api/lynx-api/main-thread/lynx-global-props.md)

### [lynx.stopExposure()](/api/lynx-api/main-thread/lynx-stop-exposure.md)

### [lynx.resumeExposure()](/api/lynx-api/main-thread/lynx-resume-exposure.md)

### [lynx.getSessionStorageItem()](/api/lynx-api/main-thread/lynx-get-session-storage.md)

### [lynx.setSessionStorageItem()](/api/lynx-api/main-thread/lynx-set-session-storage.md)

### [lynx.subscribeSessionStorage()](/api/lynx-api/main-thread/lynx-subscribe-session-storage.md)

### [lynx.unsubscribeSessionStorage()](/api/lynx-api/main-thread/lynx-unsubscribe-session-storage.md)
## SelectorQuery

### [exec()](/api/lynx-api/selector-query/selector-query-exec.md)

### [selectAll()](/api/lynx-api/selector-query/selector-query-select-all.md)

### [selectRoot()](/api/lynx-api/selector-query/selector-query-select-root.md)

### [selectUniqueID()](/api/lynx-api/selector-query/selector-query-select-unique-id.md)

### [select()](/api/lynx-api/selector-query/selector-query-select.md)
## Performance APIs

### [Performance Entry](/api/lynx-api/performance-api/performance-entry.md)

### [Performance Observer](/api/lynx-api/performance-api/performance-observer.md)

### [PerformanceMetric](/api/lynx-api/performance-api/performance-metric.md)

### [FrameworkPipelineTiming](/api/lynx-api/performance-api/framework-pipeline-timing.md)

### [HostPlatformTiming](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md)
## LynxView

### [addLynxViewClient](/api/lynx-native-api/lynx-view/add-lynx-view-client.md)

- [Syntax](/api/lynx-native-api/lynx-view/add-lynx-view-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/add-lynx-view-client.md#compatibility)

### [destroy](/api/lynx-native-api/lynx-view/destroy.md)

- [Syntax](/api/lynx-native-api/lynx-view/destroy.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/destroy.md#compatibility)

### [enableAutoLayout](/api/lynx-native-api/lynx-view/enable-auto-layout.md)

- [Syntax](/api/lynx-native-api/lynx-view/enable-auto-layout.md#syntax)
- [Notes](/api/lynx-native-api/lynx-view/enable-auto-layout.md#notes)

### [findUIByIdSelector](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md#compatibility)

### [findUIByName](/api/lynx-native-api/lynx-view/find-ui-by-name.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-ui-by-name.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-ui-by-name.md#compatibility)

### [findViewByIdSelector](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md#compatibility)

### [findViewByName](/api/lynx-native-api/lynx-view/find-view-by-name.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-view-by-name.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-view-by-name.md#compatibility)

### [loadTemplate](/api/lynx-native-api/lynx-view/load-template.md)

- [Syntax](/api/lynx-native-api/lynx-view/load-template.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/load-template.md#compatibility)

### [`<lynx-view>`](/api/lynx-native-api/lynx-view/lynx-view.md)

- [lynx-view](/api/lynx-native-api/lynx-view/lynx-view.md#lynx-view)
- [FAQ](/api/lynx-native-api/lynx-view/lynx-view.md#faq)
- [Compatibility](/api/lynx-native-api/lynx-view/lynx-view.md#compatibility)

### [reload](/api/lynx-native-api/lynx-view/reload.md)

- [api: lynx-native-api/lynx-view/reload](/api/lynx-native-api/lynx-view/reload.md#api-lynx-native-apilynx-viewreload)
- [Syntax](/api/lynx-native-api/lynx-view/reload.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/reload.md#compatibility)

### [removeLynxViewClient](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md)

- [Syntax](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md#compatibility)

### [sendGlobalEvent](/api/lynx-native-api/lynx-view/send-global-event.md)

- [Syntax](/api/lynx-native-api/lynx-view/send-global-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/send-global-event.md#compatibility)

### [setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md)

- [Syntax](/api/lynx-native-api/lynx-view/set-extra-timing.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/set-extra-timing.md#compatibility)

### [updateFontScale](/api/lynx-native-api/lynx-view/update-font-scale.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-font-scale.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-font-scale.md#compatibility)

### [updateMetaData](/api/lynx-native-api/lynx-view/update-meta-data.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-meta-data.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-meta-data.md#compatibility)

### [updateViewport](/api/lynx-native-api/lynx-view/update-viewport.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-viewport.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-viewport.md#compatibility)
## LynxViewClient

### [onDataUpdated](/api/lynx-native-api/lynx-view-client/on-data-updated.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-data-updated.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-data-updated.md#compatibility)

### [onDestroy](/api/lynx-native-api/lynx-view-client/on-destroy.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-destroy.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-destroy.md#compatibility)

### [onFirstLoadPerfReady](/api/lynx-native-api/lynx-view-client/on-first-load-perf-ready.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-first-load-perf-ready.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-first-load-perf-ready.md#compatibility)

### [onFirstScreen](/api/lynx-native-api/lynx-view-client/on-first-screen.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-first-screen.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-first-screen.md#compatibility)

### [onFling](/api/lynx-native-api/lynx-view-client/on-fling.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-fling.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-fling.md#compatibility)

### [onFlushFinish](/api/lynx-native-api/lynx-view-client/on-flush-finish.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-flush-finish.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-flush-finish.md#compatibility)

### [onKeyEvent](/api/lynx-native-api/lynx-view-client/on-key-event.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-key-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-key-event.md#compatibility)

### [onLoadSuccess](/api/lynx-native-api/lynx-view-client/on-load-success.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-load-success.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-load-success.md#compatibility)

### [onLynxEvent](/api/lynx-native-api/lynx-view-client/on-lynx-event.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-lynx-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-lynx-event.md#compatibility)

### [onLynxViewAndJSRuntimeDestroy](/api/lynx-native-api/lynx-view-client/on-lynx-view-and-js-runtime-destroy.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-lynx-view-and-js-runtime-destroy.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-lynx-view-and-js-runtime-destroy.md#compatibility)

### [onModuleMethodInvoked](/api/lynx-native-api/lynx-view-client/on-module-method-invoked.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-module-method-invoked.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-module-method-invoked.md#compatibility)

### [onPageStart](/api/lynx-native-api/lynx-view-client/on-page-start.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-page-start.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-page-start.md#compatibility)

### [onPageUpdate](/api/lynx-native-api/lynx-view-client/on-page-update.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-page-update.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-page-update.md#compatibility)

### [onPerformanceEvent](/api/lynx-native-api/lynx-view-client/on-performance-event.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-performance-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-performance-event.md#compatibility)

### [onPiperInvoked](/api/lynx-native-api/lynx-view-client/on-piper-invoked.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-piper-invoked.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-piper-invoked.md#compatibility)

### [onReceivedError](/api/lynx-native-api/lynx-view-client/on-received-error.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-received-error.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-received-error.md#compatibility)

### [onReceivedJavaError](/api/lynx-native-api/lynx-view-client/on-received-java-error.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-received-java-error.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-received-java-error.md#compatibility)

### [onReceivedJSError](/api/lynx-native-api/lynx-view-client/on-received-js-error.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-received-js-error.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-received-js-error.md#compatibility)

### [onReceivedNativeError](/api/lynx-native-api/lynx-view-client/on-received-native-error.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-received-native-error.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-received-native-error.md#compatibility)

### [onReportComponentInfo](/api/lynx-native-api/lynx-view-client/on-report-component-info.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-report-component-info.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-report-component-info.md#compatibility)

### [onRuntimeReady](/api/lynx-native-api/lynx-view-client/on-runtime-ready.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-runtime-ready.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-runtime-ready.md#compatibility)

### [onScrollStart](/api/lynx-native-api/lynx-view-client/on-scroll-start.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-scroll-start.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-scroll-start.md#compatibility)

### [onScrollStop](/api/lynx-native-api/lynx-view-client/on-scroll-stop.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-scroll-stop.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-scroll-stop.md#compatibility)

### [onTASMFinishedByNative](/api/lynx-native-api/lynx-view-client/on-tasm-finished-by-native.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-tasm-finished-by-native.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-tasm-finished-by-native.md#compatibility)

### [onTemplateBundleReady](/api/lynx-native-api/lynx-view-client/on-template-bundle-ready.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-template-bundle-ready.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-template-bundle-ready.md#compatibility)

### [onUpdateDataWithoutChange](/api/lynx-native-api/lynx-view-client/on-update-data-without-change.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-update-data-without-change.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-update-data-without-change.md#compatibility)

### [onUpdatePerfReady](/api/lynx-native-api/lynx-view-client/on-update-perf-ready.md)

- [Syntax](/api/lynx-native-api/lynx-view-client/on-update-perf-ready.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view-client/on-update-perf-ready.md#compatibility)
## LynxBackgroundRuntime

### [addLynxBackgroundRuntimeClient](/api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md#compatibility)

### [callJSFunction](/api/lynx-native-api/lynx-background-runtime/call-js-function.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/call-js-function.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/call-js-function.md#compatibility)

### [destroy](/api/lynx-native-api/lynx-background-runtime/destroy.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/destroy.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/destroy.md#compatibility)

### [evaluateJavaScript](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#compatibility)

### [removeLynxBackgroundRuntimeClient](/api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md#compatibility)

### [sendGlobalEvent](/api/lynx-native-api/lynx-background-runtime/send-global-event.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime/send-global-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime/send-global-event.md#compatibility)
## LynxBackgroundRuntimeClient

### [onEvaluateJavaScriptEnd](/api/lynx-native-api/lynx-background-runtime-client/on-evaluate-java-script-end.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime-client/on-evaluate-java-script-end.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime-client/on-evaluate-java-script-end.md#compatibility)

### [onModuleMethodInvoked](/api/lynx-native-api/lynx-background-runtime-client/on-module-method-invoked.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime-client/on-module-method-invoked.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime-client/on-module-method-invoked.md#compatibility)

### [onReceivedError](/api/lynx-native-api/lynx-background-runtime-client/on-received-error.md)

- [Syntax](/api/lynx-native-api/lynx-background-runtime-client/on-received-error.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-background-runtime-client/on-received-error.md#compatibility)
## LynxContext

### [sendGlobalEvent](/api/lynx-native-api/lynx-context/send-global-event.md)

- [Syntax](/api/lynx-native-api/lynx-context/send-global-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-context/send-global-event.md#compatibility)

### [setExtraTiming](/api/lynx-native-api/lynx-context/set-extra-timing.md)

- [Syntax](/api/lynx-native-api/lynx-context/set-extra-timing.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-context/set-extra-timing.md#compatibility)

### [updateFontScale](/api/lynx-native-api/lynx-context/update-font-scale.md)

- [Syntax](/api/lynx-native-api/lynx-context/update-font-scale.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-context/update-font-scale.md#compatibility)

### [updateMetaData](/api/lynx-native-api/lynx-context/update-meta-data.md)

- [Syntax](/api/lynx-native-api/lynx-context/update-meta-data.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-context/update-meta-data.md#compatibility)

### [updateViewport](/api/lynx-native-api/lynx-context/update-viewport.md)

- [Syntax](/api/lynx-native-api/lynx-context/update-viewport.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-context/update-viewport.md#compatibility)
## LynxEnv

### [trimMemory](/api/lynx-native-api/lynx-env/trim-memory.md)

- [Syntax](/api/lynx-native-api/lynx-env/trim-memory.md#syntax)
- [Parameters](/api/lynx-native-api/lynx-env/trim-memory.md#parameters)
- [Compatibility](/api/lynx-native-api/lynx-env/trim-memory.md#compatibility)
## LynxExtensionModule

### [LynxExtensionModule](/api/lynx-native-api/lynx-extension-module.md)
## GenericResourceFetcher

### [cancel](/api/lynx-native-api/lynx-generic-resource-fetcher/cancel.md)

- [Syntax](/api/lynx-native-api/lynx-generic-resource-fetcher/cancel.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-generic-resource-fetcher/cancel.md#compatibility)

### [fetchResourcePath](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource-path.md)

- [Syntax](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource-path.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource-path.md#compatibility)

### [fetchResource](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md)

- [Syntax](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md#compatibility)

### [fetchStream](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-stream.md)

- [Syntax](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-stream.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-stream.md#compatibility)
## MediaResourceFetcher

### [fetchImage](/api/lynx-native-api/lynx-media-resource-fetcher/fetch-image.md)

- [Syntax](/api/lynx-native-api/lynx-media-resource-fetcher/fetch-image.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-media-resource-fetcher/fetch-image.md#compatibility)

### [isLocalResource](/api/lynx-native-api/lynx-media-resource-fetcher/is-local-resource.md)

- [Syntax](/api/lynx-native-api/lynx-media-resource-fetcher/is-local-resource.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-media-resource-fetcher/is-local-resource.md#compatibility)

### [shouldRedirectUrl](/api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md)

- [Syntax](/api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md#compatibility)
## TemplateResourceFetcher

### [fetchTemplate](/api/lynx-native-api/lynx-template-resource-fetcher/fetch-template.md)

- [Syntax](/api/lynx-native-api/lynx-template-resource-fetcher/fetch-template.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-template-resource-fetcher/fetch-template.md#compatibility)
## TemplateBundle

### [fromTemplateAsyncWithOption](/api/lynx-native-api/template-bundle/from-template-async-with-option.md)

### [fromTemplateAsync](/api/lynx-native-api/template-bundle/from-template-async.md)

### [fromTemplate](/api/lynx-native-api/template-bundle/from-template.md)

### [getErrorMessage](/api/lynx-native-api/template-bundle/get-error-message.md)

### [getExtraInfo](/api/lynx-native-api/template-bundle/get-extra-info.md)

### [getTemplateSize](/api/lynx-native-api/template-bundle/get-template-size.md)

### [isElementBundleValid](/api/lynx-native-api/template-bundle/is-element-bundle-valid.md)

### [isValid](/api/lynx-native-api/template-bundle/is-valid.md)

### [postJsCacheGenerationTask](/api/lynx-native-api/template-bundle/post-js-cache-generation-task.md)

### [release](/api/lynx-native-api/template-bundle/release.md)
## TemplateData

### [constructor](/api/lynx-native-api/template-data/constructor.md)

- [Syntax](/api/lynx-native-api/template-data/constructor.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/constructor.md#compatibility)

### [data](/api/lynx-native-api/template-data/data.md)

- [Syntax](/api/lynx-native-api/template-data/data.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/data.md#compatibility)

### [fromMap](/api/lynx-native-api/template-data/from-map.md)

- [Syntax](/api/lynx-native-api/template-data/from-map.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/from-map.md#compatibility)

### [fromString](/api/lynx-native-api/template-data/from-string.md)

- [Syntax](/api/lynx-native-api/template-data/from-string.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/from-string.md#compatibility)

### [markState](/api/lynx-native-api/template-data/mark-state.md)

- [Syntax](/api/lynx-native-api/template-data/mark-state.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/mark-state.md#compatibility)

### [merge](/api/lynx-native-api/template-data/merge.md)

- [Syntax](/api/lynx-native-api/template-data/merge.md#syntax)
- [Compatibility](/api/lynx-native-api/template-data/merge.md#compatibility)
## LynxLoadMeta

### [LynxLoadMeta](/api/lynx-native-api/lynx-load-meta.md)
## LynxUpdateMeta

### [LynxUpdateMeta](/api/lynx-native-api/lynx-update-meta.md)
## LynxService

### [LynxService](/api/lynx-native-api/lynx-service.md)
## TraceEvent

### [TraceEvent](/api/lynx-native-api/trace-event.md)
## CDPEventListener

### [CDPEventListener](/api/lynx-devtool-native-api/cdp-event-listener.md)

- [Syntax](/api/lynx-devtool-native-api/cdp-event-listener.md#syntax)
- [Data Format](/api/lynx-devtool-native-api/cdp-event-listener.md#data-format)
- [Usage Example](/api/lynx-devtool-native-api/cdp-event-listener.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/cdp-event-listener.md#compatibility)
## CDPResultCallback

### [CDPResultCallback](/api/lynx-devtool-native-api/cdp-result-callback.md)

- [Syntax](/api/lynx-devtool-native-api/cdp-result-callback.md#syntax)
- [Return Data Format](/api/lynx-devtool-native-api/cdp-result-callback.md#return-data-format)
- [Usage Example](/api/lynx-devtool-native-api/cdp-result-callback.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/cdp-result-callback.md#compatibility)
## CustomizedMessage

### [CustomizedMessage](/api/lynx-devtool-native-api/customized-message.md)

- [Syntax](/api/lynx-devtool-native-api/customized-message.md#syntax)
- [Compatibility](/api/lynx-devtool-native-api/customized-message.md#compatibility)
## GlobalPropsUpdatedObserver

### [GlobalPropsUpdatedObserver](/api/lynx-devtool-native-api/global-props-updated-observer.md)

- [Syntax](/api/lynx-devtool-native-api/global-props-updated-observer.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/global-props-updated-observer.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/global-props-updated-observer.md#compatibility)
## LynxBaseInspectorOwner

### [addCDPEventListener](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md#compatibility)

### [getConsoleObject](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md#syntax)
- [Data Format](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md#data-format)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md#compatibility)

### [invokeCDPFromSDK](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#syntax)
- [Request Data Format](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#request-data-format)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#compatibility)

### [reload](/api/lynx-devtool-native-api/lynx-base-inspector-owner/reload.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/reload.md#syntax)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/reload.md#compatibility)

### [removeCDPEventListener](/api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md#compatibility)

### [sendMessage](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md#compatibility)

### [setGlobalPropsUpdatedObserver](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md#compatibility)

### [setLynxInspectorConsoleDelegate](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md#compatibility)

### [subscribeMessage](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#compatibility)

### [unsubscribeMessage](/api/lynx-devtool-native-api/lynx-base-inspector-owner/unsubscribe-message.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-base-inspector-owner/unsubscribe-message.md#syntax)
- [Usage Example](/api/lynx-devtool-native-api/lynx-base-inspector-owner/unsubscribe-message.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-base-inspector-owner/unsubscribe-message.md#compatibility)
## LynxDevToolUtils

### [setDevToolLibraryLoader](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md#syntax)
- [Compatibility](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md#compatibility)
## LynxInspectorConsoleDelegate

### [LynxInspectorConsoleDelegate](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#syntax)
- [Data Format](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#data-format)
- [Usage Example](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#usage-example)
- [Compatibility](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#compatibility)
## MessageHandler

### [MessageHandler](/api/lynx-devtool-native-api/message-handler.md)

- [Syntax](/api/lynx-devtool-native-api/message-handler.md#syntax)
- [Compatibility](/api/lynx-devtool-native-api/message-handler.md#compatibility)
## @lynx-js/testing-environment

### [Class: GlobalEventEmitter](/api/lynx-testing-environment/Class.GlobalEventEmitter.md)

- [Constructors](/api/lynx-testing-environment/Class.GlobalEventEmitter.md#constructors)
- [Properties](/api/lynx-testing-environment/Class.GlobalEventEmitter.md#properties)
- [Methods](/api/lynx-testing-environment/Class.GlobalEventEmitter.md#methods)

### [Class: LynxTestingEnv](/api/lynx-testing-environment/Class.LynxTestingEnv.md)

- [Example](/api/lynx-testing-environment/Class.LynxTestingEnv.md#example)
- [Constructors](/api/lynx-testing-environment/Class.LynxTestingEnv.md#constructors)
- [Properties](/api/lynx-testing-environment/Class.LynxTestingEnv.md#properties)
- [Methods](/api/lynx-testing-environment/Class.LynxTestingEnv.md#methods)

### [Function: initElementTree()](/api/lynx-testing-environment/Function.initElementTree.md)

- [Returns](/api/lynx-testing-environment/Function.initElementTree.md#returns)
- [Defined in](/api/lynx-testing-environment/Function.initElementTree.md#defined-in)

### [Function: installLynxTestingEnv()](/api/lynx-testing-environment/Function.installLynxTestingEnv.md)

- [Parameters](/api/lynx-testing-environment/Function.installLynxTestingEnv.md#parameters)
- [Returns](/api/lynx-testing-environment/Function.installLynxTestingEnv.md#returns)
- [Defined in](/api/lynx-testing-environment/Function.installLynxTestingEnv.md#defined-in)

### [Function: uninstallLynxTestingEnv()](/api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md)

- [Parameters](/api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md#parameters)
- [Returns](/api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md#returns)
- [Defined in](/api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md#defined-in)

### [Interface: LynxElement](/api/lynx-testing-environment/Interface.LynxElement.md)

- [Extends](/api/lynx-testing-environment/Interface.LynxElement.md#extends)
- [Properties](/api/lynx-testing-environment/Interface.LynxElement.md#properties)

### [Interface: LynxEnv](/api/lynx-testing-environment/Interface.LynxEnv.md)

- [Properties](/api/lynx-testing-environment/Interface.LynxEnv.md#properties)

### [Interface: LynxGlobalThis](/api/lynx-testing-environment/Interface.LynxGlobalThis.md)

- [Indexable](/api/lynx-testing-environment/Interface.LynxGlobalThis.md#indexable)
- [Properties](/api/lynx-testing-environment/Interface.LynxGlobalThis.md#properties)

### [Type Alias: ElementTree](/api/lynx-testing-environment/TypeAlias.ElementTree.md)

- [Defined in](/api/lynx-testing-environment/TypeAlias.ElementTree.md#defined-in)

### [Type Alias: ElementTreeGlobals](/api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md)

- [Defined in](/api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md#defined-in)

### [Type Alias: FilterUnderscoreKeys\<T\>](/api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md)

- [Type Parameters](/api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md#type-parameters)
- [Defined in](/api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md#defined-in)

### [Type Alias: PickUnderscoreKeys\<T\>](/api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md)

- [Type Parameters](/api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md#type-parameters)
- [Defined in](/api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md#defined-in)
## @lynx-js/react/testing-library

### [Class: LynxTestingEnv](/api/reactlynx-testing-library/Class.LynxTestingEnv.md)

- [Example](/api/reactlynx-testing-library/Class.LynxTestingEnv.md#example)
- [Constructors](/api/reactlynx-testing-library/Class.LynxTestingEnv.md#constructors)
- [Properties](/api/reactlynx-testing-library/Class.LynxTestingEnv.md#properties)
- [Methods](/api/reactlynx-testing-library/Class.LynxTestingEnv.md#methods)

### [Function: buildQueries()](/api/reactlynx-testing-library/Function.buildQueries.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.buildQueries.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.buildQueries.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.buildQueries.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.buildQueries.md#defined-in)

### [Function: cleanup()](/api/reactlynx-testing-library/Function.cleanup.md)

- [Returns](/api/reactlynx-testing-library/Function.cleanup.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.cleanup.md#defined-in)

### [Function: computeHeadingLevel()](/api/reactlynx-testing-library/Function.computeHeadingLevel.md)

- [Parameters](/api/reactlynx-testing-library/Function.computeHeadingLevel.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.computeHeadingLevel.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.computeHeadingLevel.md#defined-in)

### [Function: configure()](/api/reactlynx-testing-library/Function.configure.md)

- [Parameters](/api/reactlynx-testing-library/Function.configure.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.configure.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.configure.md#defined-in)

### [Function: createEvent()](/api/reactlynx-testing-library/Function.createEvent.md)

- [Parameters](/api/reactlynx-testing-library/Function.createEvent.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.createEvent.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.createEvent.md#defined-in)

### [Function: findAllByAltText()](/api/reactlynx-testing-library/Function.findAllByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByAltText.md#defined-in)

### [Function: findAllByDisplayValue()](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md#defined-in)

### [Function: findAllByLabelText()](/api/reactlynx-testing-library/Function.findAllByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByLabelText.md#defined-in)

### [Function: findAllByPlaceholderText()](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md#defined-in)

### [Function: findAllByRole()](/api/reactlynx-testing-library/Function.findAllByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByRole.md#defined-in)

### [Function: findAllByTestId()](/api/reactlynx-testing-library/Function.findAllByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByTestId.md#defined-in)

### [Function: findAllByText()](/api/reactlynx-testing-library/Function.findAllByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByText.md#defined-in)

### [Function: findAllByTitle()](/api/reactlynx-testing-library/Function.findAllByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findAllByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findAllByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findAllByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findAllByTitle.md#defined-in)

### [Function: findByAltText()](/api/reactlynx-testing-library/Function.findByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByAltText.md#defined-in)

### [Function: findByDisplayValue()](/api/reactlynx-testing-library/Function.findByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByDisplayValue.md#defined-in)

### [Function: findByLabelText()](/api/reactlynx-testing-library/Function.findByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByLabelText.md#defined-in)

### [Function: findByPlaceholderText()](/api/reactlynx-testing-library/Function.findByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByPlaceholderText.md#defined-in)

### [Function: findByRole()](/api/reactlynx-testing-library/Function.findByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByRole.md#defined-in)

### [Function: findByTestId()](/api/reactlynx-testing-library/Function.findByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByTestId.md#defined-in)

### [Function: findByText()](/api/reactlynx-testing-library/Function.findByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByText.md#defined-in)

### [Function: findByTitle()](/api/reactlynx-testing-library/Function.findByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.findByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.findByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.findByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.findByTitle.md#defined-in)

### [Function: fireEvent()](/api/reactlynx-testing-library/Function.fireEvent.md)

- [Parameters](/api/reactlynx-testing-library/Function.fireEvent.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.fireEvent.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.fireEvent.md#defined-in)

### [Function: getAllByAltText()](/api/reactlynx-testing-library/Function.getAllByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByAltText.md#defined-in)

### [Function: getAllByDisplayValue()](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md#defined-in)

### [Function: getAllByLabelText()](/api/reactlynx-testing-library/Function.getAllByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByLabelText.md#defined-in)

### [Function: getAllByPlaceholderText()](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md#defined-in)

### [Function: getAllByRole()](/api/reactlynx-testing-library/Function.getAllByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByRole.md#defined-in)

### [Function: getAllByTestId()](/api/reactlynx-testing-library/Function.getAllByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByTestId.md#defined-in)

### [Function: getAllByText()](/api/reactlynx-testing-library/Function.getAllByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByText.md#defined-in)

### [Function: getAllByTitle()](/api/reactlynx-testing-library/Function.getAllByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getAllByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getAllByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getAllByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getAllByTitle.md#defined-in)

### [Function: getByAltText()](/api/reactlynx-testing-library/Function.getByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByAltText.md#defined-in)

### [Function: getByDisplayValue()](/api/reactlynx-testing-library/Function.getByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByDisplayValue.md#defined-in)

### [Function: getByLabelText()](/api/reactlynx-testing-library/Function.getByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByLabelText.md#defined-in)

### [Function: getByPlaceholderText()](/api/reactlynx-testing-library/Function.getByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByPlaceholderText.md#defined-in)

### [Function: getByRole()](/api/reactlynx-testing-library/Function.getByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByRole.md#defined-in)

### [Function: getByTestId()](/api/reactlynx-testing-library/Function.getByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByTestId.md#defined-in)

### [Function: getByText()](/api/reactlynx-testing-library/Function.getByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByText.md#defined-in)

### [Function: getByTitle()](/api/reactlynx-testing-library/Function.getByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getByTitle.md#defined-in)

### [Function: getConfig()](/api/reactlynx-testing-library/Function.getConfig.md)

- [Returns](/api/reactlynx-testing-library/Function.getConfig.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getConfig.md#defined-in)

### [Function: getDefaultNormalizer()](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md)

- [Parameters](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md#defined-in)

### [Function: getElementError()](/api/reactlynx-testing-library/Function.getElementError.md)

- [Parameters](/api/reactlynx-testing-library/Function.getElementError.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getElementError.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getElementError.md#defined-in)

### [Function: getNodeText()](/api/reactlynx-testing-library/Function.getNodeText.md)

- [Parameters](/api/reactlynx-testing-library/Function.getNodeText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getNodeText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getNodeText.md#defined-in)

### [Function: getQueriesForElement()](/api/reactlynx-testing-library/Function.getQueriesForElement.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.getQueriesForElement.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.getQueriesForElement.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getQueriesForElement.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getQueriesForElement.md#defined-in)

### [Function: getRoles()](/api/reactlynx-testing-library/Function.getRoles.md)

- [Parameters](/api/reactlynx-testing-library/Function.getRoles.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getRoles.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getRoles.md#defined-in)

### [Function: getSuggestedQuery()](/api/reactlynx-testing-library/Function.getSuggestedQuery.md)

- [Parameters](/api/reactlynx-testing-library/Function.getSuggestedQuery.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.getSuggestedQuery.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.getSuggestedQuery.md#defined-in)

### [Function: isInaccessible()](/api/reactlynx-testing-library/Function.isInaccessible.md)

- [Parameters](/api/reactlynx-testing-library/Function.isInaccessible.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.isInaccessible.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.isInaccessible.md#defined-in)

### [Function: logDOM()](/api/reactlynx-testing-library/Function.logDOM.md)

- [Parameters](/api/reactlynx-testing-library/Function.logDOM.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.logDOM.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.logDOM.md#defined-in)

### [Function: logRoles()](/api/reactlynx-testing-library/Function.logRoles.md)

- [Parameters](/api/reactlynx-testing-library/Function.logRoles.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.logRoles.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.logRoles.md#defined-in)

### [Function: prettyDOM()](/api/reactlynx-testing-library/Function.prettyDOM.md)

- [Parameters](/api/reactlynx-testing-library/Function.prettyDOM.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.prettyDOM.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.prettyDOM.md#defined-in)

### [Function: queryAllByAltText()](/api/reactlynx-testing-library/Function.queryAllByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByAltText.md#defined-in)

### [Function: queryAllByAttribute()](/api/reactlynx-testing-library/Function.queryAllByAttribute.md)

- [Parameters](/api/reactlynx-testing-library/Function.queryAllByAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByAttribute.md#defined-in)

### [Function: queryAllByDisplayValue()](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md#defined-in)

### [Function: queryAllByLabelText()](/api/reactlynx-testing-library/Function.queryAllByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByLabelText.md#defined-in)

### [Function: queryAllByPlaceholderText()](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md#defined-in)

### [Function: queryAllByRole()](/api/reactlynx-testing-library/Function.queryAllByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByRole.md#defined-in)

### [Function: queryAllByTestId()](/api/reactlynx-testing-library/Function.queryAllByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByTestId.md#defined-in)

### [Function: queryAllByText()](/api/reactlynx-testing-library/Function.queryAllByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByText.md#defined-in)

### [Function: queryAllByTitle()](/api/reactlynx-testing-library/Function.queryAllByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryAllByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryAllByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryAllByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryAllByTitle.md#defined-in)

### [Function: queryByAltText()](/api/reactlynx-testing-library/Function.queryByAltText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByAltText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByAltText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByAltText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByAltText.md#defined-in)

### [Function: queryByAttribute()](/api/reactlynx-testing-library/Function.queryByAttribute.md)

- [Parameters](/api/reactlynx-testing-library/Function.queryByAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByAttribute.md#defined-in)

### [Function: queryByDisplayValue()](/api/reactlynx-testing-library/Function.queryByDisplayValue.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByDisplayValue.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByDisplayValue.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByDisplayValue.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByDisplayValue.md#defined-in)

### [Function: queryByLabelText()](/api/reactlynx-testing-library/Function.queryByLabelText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByLabelText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByLabelText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByLabelText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByLabelText.md#defined-in)

### [Function: queryByPlaceholderText()](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md#defined-in)

### [Function: queryByRole()](/api/reactlynx-testing-library/Function.queryByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByRole.md#defined-in)

### [Function: queryByTestId()](/api/reactlynx-testing-library/Function.queryByTestId.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByTestId.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByTestId.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByTestId.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByTestId.md#defined-in)

### [Function: queryByText()](/api/reactlynx-testing-library/Function.queryByText.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByText.md#defined-in)

### [Function: queryByTitle()](/api/reactlynx-testing-library/Function.queryByTitle.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.queryByTitle.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.queryByTitle.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.queryByTitle.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.queryByTitle.md#defined-in)

### [Function: render()](/api/reactlynx-testing-library/Function.render.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.render.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.render.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.render.md#returns)
- [Example](/api/reactlynx-testing-library/Function.render.md#example)
- [Defined in](/api/reactlynx-testing-library/Function.render.md#defined-in)

### [Function: renderHook()](/api/reactlynx-testing-library/Function.renderHook.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.renderHook.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.renderHook.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.renderHook.md#returns)
- [Example](/api/reactlynx-testing-library/Function.renderHook.md#example)
- [Defined in](/api/reactlynx-testing-library/Function.renderHook.md#defined-in)

### [Function: waitFor()](/api/reactlynx-testing-library/Function.waitFor.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.waitFor.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.waitFor.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.waitFor.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.waitFor.md#defined-in)

### [Function: waitForElementToBeRemoved()](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md#defined-in)

### [Function: ~~waitSchedule()~~](/api/reactlynx-testing-library/Function.waitSchedule.md)

- [Returns](/api/reactlynx-testing-library/Function.waitSchedule.md#returns)
- [Deprecated](/api/reactlynx-testing-library/Function.waitSchedule.md#deprecated)
- [Defined in](/api/reactlynx-testing-library/Function.waitSchedule.md#defined-in)

### [Function: within()](/api/reactlynx-testing-library/Function.within.md)

- [Type Parameters](/api/reactlynx-testing-library/Function.within.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/Function.within.md#parameters)
- [Returns](/api/reactlynx-testing-library/Function.within.md#returns)
- [Defined in](/api/reactlynx-testing-library/Function.within.md#defined-in)

### [Interface: ByRoleOptions](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)

- [Properties](/api/reactlynx-testing-library/Interface.ByRoleOptions.md#properties)

### [Interface: Config](/api/reactlynx-testing-library/Interface.Config.md)

- [Properties](/api/reactlynx-testing-library/Interface.Config.md#properties)
- [Methods](/api/reactlynx-testing-library/Interface.Config.md#methods)

### [Interface: ConfigFn()](/api/reactlynx-testing-library/Interface.ConfigFn.md)

- [Parameters](/api/reactlynx-testing-library/Interface.ConfigFn.md#parameters)
- [Returns](/api/reactlynx-testing-library/Interface.ConfigFn.md#returns)
- [Defined in](/api/reactlynx-testing-library/Interface.ConfigFn.md#defined-in)

### [Interface: DefaultNormalizerOptions](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md)

- [Extended by](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#extended-by)
- [Properties](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#properties)

### [Interface: LogRolesOptions](/api/reactlynx-testing-library/Interface.LogRolesOptions.md)

- [Properties](/api/reactlynx-testing-library/Interface.LogRolesOptions.md#properties)

### [Interface: MatcherOptions](/api/reactlynx-testing-library/Interface.MatcherOptions.md)

- [Extended by](/api/reactlynx-testing-library/Interface.MatcherOptions.md#extended-by)
- [Properties](/api/reactlynx-testing-library/Interface.MatcherOptions.md#properties)

### [Interface: NormalizerOptions](/api/reactlynx-testing-library/Interface.NormalizerOptions.md)

- [Extends](/api/reactlynx-testing-library/Interface.NormalizerOptions.md#extends)
- [Properties](/api/reactlynx-testing-library/Interface.NormalizerOptions.md#properties)

### [Interface: PrettyDOMOptions](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md)

- [Extends](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md#extends)
- [Properties](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md#properties)

### [Interface: Queries](/api/reactlynx-testing-library/Interface.Queries.md)

- [Indexable](/api/reactlynx-testing-library/Interface.Queries.md#indexable)

### [Interface: QueryOptions](/api/reactlynx-testing-library/Interface.QueryOptions.md)

- [Indexable](/api/reactlynx-testing-library/Interface.QueryOptions.md#indexable)

### [Interface: RenderHookOptions\<Props\>](/api/reactlynx-testing-library/Interface.RenderHookOptions.md)

- [Type Parameters](/api/reactlynx-testing-library/Interface.RenderHookOptions.md#type-parameters)
- [Properties](/api/reactlynx-testing-library/Interface.RenderHookOptions.md#properties)

### [Interface: RenderHookResult\<Result, Props\>](/api/reactlynx-testing-library/Interface.RenderHookResult.md)

- [Type Parameters](/api/reactlynx-testing-library/Interface.RenderHookResult.md#type-parameters)
- [Properties](/api/reactlynx-testing-library/Interface.RenderHookResult.md#properties)

### [Interface: RenderOptions\<Q\>](/api/reactlynx-testing-library/Interface.RenderOptions.md)

- [Type Parameters](/api/reactlynx-testing-library/Interface.RenderOptions.md#type-parameters)
- [Properties](/api/reactlynx-testing-library/Interface.RenderOptions.md#properties)

### [Interface: Suggestion](/api/reactlynx-testing-library/Interface.Suggestion.md)

- [Properties](/api/reactlynx-testing-library/Interface.Suggestion.md#properties)
- [Methods](/api/reactlynx-testing-library/Interface.Suggestion.md#methods)

### [Interface: waitForOptions](/api/reactlynx-testing-library/Interface.waitForOptions.md)

- [Properties](/api/reactlynx-testing-library/Interface.waitForOptions.md#properties)

### [queries](/api/reactlynx-testing-library/Namespace.queries.md)

- [Index](/api/reactlynx-testing-library/Namespace.queries.md#index)
- [References](/api/reactlynx-testing-library/Namespace.queries.md#references)

### [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md)

- [Index](/api/reactlynx-testing-library/Namespace.queryHelpers.md#index)
- [References](/api/reactlynx-testing-library/Namespace.queryHelpers.md#references)

### [Type Alias: QueryByBoundAttribute()\<T\>](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)

- [Type Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md#defined-in)

### [Type Alias: QueryByRole()\<T\>](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md#defined-in)

### [Type Alias: QueryByText()\<T\>](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)

- [Type Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md#defined-in)

### [Interface: SelectorMatcherOptions](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)

- [Extends](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md#extends)
- [Properties](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md#properties)

### [Type Alias: QueryMethod()\<Arguments, Return\>](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md)

- [Type Parameters](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md#parameters)
- [Returns](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md#returns)
- [Defined in](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md#defined-in)

### [Type Alias: WithSuggest](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md)

- [Type declaration](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md#type-declaration)
- [Defined in](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md#defined-in)

### [Type Alias: AllByAttribute()](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md#defined-in)

### [Type Alias: AllByBoundAttribute()\<T\>](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md#defined-in)

### [Type Alias: AllByRole()\<T\>](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.AllByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.AllByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.AllByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.AllByRole.md#defined-in)

### [Type Alias: AllByText()\<T\>](/api/reactlynx-testing-library/TypeAlias.AllByText.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.AllByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.AllByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.AllByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.AllByText.md#defined-in)

### [Type Alias: BoundFunction\<T\>](/api/reactlynx-testing-library/TypeAlias.BoundFunction.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.BoundFunction.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.BoundFunction.md#defined-in)

### [Type Alias: BoundFunctions\<Q\>](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md#defined-in)

### [Type Alias: BuiltQueryMethods\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md#defined-in)

### [Type Alias: ByRoleMatcher](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md#defined-in)

### [Type Alias: CreateFunction()](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md#defined-in)

### [Type Alias: CreateObject](/api/reactlynx-testing-library/TypeAlias.CreateObject.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.CreateObject.md#defined-in)

### [Type Alias: ElementTree](/api/reactlynx-testing-library/TypeAlias.ElementTree.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.ElementTree.md#defined-in)

### [Type Alias: EventType](/api/reactlynx-testing-library/TypeAlias.EventType.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.EventType.md#defined-in)

### [Type Alias: FindAllBy\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md#defined-in)

### [Type Alias: FindAllByBoundAttribute()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md#defined-in)

### [Type Alias: FindAllByRole()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md#defined-in)

### [Type Alias: FindAllByText()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md#defined-in)

### [Type Alias: FindBy\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.FindBy.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindBy.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindBy.md#defined-in)

### [Type Alias: FindByBoundAttribute()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md#defined-in)

### [Type Alias: FindByRole()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindByRole.md#defined-in)

### [Type Alias: FindByText()\<T\>](/api/reactlynx-testing-library/TypeAlias.FindByText.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.FindByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.FindByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FindByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FindByText.md#defined-in)

### [Type Alias: FireFunction()](/api/reactlynx-testing-library/TypeAlias.FireFunction.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.FireFunction.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.FireFunction.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.FireFunction.md#defined-in)

### [Type Alias: FireObject](/api/reactlynx-testing-library/TypeAlias.FireObject.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.FireObject.md#defined-in)

### [Type Alias: GetAllBy\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md#defined-in)

### [Type Alias: GetBy\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.GetBy.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetBy.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetBy.md#defined-in)

### [Type Alias: GetByBoundAttribute()\<T\>](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md#defined-in)

### [Type Alias: GetByRole()\<T\>](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetByRole.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.GetByRole.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.GetByRole.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetByRole.md#defined-in)

### [Type Alias: GetByText()\<T\>](/api/reactlynx-testing-library/TypeAlias.GetByText.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetByText.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.GetByText.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.GetByText.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetByText.md#defined-in)

### [Type Alias: GetErrorFunction()\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md#type-parameters)
- [Parameters](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md#defined-in)

### [Type Alias: Match()](/api/reactlynx-testing-library/TypeAlias.Match.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.Match.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.Match.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.Match.md#defined-in)

### [Type Alias: Matcher](/api/reactlynx-testing-library/TypeAlias.Matcher.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.Matcher.md#defined-in)

### [Type Alias: MatcherFunction()](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md#defined-in)

### [Type Alias: Method](/api/reactlynx-testing-library/TypeAlias.Method.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.Method.md#defined-in)

### [Type Alias: NormalizerFn()](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md#defined-in)

### [Type Alias: Query()](/api/reactlynx-testing-library/TypeAlias.Query.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.Query.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.Query.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.Query.md#defined-in)

### [Type Alias: QueryArgs](/api/reactlynx-testing-library/TypeAlias.QueryArgs.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.QueryArgs.md#defined-in)

### [Type Alias: QueryBy\<Arguments\>](/api/reactlynx-testing-library/TypeAlias.QueryBy.md)

- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.QueryBy.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.QueryBy.md#defined-in)

### [Type Alias: QueryByAttribute()](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md)

- [Parameters](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md#parameters)
- [Returns](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md#returns)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md#defined-in)

### [Type Alias: RenderResult\<Q\>](/api/reactlynx-testing-library/TypeAlias.RenderResult.md)

- [Type declaration](/api/reactlynx-testing-library/TypeAlias.RenderResult.md#type-declaration)
- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.RenderResult.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.RenderResult.md#defined-in)

### [Type Alias: Screen\<Q\>](/api/reactlynx-testing-library/TypeAlias.Screen.md)

- [Type declaration](/api/reactlynx-testing-library/TypeAlias.Screen.md#type-declaration)
- [Type Parameters](/api/reactlynx-testing-library/TypeAlias.Screen.md#type-parameters)
- [Defined in](/api/reactlynx-testing-library/TypeAlias.Screen.md#defined-in)

### [Type Alias: Variant](/api/reactlynx-testing-library/TypeAlias.Variant.md)

- [Defined in](/api/reactlynx-testing-library/TypeAlias.Variant.md#defined-in)

### [Variable: act](/api/reactlynx-testing-library/Variable.act.md)

### [Variable: screen](/api/reactlynx-testing-library/Variable.screen.md)

- [Defined in](/api/reactlynx-testing-library/Variable.screen.md#defined-in)
## Element PAPIs

### [`__AddClass`](/api/engine/element-api/__AddClass.md)

- [Introduction](/api/engine/element-api/__AddClass.md#introduction)
- [Syntax](/api/engine/element-api/__AddClass.md#syntax)
- [Example](/api/engine/element-api/__AddClass.md#example)

### [`__AddConfig`](/api/engine/element-api/__AddConfig.md)

- [Introduction](/api/engine/element-api/__AddConfig.md#introduction)
- [Syntax](/api/engine/element-api/__AddConfig.md#syntax)
- [Example](/api/engine/element-api/__AddConfig.md#example)

### [`__AddDataset`](/api/engine/element-api/__AddDataset.md)

- [Introduction](/api/engine/element-api/__AddDataset.md#introduction)
- [Syntax](/api/engine/element-api/__AddDataset.md#syntax)
- [Example](/api/engine/element-api/__AddDataset.md#example)

### [`__AddEvent`](/api/engine/element-api/__AddEvent.md)

- [Introduction](/api/engine/element-api/__AddEvent.md#introduction)
- [Syntax](/api/engine/element-api/__AddEvent.md#syntax)
- [Example](/api/engine/element-api/__AddEvent.md#example)

### [`__AddInlineStyle`](/api/engine/element-api/__AddInlineStyle.md)

- [Introduction](/api/engine/element-api/__AddInlineStyle.md#introduction)
- [Syntax](/api/engine/element-api/__AddInlineStyle.md#syntax)
- [Example](/api/engine/element-api/__AddInlineStyle.md#example)

### [`__AppendElement`](/api/engine/element-api/__AppendElement.md)

- [Introduction](/api/engine/element-api/__AppendElement.md#introduction)
- [Syntax](/api/engine/element-api/__AppendElement.md#syntax)
- [Example](/api/engine/element-api/__AppendElement.md#example)

### [`__CreateComponent`](/api/engine/element-api/__CreateComponent.md)

- [Introduction](/api/engine/element-api/__CreateComponent.md#introduction)
- [Syntax](/api/engine/element-api/__CreateComponent.md#syntax)
- [Example](/api/engine/element-api/__CreateComponent.md#example)

### [`__CreateElement`](/api/engine/element-api/__CreateElement.md)

- [Introduction](/api/engine/element-api/__CreateElement.md#introduction)
- [Syntax](/api/engine/element-api/__CreateElement.md#syntax)
- [Example](/api/engine/element-api/__CreateElement.md#example)

### [`__CreatePage`](/api/engine/element-api/__CreatePage.md)

- [Introduction](/api/engine/element-api/__CreatePage.md#introduction)
- [Syntax](/api/engine/element-api/__CreatePage.md#syntax)
- [Example](/api/engine/element-api/__CreatePage.md#example)

### [`__ElementIsEqual`](/api/engine/element-api/__ElementIsEqual.md)

- [Introduction](/api/engine/element-api/__ElementIsEqual.md#introduction)
- [Syntax](/api/engine/element-api/__ElementIsEqual.md#syntax)
- [Example](/api/engine/element-api/__ElementIsEqual.md#example)

### [`__FirstElement`](/api/engine/element-api/__FirstElement.md)

- [Introduction](/api/engine/element-api/__FirstElement.md#introduction)
- [Syntax](/api/engine/element-api/__FirstElement.md#syntax)
- [Example](/api/engine/element-api/__FirstElement.md#example)

### [`__GetAttributes`](/api/engine/element-api/__GetAttributes.md)

- [Introduction](/api/engine/element-api/__GetAttributes.md#introduction)
- [Syntax](/api/engine/element-api/__GetAttributes.md#syntax)
- [Example](/api/engine/element-api/__GetAttributes.md#example)

### [`__GetChildren`](/api/engine/element-api/__GetChildren.md)

- [Introduction](/api/engine/element-api/__GetChildren.md#introduction)
- [Syntax](/api/engine/element-api/__GetChildren.md#syntax)
- [Example](/api/engine/element-api/__GetChildren.md#example)

### [`__GetClasses`](/api/engine/element-api/__GetClasses.md)

- [Introduction](/api/engine/element-api/__GetClasses.md#introduction)
- [Syntax](/api/engine/element-api/__GetClasses.md#syntax)
- [Example](/api/engine/element-api/__GetClasses.md#example)

### [`__GetComponentID`](/api/engine/element-api/__GetComponentID.md)

- [Introduction](/api/engine/element-api/__GetComponentID.md#introduction)
- [Syntax](/api/engine/element-api/__GetComponentID.md#syntax)
- [Example](/api/engine/element-api/__GetComponentID.md#example)

### [`__GetComputedStyleByKey`](/api/engine/element-api/__GetComputedStyleByKey.md)

- [Introduction](/api/engine/element-api/__GetComputedStyleByKey.md#introduction)
- [Syntax](/api/engine/element-api/__GetComputedStyleByKey.md#syntax)
- [Example](/api/engine/element-api/__GetComputedStyleByKey.md#example)
- [Compatability](/api/engine/element-api/__GetComputedStyleByKey.md#compatability)

### [`__GetConfig`](/api/engine/element-api/__GetConfig.md)

- [Introduction](/api/engine/element-api/__GetConfig.md#introduction)
- [Syntax](/api/engine/element-api/__GetConfig.md#syntax)
- [Example](/api/engine/element-api/__GetConfig.md#example)

### [`__GetDataByKey`](/api/engine/element-api/__GetDataByKey.md)

- [Introduction](/api/engine/element-api/__GetDataByKey.md#introduction)
- [Syntax](/api/engine/element-api/__GetDataByKey.md#syntax)
- [Example](/api/engine/element-api/__GetDataByKey.md#example)

### [`__GetDataset`](/api/engine/element-api/__GetDataset.md)

- [Introduction](/api/engine/element-api/__GetDataset.md#introduction)
- [Syntax](/api/engine/element-api/__GetDataset.md#syntax)
- [Example](/api/engine/element-api/__GetDataset.md#example)

### [`__GetElementUniqueID`](/api/engine/element-api/__GetElementUniqueID.md)

- [Introduction](/api/engine/element-api/__GetElementUniqueID.md#introduction)
- [Syntax](/api/engine/element-api/__GetElementUniqueID.md#syntax)
- [Example](/api/engine/element-api/__GetElementUniqueID.md#example)

### [`__GetEvent`](/api/engine/element-api/__GetEvent.md)

- [Introduction](/api/engine/element-api/__GetEvent.md#introduction)
- [Syntax](/api/engine/element-api/__GetEvent.md#syntax)
- [Example](/api/engine/element-api/__GetEvent.md#example)

### [`__GetEvents`](/api/engine/element-api/__GetEvents.md)

- [Introduction](/api/engine/element-api/__GetEvents.md#introduction)
- [Syntax](/api/engine/element-api/__GetEvents.md#syntax)
- [Example](/api/engine/element-api/__GetEvents.md#example)

### [`__GetID`](/api/engine/element-api/__GetID.md)

- [Introduction](/api/engine/element-api/__GetID.md#introduction)
- [Syntax](/api/engine/element-api/__GetID.md#syntax)
- [Example](/api/engine/element-api/__GetID.md#example)

### [`__GetInlineStyles`](/api/engine/element-api/__GetInlineStyles.md)

- [Introduction](/api/engine/element-api/__GetInlineStyles.md#introduction)
- [Syntax](/api/engine/element-api/__GetInlineStyles.md#syntax)
- [Example](/api/engine/element-api/__GetInlineStyles.md#example)

### [`__GetParent`](/api/engine/element-api/__GetParent.md)

- [Introduction](/api/engine/element-api/__GetParent.md#introduction)
- [Syntax](/api/engine/element-api/__GetParent.md#syntax)
- [Example](/api/engine/element-api/__GetParent.md#example)

### [`__GetTag`](/api/engine/element-api/__GetTag.md)

- [Introduction](/api/engine/element-api/__GetTag.md#introduction)
- [Syntax](/api/engine/element-api/__GetTag.md#syntax)
- [Example](/api/engine/element-api/__GetTag.md#example)

### [`__InsertElementBefore`](/api/engine/element-api/__InsertElementBefore.md)

- [Introduction](/api/engine/element-api/__InsertElementBefore.md#introduction)
- [Syntax](/api/engine/element-api/__InsertElementBefore.md#syntax)
- [Example](/api/engine/element-api/__InsertElementBefore.md#example)

### [`__LastElement`](/api/engine/element-api/__LastElement.md)

- [Introduction](/api/engine/element-api/__LastElement.md#introduction)
- [Syntax](/api/engine/element-api/__LastElement.md#syntax)
- [Example](/api/engine/element-api/__LastElement.md#example)

### [`__NextElement`](/api/engine/element-api/__NextElement.md)

- [Introduction](/api/engine/element-api/__NextElement.md#introduction)
- [Syntax](/api/engine/element-api/__NextElement.md#syntax)
- [Example](/api/engine/element-api/__NextElement.md#example)

### [`__RemoveElement`](/api/engine/element-api/__RemoveElement.md)

- [Introduction](/api/engine/element-api/__RemoveElement.md#introduction)
- [Syntax](/api/engine/element-api/__RemoveElement.md#syntax)
- [Example](/api/engine/element-api/__RemoveElement.md#example)

### [`__ReplaceElement`](/api/engine/element-api/__ReplaceElement.md)

- [Introduction](/api/engine/element-api/__ReplaceElement.md#introduction)
- [Syntax](/api/engine/element-api/__ReplaceElement.md#syntax)
- [Example](/api/engine/element-api/__ReplaceElement.md#example)

### [`__ReplaceElements`](/api/engine/element-api/__ReplaceElements.md)

- [Introduction](/api/engine/element-api/__ReplaceElements.md#introduction)
- [Syntax](/api/engine/element-api/__ReplaceElements.md#syntax)
- [Example](/api/engine/element-api/__ReplaceElements.md#example)

### [`__SetAttribute`](/api/engine/element-api/__SetAttribute.md)

- [Introduction](/api/engine/element-api/__SetAttribute.md#introduction)
- [Syntax](/api/engine/element-api/__SetAttribute.md#syntax)
- [Example](/api/engine/element-api/__SetAttribute.md#example)

### [`__SetClasses`](/api/engine/element-api/__SetClasses.md)

- [Introduction](/api/engine/element-api/__SetClasses.md#introduction)
- [Syntax](/api/engine/element-api/__SetClasses.md#syntax)
- [Example](/api/engine/element-api/__SetClasses.md#example)

### [`__SetConfig`](/api/engine/element-api/__SetConfig.md)

- [Introduction](/api/engine/element-api/__SetConfig.md#introduction)
- [Syntax](/api/engine/element-api/__SetConfig.md#syntax)
- [Example](/api/engine/element-api/__SetConfig.md#example)

### [`__SetCSSId`](/api/engine/element-api/__SetCSSId.md)

- [Introduction](/api/engine/element-api/__SetCSSId.md#introduction)
- [Syntax](/api/engine/element-api/__SetCSSId.md#syntax)
- [Example](/api/engine/element-api/__SetCSSId.md#example)

### [`__SetDataset`](/api/engine/element-api/__SetDataset.md)

- [Introduction](/api/engine/element-api/__SetDataset.md#introduction)
- [Syntax](/api/engine/element-api/__SetDataset.md#syntax)
- [Example](/api/engine/element-api/__SetDataset.md#example)

### [`__SetEvents`](/api/engine/element-api/__SetEvents.md)

- [Introduction](/api/engine/element-api/__SetEvents.md#introduction)
- [Syntax](/api/engine/element-api/__SetEvents.md#syntax)
- [Example](/api/engine/element-api/__SetEvents.md#example)

### [`__SetID`](/api/engine/element-api/__SetID.md)

- [Introduction](/api/engine/element-api/__SetID.md#introduction)
- [Syntax](/api/engine/element-api/__SetID.md#syntax)
- [Example](/api/engine/element-api/__SetID.md#example)

### [`__SetInlineStyles`](/api/engine/element-api/__SetInlineStyles.md)

- [Introduction](/api/engine/element-api/__SetInlineStyles.md#introduction)
- [Syntax](/api/engine/element-api/__SetInlineStyles.md#syntax)
- [Example](/api/engine/element-api/__SetInlineStyles.md#example)

### [`__SwapElement`](/api/engine/element-api/__SwapElement.md)

- [Introduction](/api/engine/element-api/__SwapElement.md#introduction)
- [Syntax](/api/engine/element-api/__SwapElement.md#syntax)
- [Example](/api/engine/element-api/__SwapElement.md#example)

### [`__UpdateComponentID`](/api/engine/element-api/__UpdateComponentID.md)

- [Introduction](/api/engine/element-api/__UpdateComponentID.md#introduction)
- [Syntax](/api/engine/element-api/__UpdateComponentID.md#syntax)
- [Example](/api/engine/element-api/__UpdateComponentID.md#example)
## LynxError

### [LynxError](/api/errors/lynx-error.md)
## Error Codes

### [Error Codes](/api/errors/error-code.md)



---
url: /api/react/index.md
---



# @lynx-js/react

Welcome to the API reference for `@lynx-js/react`, the package that provides the ReactLynx framework. For an introduction to ReactLynx, please visit the [ReactLynx Guides](/react/index.md).

## React APIs

ReactLynx is based on the React 17 API. You can expect the React APIs provided by `@lynx-js/react` to be fully compatible with React 17 or [Preact](https://preactjs.com/guide/v10/switching-to-preact/).

Here is an overview of the APIs provided by ReactLynx. These APIs will behave consistently with those described in the [official React reference](https://react.dev/reference/react) unless otherwise specified. We will also highlight any special considerations for using them on the Lynx platform.

:::details Why is it based on compatibility with React 17?
React officially entered the "concurrent" era starting with [React 18](https://react.dev/blog/2022/03/29/react-v18). Concurrent React features, represented by APIs such as `useTransition` and `useDeferredValue`, have very strict requirements for the scheduling method and concurrency model of the execution environment—including dependencies on or overwriting of browser Web APIs, dependencies on the new architecture of React Native, and more. Lynx has its own characteristics and considerations in architectural evolution, so we chose React 17 as the foundation for ReactLynx, evolving into the Lynx system while retaining the React programming model.

At the same time, we will continue to pay attention to subsequent React advancements, such as [React 19](https://react.dev/blog/2024/04/25/react-19) and [React Compiler](https://react.dev/learn/react-compiler), and attempt to integrate the parts that do not depend on the concurrent architecture into the ReactLynx system.
:::

## Documents

| Document                                                  | Description |
| --------------------------------------------------------- | ----------- |
| [built-in-macros](/api/react/Document.built-in-macros.md) | -           |
| [directives](/api/react/Document.directives.md)           | -           |

## Classes

| Class                                              | Description                                                                                                                                                                                                                                                       |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Component](/api/react/Class.Component.md)         | -                                                                                                                                                                                                                                                                 |
| [MainThreadRef](/api/react/Class.MainThreadRef.md) | A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve states between main thread function calls. The data saved in `current` property of the `MainThreadRef` can be read and written in multiple main thread functions. |
| [PureComponent](/api/react/Class.PureComponent.md) | -                                                                                                                                                                                                                                                                 |

## Interfaces

| Interface                                                                  | Description                                                                                                                  |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [DataProcessorDefinition](/api/react/Interface.DataProcessorDefinition.md) | Definition of DataProcessor(s)                                                                                               |
| [DataProcessors](/api/react/Interface.DataProcessors.md)                   | The data processors that registered with [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors). |
| [GlobalProps](/api/react/Interface.GlobalProps.md)                         | The interface you can extends so that the `useGlobalProps` returning value can be customized                                 |
| [InitData](/api/react/Interface.InitData.md)                               | The interface you can extends so that the `defaultDataProcessor` returning value can be customized                           |
| [InitDataRaw](/api/react/Interface.InitDataRaw.md)                         | The interface you can extends so that the `defaultDataProcessor` parameter can be customized                                 |
| [Lynx](/api/react/Interface.Lynx.md)                                       | APIs under `lynx` global variable that added by ReactLynx.                                                                   |
| [Root](/api/react/Interface.Root.md)                                       | The default root exported by `@lynx-js/react` for you to render a JSX                                                        |

## Variables

| Variable                                                    | Description                                                  |
| ----------------------------------------------------------- | ------------------------------------------------------------ |
| [root](/api/react/Variable.root.md)                         | The default and only root of ReactLynx for you to render JSX |
| [useErrorBoundary](/api/react/Variable.useErrorBoundary.md) | -                                                            |

## Functions

| Function                                                                        | Description                                                                                                                                                                                      |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [cloneElement](/api/react/Function.cloneElement.md)                             | -                                                                                                                                                                                                |
| [createContext](/api/react/Function.createContext.md)                           | Lets you create a Context that components can provide or read.                                                                                                                                   |
| [createElement](/api/react/Function.createElement.md)                           | -                                                                                                                                                                                                |
| [createPortal](/api/react/Function.createPortal.md)                             | Create a `Portal` to continue rendering the vnode tree at a different DOM node.                                                                                                                  |
| [createRef](/api/react/Function.createRef.md)                                   | -                                                                                                                                                                                                |
| [forwardRef](/api/react/Function.forwardRef.md)                                 | Lets your component expose a DOM node to a parent component using a ref.                                                                                                                         |
| [Fragment](/api/react/Function.Fragment.md)                                     | Lets you group elements without a wrapper node.                                                                                                                                                  |
| [isValidElement](/api/react/Function.isValidElement.md)                         | -                                                                                                                                                                                                |
| [lazy](/api/react/Function.lazy.md)                                             | Lets you defer loading a component’s code until it is rendered for the first time.                                                                                                               |
| [memo](/api/react/Function.memo.md)                                             | Lets you skip re-rendering a component when its props are unchanged.                                                                                                                             |
| [runOnBackground](/api/react/Function.runOnBackground.md)                       | `runOnBackground` allows triggering js functions on the background thread asynchronously.                                                                                                        |
| [runOnMainThread](/api/react/Function.runOnMainThread.md)                       | `runOnMainThread` allows triggering main thread functions on the main thread asynchronously.                                                                                                     |
| [Suspense](/api/react/Function.Suspense.md)                                     | Lets you display a fallback until its children have finished loading.                                                                                                                            |
| [useCallback](/api/react/Function.useCallback.md)                               | `useCallback` will return a memoized version of the callback that only changes if one of the `inputs` has changed.                                                                               |
| [useContext](/api/react/Function.useContext.md)                                 | Accepts a context object (the value returned from `React.createContext`) and returns the current context value, as given by the nearest context provider for the given context.                  |
| [useDebugValue](/api/react/Function.useDebugValue.md)                           | `useDebugValue` can be used to display a label for custom hooks in React DevTools.                                                                                                               |
| [useEffect](/api/react/Function.useEffect.md)                                   | Accepts a function that contains imperative, possibly effectful code. The effects run after main thread dom update without blocking it.                                                          |
| [useGlobalProps](/api/react/Function.useGlobalProps.md)                         | A React Hooks for you to get `lynx.__globalProps`. If `lynx.__globalProps` is changed, a re-render will be triggered automatically.                                                              |
| [useGlobalPropsChanged](/api/react/Function.useGlobalPropsChanged.md)           | A React Hooks for you to get notified when `__globalProps` changed.                                                                                                                              |
| [useImperativeHandle](/api/react/Function.useImperativeHandle.md)               | `useImperativeHandle` customizes the instance value that is exposed to parent components when using `ref`. As always, imperative code using refs should be avoided in most cases.                |
| [useInitData](/api/react/Function.useInitData.md)                               | A React Hooks for you to get `initData`. If `initData` is changed, a re-render will be triggered automatically.                                                                                  |
| [useInitDataChanged](/api/react/Function.useInitDataChanged.md)                 | A React Hooks for you to get notified when `initData` changed.                                                                                                                                   |
| [useLayoutEffect](/api/react/Function.useLayoutEffect.md)                       | `useLayoutEffect` is now an alias of `useEffect`. Use `useEffect` instead.                                                                                                                       |
| [useLynxGlobalEventListener](/api/react/Function.useLynxGlobalEventListener.md) | `useLynxGlobalEventListener` helps you `addListener` as early as possible.                                                                                                                       |
| [useMainThreadRef](/api/react/Function.useMainThreadRef.md)                     | Create A `MainThreadRef`.                                                                                                                                                                        |
| [useMemo](/api/react/Function.useMemo.md)                                       | `useMemo` will only recompute the memoized value when one of the `deps` has changed.                                                                                                             |
| [useReducer](/api/react/Function.useReducer.md)                                 | An alternative to `useState`.                                                                                                                                                                    |
| [useRef](/api/react/Function.useRef.md)                                         | `useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. |
| [useState](/api/react/Function.useState.md)                                     | Returns a stateful value, and a function to update it.                                                                                                                                           |
| [useSyncExternalStore](/api/react/Function.useSyncExternalStore.md)             | -                                                                                                                                                                                                |
| [withInitDataInState](/api/react/Function.withInitDataInState.md)               | Higher-Order Component (HOC) that injects `initData` into the state of the given class component.                                                                                                |

## Components

| Function                                                          | Description                                                                                                                                                                                                      |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [GlobalPropsConsumer](/api/react/Function.GlobalPropsConsumer.md) | The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `lynx.__globalProps`. This should be used with [GlobalPropsProvider](/api/react/Function.GlobalPropsProvider.md) |
| [GlobalPropsProvider](/api/react/Function.GlobalPropsProvider.md) | The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `lynx.__globalProps`, you must wrap your JSX inside it                                                           |
| [InitDataConsumer](/api/react/Function.InitDataConsumer.md)       | The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `initData`. This should be used with [InitDataProvider](/api/react/Function.InitDataProvider.md)                 |
| [InitDataProvider](/api/react/Function.InitDataProvider.md)       | The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `initData`, you must wrap your JSX inside it                                                                     |



---
url: /api/react/Document.built-in-macros.md
---



[@lynx-js/react](/api/react/index.md) / built-in-macros

# Built-in Macros

The `@lynx-js/react` package processes built-in macro definitions such as `__BACKGROUND__` and `__MAIN_THREAD__`. During compilation, code blocks with `false` conditions are automatically removed.

## `__BACKGROUND__`

- Type: `boolean`
- Purpose: Controls code execution in background thread environment. Used to determine which code segments should be preserved in background thread code after compilation.

### Usage Examples

#### In Function Components

Here's an example using the `App` component:

```tsx
import { noop } from 'lodash-es';
import { useEffect } from '@lynx-js/react';

function App() {
  const showToast = __BACKGROUND__
    ? () => {
        bridge.call('showToast', {
          message: t('toast'),
          icon: 'success',
        });
      }
    : noop;

  useEffect(showToast, []);
  return <view />;
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = () => {
    bridge.call('showToast', {
      message: t('toast'),
      icon: 'success',
    });
  };
  useEffect(showToast, []);
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = noop_default;

  useEffect();
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

#### In Class Components

Here's an example using the `Conversations` component:

```tsx
import { AppLoggerFactory } from '../utils/appLoggerFactory';

class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    if (__BACKGROUND__) {
      this.appLogger = AppLoggerFactory();
    }
  }
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    this.appLogger = AppLoggerFactory();
  }
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
  }
}
```

## `__MAIN_THREAD__`

- Type: `boolean`
- Purpose: Controls code execution in main thread environment. Used to determine which code segments should be preserved in main thread code during compilation.

### Usage Examples

#### In Function Components

Here's an example using the `App` component:

```tsx
import { noop } from 'lodash-es';
import { useEffect } from '@lynx-js/react';

function App() {
  const showToast = !__MAIN_THREAD__
    ? () => {
        bridge.call('showToast', {
          message: t('toast'),
          icon: 'success',
        });
      }
    : noop;

  useEffect(showToast, []);
  return <view />;
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = () => {
    bridge.call('showToast', {
      message: t('toast'),
      icon: 'success',
    });
  };
  useEffect(showToast, []);
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
function App() {
  const showToast = noop_default;

  useEffect();
  return createSnapshotInstance(__snapshot_5ab440, null, []);
}
```

#### In Class Components

Here's an example using the `Conversations` component:

```tsx
import { AppLoggerFactory } from '../utils/appLoggerFactory';

class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    if (!__MAIN_THREAD__) {
      this.appLogger = AppLoggerFactory();
    }
  }
}
```

After compilation, this code is transformed into:

- Background thread code (`background.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
    this.appLogger = AppLoggerFactory();
  }
}
```

- Main thread code (`main-thread.js` in the compilation intermediate directory):

```tsx
class Conversations extends Component<Props, State> {
  appLogger: AppLogger;

  constructor(props: Props) {
    super(props);
    this.state = {
      showConversationItemAction: false,
      loading: true,
    };
  }
}
```



---
url: /api/react/Document.directives.md
---



[@lynx-js/react](/api/react/index.md) / directives

# Directives

## `'background only'`

The `'background only'` directive allows you to mark functions that will only be executed on the background thread. In other threads, the function body of the marked function will be removed.

To mark a function as background only, simply add the `'background only'` directive at the first line of the function body:

```ts
function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}
```

In the main thread portion of the generated output, this function will be replaced as follows:

```ts
function bgOnlyAction(pureCallback) {}
```

Typically, code with side effects should only be executed in the background thread, such as event listeners, JSB calls, etc. Marking such functions as `'background only'` can significantly reduce the bundle size.

One way to use `'background only'` is in conjunction with custom hooks. For example, `useFirstRender` is a user-defined hook used to execute some logic when a component is first rendered. We want to use it to listen for events. The event listening logic should not and cannot be executed on the main thread. In this case, we can use the `'background only'` directive to mark this function, removing the event listening logic from the main thread.

```ts
import {useFirstRender} from './useFirstRender';

function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}

function Foo({ prop } ){
  const ref = useRef(null);
  useFirstRender(() => {
    bgOnlyAction(() => {
      // ...
    });
  });
  return <view>;
}
```

It is not only the code marked as `'background only'` that will be removed in other threads; ReactLynx will by default remove certain parts of the code, including the parameters of `useEffect`, `useLayoutEffect`, and some event handlers, among others. For these parts, you do not need to mark the corresponding functions as `'background only'`. For more details, refer to [Dual Runtime Code Splitting](/react/thinking-in-reactlynx.md).

## `'main thread'`

The `'main thread'` directive allows you to mark main thread functions. Main thread functions are part of the [Main Thread Script](/react/main-thread-script.md) system and can only be executed on the main thread. They are primarily used for smooth animations and gesture handling.

To convert a background thread function into a main thread function, simply add the `'main thread'` directive at the first line of the function:

```tsx {7}
import {MainThread} from "@lynx-js/types";

export default function App() {
  const red = 'red';

  function handleTap(event: MainThread.TouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={handleTap}>
      <text>Hello World!</text>
    </view>
  );
}
```

A main thread function will automatically capture external variables from the background thread when defined, such as `red` in the example above.

When using a main thread function as an event handler, the main thread function accepts an `event` parameter that contains basic information about the event. The `event.target` and `event.currentTarget` parameters differ from those in regular event handlers; they are [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md) objects. This object allows you to conveniently synchronize the retrieval and setting of node properties, such as using [`setStyleProperty()`] in the example.

Some important notes:

- Main thread functions can and must only run on the main thread. Main thread functions can call each other.
- Captured variables need to be passed between threads using `JSON.stringify()`, so they must be serializable to JSON.
- Main thread functions can only execute after TTI (Time to Interactive). This means they cannot execute during the initial screen load.
- Main thread functions do not support nested definitions.
- The constructor, getter, and setter of class components do not support being specified as main thread functions.
- You cannot modify variables captured from the external scope within a main thread function.

[`setStyleProperty()`]: /api/lynx-api/main-thread/main-thread-element.md#elementsetstyleproperty



---
url: /api/react/Document.global-events.md
---

[@lynx-js/react](/api/react/index.md) / global-events

# Global Events

ReactLynx provides a series of global events that allow developers to listen and respond to application-level state changes. You can easily subscribe to these events in your components using the [`useLynxGlobalEventListener`](/api/react/Function.useLynxGlobalEventListener.md) hook.

## onGlobalPropsChanged

The `onGlobalPropsChanged` event is triggered when the [`lynx.__globalProps`](/api/lynx-api/lynx/lynx-global-props.md) object changes, automatically re-rendering the entire page afterward.
This is useful for components that need to react to global configuration changes, such as themes, languages, etc.

As a result, `onGlobalPropsChanged` is mainly used for handling side effects that are **not directly related to UI rendering**, such as data fetching.

The callback function for this event does not receive any arguments; you can read the latest state directly from [`lynx.__globalProps`](/api/lynx-api/lynx/lynx-global-props.md).

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

function App() {
  useLynxGlobalEventListener('onGlobalPropsChanged', () => {
    console.log('Global props changed:', lynx.__globalProps);
    // You can perform data fetching or other operations here
  });

  return <view>...</view>;
}
```

## onDataChanged

The `onDataChanged` event is triggered when [`initData`](/api/react/Function.useInitData.md) is updated by the client.

[`useInitData`](/api/react/Function.useInitData.md) is a responsive hook that automatically triggers a component re-render when `initData` changes.
The `onDataChanged` event is primarily used to handle side effects that are **not directly related to UI rendering**, such as logging, data analytics, or executing other imperative operations.

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

function DataChangeLogger() {
  useLynxGlobalEventListener('onDataChanged', (data) => {
    console.log('initData changed:', data);
    // You can perform data reporting or other operations here
  });

  return <view>...</view>;
}
```



---
url: /api/react/Document.import-attributes.md
---

[@lynx-js/react](/api/react/index.md) / import-attributes

# Import Attributes

## `runtime: 'shared'`

Explicitly declare that certain modules can be shared between the main thread and the background thread via **Import Attributes**.

This is strictly for use with **[Main Thread Functions](/react/main-thread-script.md)**. For details, please refer to [Cross-thread Shared Modules](/react/main-thread-script.md#cross-thread-shared-modules).

The `runtime` attribute in the `with` clause of an `import` statement specifies the runtime behavior of the imported module. When set to `'shared'`, the module is marked as shared across threads.

### Syntax

```javascript
import { ... } from "module-name" with { runtime: 'shared' };
import "module-name" with { runtime: 'shared' };
```

### Parameters

- `runtime`: `'shared'`

### Examples

```javascript
import { func } from "./utils.js" with {runtime: 'shared'};

function mainThreadFunction() {
  'main thread';
  func(); // Can be called within a main thread function
}
```

### Precautions

1. **Static Analysis**: This feature relies on compile-time static analysis. Only identifiers imported directly via `import ... with { runtime: 'shared' }` are recognized as shared.
2. **Identifier Passing**: If a shared imported function is assigned to another variable, the new variable loses the shared characteristic and cannot be called directly in a main thread function (unless wrapped again as a main thread function).
3. **Main Thread Limitations**: Although code in shared modules can run on the main thread, it does not automatically gain the main thread context (e.g., cannot directly use `MainThreadRef`) unless explicitly marked with `'main thread'`.
4. **State Isolation**: Variables and states in a Shared Module are **completely isolated** between the two threads, each possessing independent instances. Modifying state in one thread does not affect the other.



---
url: /api/react/Class.Component.md
---



[@lynx-js/react](/api/react/index.md) / Component

# Class: Component\<P, S, SS>

## Extends

- `ComponentLifecycle`\<`P`, `S`, `SS`>

## Extended by

- [`PureComponent`](/api/react/Class.PureComponent.md)

## Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | `object`     |
| `S`            | `object`     |
| `SS`           | `any`        |

## Constructors

### new Component()

```ts
new Component<P, S, SS>(props: P): Component<P, S, SS>
```

#### Parameters

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

#### Returns

[`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

#### Inherited from

`ComponentLifecycle<P, S, SS>.constructor`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1017

### new Component()

```ts
new Component<P, S, SS>(props: P, context: any): Component<P, S, SS>
```

#### Parameters

| Parameter | Type  |
| --------- | ----- |
| `props`   | `P`   |
| `context` | `any` |

#### Returns

[`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

#### Deprecated

#### See

[React Docs](https://legacy.reactjs.org/docs/legacy-context.html)

#### Inherited from

`ComponentLifecycle<P, S, SS>.constructor`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1022

## Properties

### context

```ts
context: unknown;
```

If using the new style context, re-declare this in your class to be the
`React.ContextType` of your `static contextType`.
Should be used with type annotation or static contextType.

#### Example

```ts
static contextType = MyContext
// For TS pre-3.7:
context!: React.ContextType<typeof MyContext>
// For TS 3.7 and above:
declare context: React.ContextType<typeof MyContext>
```

#### See

[React Docs](https://react.dev/reference/react/Component#context)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1015

***

### props

```ts
readonly props: Readonly<P>;
```

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1035

***

### ~~refs~~

```ts
refs: object;
```

#### Index Signature

\[`key`: `string`]: `ReactInstance`

#### Deprecated

#### See

[Legacy React Docs](https://legacy.reactjs.org/docs/refs-and-the-dom.html#legacy-api-string-refs)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1042

***

### state

```ts
state: Readonly<S>;
```

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1036

***

### contextType?

```ts
static optional contextType: Context<any>;
```

If set, `this.context` will be set at runtime to the current value of the given Context.

#### Example

```ts
type MyContext = number
const Ctx = React.createContext<MyContext>(0)

class Foo extends React.Component {
  static contextType = Ctx
  context!: React.ContextType<typeof Ctx>
  render () {
    return <>My context's value: {this.context}</>;
  }
}
```

#### See

[https://react.dev/reference/react/Component#static-contexttype](https://react.dev/reference/react/Component#static-contexttype)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:997

## Methods

### componentDidCatch()?

```ts
optional componentDidCatch(error: Error, errorInfo: ErrorInfo): void
```

Catches exceptions generated in descendant components. Unhandled exceptions will cause
the entire component tree to unmount.

#### Parameters

| Parameter   | Type        |
| ----------- | ----------- |
| `error`     | `Error`     |
| `errorInfo` | `ErrorInfo` |

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidCatch`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1399

***

### componentDidMount()?

```ts
optional componentDidMount(): void
```

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidMount`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1378

***

### componentDidUpdate()?

```ts
optional componentDidUpdate(
   prevProps: Readonly<P>, 
   prevState: Readonly<S>, 
   snapshot?: SS): void
```

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/react/Class.Component.md#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |
| `snapshot`? | `SS`             |

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentDidUpdate`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1441

***

### ~~componentWillMount()?~~

```ts
optional componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillMount`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1457

***

### ~~componentWillReceiveProps()?~~

```ts
optional componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillReceiveProps`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1488

***

### componentWillUnmount()?

```ts
optional componentWillUnmount(): void
```

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as
cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

`void`

#### Inherited from

`ComponentLifecycle.componentWillUnmount`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1394

***

### ~~componentWillUpdate()?~~

```ts
optional componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.componentWillUpdate`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1520

***

### forceUpdate()

```ts
forceUpdate(callback?: () => void): void
```

#### Parameters

| Parameter   | Type         |
| ----------- | ------------ |
| `callback`? | () => `void` |

#### Returns

`void`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1032

***

### getSnapshotBeforeUpdate()?

```ts
optional getSnapshotBeforeUpdate(prevProps: Readonly<P>, prevState: Readonly<S>): null | SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.Component.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`null` | `SS`

#### Inherited from

`ComponentLifecycle.getSnapshotBeforeUpdate`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1435

***

### render()

```ts
render(): ReactNode
```

#### Returns

`ReactNode`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1033

***

### setState()

```ts
setState<K>(state: null | S | (prevState: Readonly<S>, props: Readonly<P>) => null | S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter                                 |
| ---------------------------------------------- |
| `K` _extends_ `string` \| `number` \| `symbol` |

#### Parameters

| Parameter   | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `state`     | `null` \| `S` \| (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `null` \| `S` \| `Pick`\<`S`, `K`> \| `Pick`\<`S`, `K`> |
| `callback`? | () => `void`                                                                                                                           |

#### Returns

`void`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1027

***

### shouldComponentUpdate()?

```ts
optional shouldComponentUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): boolean
```

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true.
`PureComponent` implements a shallow comparison on props and state and returns true if any
props or states have changed.

If false is returned, [Component.render](/api/react/Class.Component.md#render), `componentWillUpdate`
and `componentDidUpdate` will not be called.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`boolean`

#### Inherited from

`ComponentLifecycle.shouldComponentUpdate`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1389

***

### ~~UNSAFE\_componentWillMount()?~~

```ts
optional UNSAFE_componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillMount`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1472

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

```ts
optional UNSAFE_componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillReceiveProps`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1506

***

### ~~UNSAFE\_componentWillUpdate()?~~

```ts
optional UNSAFE_componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

`ComponentLifecycle.UNSAFE_componentWillUpdate`

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1536



---
url: /api/react/Class.MainThreadRef.md
---



[@lynx-js/react](/api/react/index.md) / MainThreadRef

# Class: MainThreadRef\<T>

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

## Extends

- `WorkletRef`\<`T`>

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Constructors

### new MainThreadRef()

```ts
new MainThreadRef<T>(initValue: T): MainThreadRef<T>
```

#### Parameters

| Parameter   | Type |
| ----------- | ---- |
| `initValue` | `T`  |

#### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T`>

#### Overrides

`WorkletRef<T>.constructor`

#### Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/ref/workletRef.d.ts:15

## Accessors

### current

#### Get Signature

```ts
get current(): T
```

##### Returns

`T`

#### Set Signature

```ts
set current(_: T): void
```

##### Parameters

| Parameter | Type |
| --------- | ---- |
| `_`       | `T`  |

##### Returns

`void`

#### Inherited from

`WorkletRef.current`

#### Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/ref/workletRef.d.ts:4



---
url: /api/react/Class.PureComponent.md
---



[@lynx-js/react](/api/react/index.md) / PureComponent

# Class: PureComponent\<P, S, SS>

## Extends

- [`Component`](/api/react/Class.Component.md)\<`P`, `S`, `SS`>

## Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `P`            | `object`     |
| `S`            | `object`     |
| `SS`           | `any`        |

## Constructors

### new PureComponent()

```ts
new PureComponent<P, S, SS>(props: P): PureComponent<P, S, SS>
```

#### Parameters

| Parameter | Type |
| --------- | ---- |
| `props`   | `P`  |

#### Returns

[`PureComponent`](/api/react/Class.PureComponent.md)\<`P`, `S`, `SS`>

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`constructor`](/api/react/Class.Component.md#constructors)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1017

### new PureComponent()

```ts
new PureComponent<P, S, SS>(props: P, context: any): PureComponent<P, S, SS>
```

#### Parameters

| Parameter | Type  |
| --------- | ----- |
| `props`   | `P`   |
| `context` | `any` |

#### Returns

[`PureComponent`](/api/react/Class.PureComponent.md)\<`P`, `S`, `SS`>

#### Deprecated

#### See

[React Docs](https://legacy.reactjs.org/docs/legacy-context.html)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`constructor`](/api/react/Class.Component.md#constructors)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1022

## Properties

### context

```ts
context: unknown;
```

If using the new style context, re-declare this in your class to be the
`React.ContextType` of your `static contextType`.
Should be used with type annotation or static contextType.

#### Example

```ts
static contextType = MyContext
// For TS pre-3.7:
context!: React.ContextType<typeof MyContext>
// For TS 3.7 and above:
declare context: React.ContextType<typeof MyContext>
```

#### See

[React Docs](https://react.dev/reference/react/Component#context)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`context`](/api/react/Class.Component.md#context)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1015

***

### props

```ts
readonly props: Readonly<P>;
```

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`props`](/api/react/Class.Component.md#props)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1035

***

### ~~refs~~

```ts
refs: object;
```

#### Index Signature

\[`key`: `string`]: `ReactInstance`

#### Deprecated

#### See

[Legacy React Docs](https://legacy.reactjs.org/docs/refs-and-the-dom.html#legacy-api-string-refs)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`refs`](/api/react/Class.Component.md#refs)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1042

***

### state

```ts
state: Readonly<S>;
```

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`state`](/api/react/Class.Component.md#state)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1036

***

### contextType?

```ts
static optional contextType: Context<any>;
```

If set, `this.context` will be set at runtime to the current value of the given Context.

#### Example

```ts
type MyContext = number
const Ctx = React.createContext<MyContext>(0)

class Foo extends React.Component {
  static contextType = Ctx
  context!: React.ContextType<typeof Ctx>
  render () {
    return <>My context's value: {this.context}</>;
  }
}
```

#### See

[https://react.dev/reference/react/Component#static-contexttype](https://react.dev/reference/react/Component#static-contexttype)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`contextType`](/api/react/Class.Component.md#contexttype)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:997

## Methods

### componentDidCatch()?

```ts
optional componentDidCatch(error: Error, errorInfo: ErrorInfo): void
```

Catches exceptions generated in descendant components. Unhandled exceptions will cause
the entire component tree to unmount.

#### Parameters

| Parameter   | Type        |
| ----------- | ----------- |
| `error`     | `Error`     |
| `errorInfo` | `ErrorInfo` |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidCatch`](/api/react/Class.Component.md#componentdidcatch)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1399

***

### componentDidMount()?

```ts
optional componentDidMount(): void
```

Called immediately after a component is mounted. Setting state here will trigger re-rendering.

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidMount`](/api/react/Class.Component.md#componentdidmount)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1378

***

### componentDidUpdate()?

```ts
optional componentDidUpdate(
   prevProps: Readonly<P>, 
   prevState: Readonly<S>, 
   snapshot?: SS): void
```

Called immediately after updating occurs. Not called for the initial render.

The snapshot is only present if [getSnapshotBeforeUpdate](/api/react/Class.PureComponent.md#getsnapshotbeforeupdate) is present and returns non-null.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |
| `snapshot`? | `SS`             |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentDidUpdate`](/api/react/Class.Component.md#componentdidupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1441

***

### ~~componentWillMount()?~~

```ts
optional componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillMount`](/api/react/Class.Component.md#componentwillmount)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1457

***

### ~~componentWillReceiveProps()?~~

```ts
optional componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillReceiveProps`](/api/react/Class.Component.md#componentwillreceiveprops)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1488

***

### componentWillUnmount()?

```ts
optional componentWillUnmount(): void
```

Called immediately before a component is destroyed. Perform any necessary cleanup in this method, such as
cancelled network requests, or cleaning up any DOM elements created in `componentDidMount`.

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillUnmount`](/api/react/Class.Component.md#componentwillunmount)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1394

***

### ~~componentWillUpdate()?~~

```ts
optional componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`componentWillUpdate`](/api/react/Class.Component.md#componentwillupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1520

***

### forceUpdate()

```ts
forceUpdate(callback?: () => void): void
```

#### Parameters

| Parameter   | Type         |
| ----------- | ------------ |
| `callback`? | () => `void` |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`forceUpdate`](/api/react/Class.Component.md#forceupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1032

***

### getSnapshotBeforeUpdate()?

```ts
optional getSnapshotBeforeUpdate(prevProps: Readonly<P>, prevState: Readonly<S>): null | SS
```

Runs before React applies the result of [render](/api/react/Class.Component.md#render) to the document, and
returns an object to be given to [componentDidUpdate](/api/react/Class.PureComponent.md#componentdidupdate). Useful for saving
things such as scroll position before [render](/api/react/Class.Component.md#render) causes changes to it.

Note: the presence of this method prevents any of the deprecated
lifecycle events from running.

#### Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `prevProps` | `Readonly`\<`P`> |
| `prevState` | `Readonly`\<`S`> |

#### Returns

`null` | `SS`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`getSnapshotBeforeUpdate`](/api/react/Class.Component.md#getsnapshotbeforeupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1435

***

### render()

```ts
render(): ReactNode
```

#### Returns

`ReactNode`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`render`](/api/react/Class.Component.md#render)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1033

***

### setState()

```ts
setState<K>(state: null | S | (prevState: Readonly<S>, props: Readonly<P>) => null | S | Pick<S, K> | Pick<S, K>, callback?: () => void): void
```

#### Type Parameters

| Type Parameter                                 |
| ---------------------------------------------- |
| `K` _extends_ `string` \| `number` \| `symbol` |

#### Parameters

| Parameter   | Type                                                                                                                                   |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `state`     | `null` \| `S` \| (`prevState`: `Readonly`\<`S`>, `props`: `Readonly`\<`P`>) => `null` \| `S` \| `Pick`\<`S`, `K`> \| `Pick`\<`S`, `K`> |
| `callback`? | () => `void`                                                                                                                           |

#### Returns

`void`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`setState`](/api/react/Class.Component.md#setstate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1027

***

### shouldComponentUpdate()?

```ts
optional shouldComponentUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): boolean
```

Called to determine whether the change in props and state should trigger a re-render.

`Component` always returns true.
`PureComponent` implements a shallow comparison on props and state and returns true if any
props or states have changed.

If false is returned, [Component.render](/api/react/Class.Component.md#render), `componentWillUpdate`
and `componentDidUpdate` will not be called.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`boolean`

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`shouldComponentUpdate`](/api/react/Class.Component.md#shouldcomponentupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1389

***

### ~~UNSAFE\_componentWillMount()?~~

```ts
optional UNSAFE_componentWillMount(): void
```

Called immediately before mounting occurs, and before [Component.render](/api/react/Class.Component.md#render).
Avoid introducing any side-effects or subscriptions in this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Returns

`void`

#### Deprecated

16.3, use ComponentLifecycle.componentDidMount componentDidMount or the constructor instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillMount`](/api/react/Class.Component.md#unsafe_componentwillmount)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1472

***

### ~~UNSAFE\_componentWillReceiveProps()?~~

```ts
optional UNSAFE_componentWillReceiveProps(nextProps: Readonly<P>, nextContext: any): void
```

Called when the component may be receiving new props.
React may call this even if props have not changed, so be sure to compare new and existing
props if you only want to handle changes.

Calling [Component.setState](/api/react/Class.Component.md#setstate) generally does not trigger this method.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use static StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillReceiveProps`](/api/react/Class.Component.md#unsafe_componentwillreceiveprops)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1506

***

### ~~UNSAFE\_componentWillUpdate()?~~

```ts
optional UNSAFE_componentWillUpdate(
   nextProps: Readonly<P>, 
   nextState: Readonly<S>, 
   nextContext: any): void
```

Called immediately before rendering when new props or state is received. Not called for the initial render.

Note: You cannot call [Component.setState](/api/react/Class.Component.md#setstate) here.

This method will not stop working in React 17.

Note: the presence of NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate
or StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps prevents
this from being invoked.

#### Parameters

| Parameter     | Type             |
| ------------- | ---------------- |
| `nextProps`   | `Readonly`\<`P`> |
| `nextState`   | `Readonly`\<`S`> |
| `nextContext` | `any`            |

#### Returns

`void`

#### Deprecated

16.3, use getSnapshotBeforeUpdate instead

#### See

- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update)
- [https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path](https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path)

#### Inherited from

[`Component`](/api/react/Class.Component.md).[`UNSAFE_componentWillUpdate`](/api/react/Class.Component.md#unsafe_componentwillupdate)

#### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1536



---
url: /api/react/Function.cloneElement.md
---



[@lynx-js/react](/api/react/index.md) / cloneElement

# Function: cloneElement()

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: DetailedReactHTMLElement<P, T>, 
   props?: P, ...
children?: ReactNode[]): DetailedReactHTMLElement<P, T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                                  |
| -------------- | ------------------------------------- |
| `element`      | `DetailedReactHTMLElement`\<`P`, `T`> |
| `props`?       | `P`                                   |
| ...`children`? | `ReactNode`\[]                        |

### Returns

`DetailedReactHTMLElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:571

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: ReactHTMLElement<T>, 
   props?: P, ...
children?: ReactNode[]): ReactHTMLElement<T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                     |
| -------------- | ------------------------ |
| `element`      | `ReactHTMLElement`\<`T`> |
| `props`?       | `P`                      |
| ...`children`? | `ReactNode`\[]           |

### Returns

`ReactHTMLElement`\<`T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:577

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: ReactSVGElement, 
   props?: P, ...
   children?: ReactNode[]): ReactSVGElement
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `SVGAttributes`\<`T`, `P`> |
| `T` _extends_ `SVGElement`\<`T`>         |

### Parameters

| Parameter      | Type              |
| -------------- | ----------------- |
| `element`      | `ReactSVGElement` |
| `props`?       | `P`               |
| ...`children`? | `ReactNode`\[]    |

### Returns

`ReactSVGElement`

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:583

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: DOMElement<P, T>, 
   props?: DOMAttributes<T> & P, ...
children?: ReactNode[]): DOMElement<P, T>
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `DOMAttributes`\<`T`, `P`> |
| `T` _extends_ `Element`\<`T`>            |

### Parameters

| Parameter      | Type                        |
| -------------- | --------------------------- |
| `element`      | `DOMElement`\<`P`, `T`>     |
| `props`?       | `DOMAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]              |

### Returns

`DOMElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:589

## cloneElement(element, props, children)

```ts
function cloneElement<P>(
   element: FunctionComponentElement<P>, 
   props?: Partial<P> & Attributes, ...
children?: ReactNode[]): FunctionComponentElement<P>
```

### Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

### Parameters

| Parameter      | Type                             |
| -------------- | -------------------------------- |
| `element`      | `FunctionComponentElement`\<`P`> |
| `props`?       | `Partial`\<`P`> & `Attributes`   |
| ...`children`? | `ReactNode`\[]                   |

### Returns

`FunctionComponentElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:596

## cloneElement(element, props, children)

```ts
function cloneElement<P, T>(
   element: CElement<P, T>, 
   props?: Partial<P> & ClassAttributes<T>, ...
children?: ReactNode[]): CElement<P, T>
```

### Type Parameters

| Type Parameter                                                                      |
| ----------------------------------------------------------------------------------- |
| `P`                                                                                 |
| `T` _extends_ [`Component`](/api/react/Class.Component.md)\<`P`, `any`, `any`, `T`> |

### Parameters

| Parameter      | Type                                      |
| -------------- | ----------------------------------------- |
| `element`      | `CElement`\<`P`, `T`>                     |
| `props`?       | `Partial`\<`P`> & `ClassAttributes`\<`T`> |
| ...`children`? | `ReactNode`\[]                            |

### Returns

`CElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:601

## cloneElement(element, props, children)

```ts
function cloneElement<P>(
   element: ReactElement<P, string | JSXElementConstructor<any>>, 
   props?: Partial<P> & Attributes, ...
children?: ReactNode[]): ReactElement<P>
```

### Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

### Parameters

| Parameter      | Type                                                              |
| -------------- | ----------------------------------------------------------------- |
| `element`      | `ReactElement`\<`P`, `string` \| `JSXElementConstructor`\<`any`>> |
| `props`?       | `Partial`\<`P`> & `Attributes`                                    |
| ...`children`? | `ReactNode`\[]                                                    |

### Returns

`ReactElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:606



---
url: /api/react/Function.createContext.md
---



[@lynx-js/react](/api/react/index.md) / createContext

# Function: createContext()

```ts
function createContext<T>(defaultValue: T): Context<T>
```

Lets you create a Context that components can provide or read.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter      | Type | Description                                                                                                                                                               |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultValue` | `T`  | The value you want the context to have when there is no matching Provider in the tree above the component reading the context. This is meant as a "last resort" fallback. |

## Returns

`Context`\<`T`>

## See

- [React Docs](https://react.dev/reference/react/createContext#reference)
- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/)

## Example

```tsx
import { createContext } from 'react';

const ThemeContext = createContext('light');
```

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:783



---
url: /api/react/Function.createElement.md
---



[@lynx-js/react](/api/react/index.md) / createElement

# Function: createElement()

## createElement(type, props, children)

```ts
function createElement(
   type: "input", 
   props?: null | InputHTMLAttributes<HTMLInputElement> & ClassAttributes<HTMLInputElement>, ...
children?: ReactNode[]): DetailedReactHTMLElement<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>
```

### Parameters

| Parameter      | Type                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------- |
| `type`         | `"input"`                                                                                     |
| `props`?       | `null` \| `InputHTMLAttributes`\<`HTMLInputElement`> & `ClassAttributes`\<`HTMLInputElement`> |
| ...`children`? | `ReactNode`\[]                                                                                |

### Returns

`DetailedReactHTMLElement`\<`InputHTMLAttributes`\<`HTMLInputElement`>, `HTMLInputElement`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:530

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: keyof ReactHTML, 
   props?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): DetailedReactHTMLElement<P, T>
```

### Type Parameters

| Type Parameter                            |
| ----------------------------------------- |
| `P` _extends_ `HTMLAttributes`\<`T`, `P`> |
| `T` _extends_ `HTMLElement`\<`T`>         |

### Parameters

| Parameter      | Type                                    |
| -------------- | --------------------------------------- |
| `type`         | keyof `ReactHTML`                       |
| `props`?       | `null` \| `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                          |

### Returns

`DetailedReactHTMLElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:535

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: keyof ReactSVG, 
   props?: null | ClassAttributes<T> & P, ...
   children?: ReactNode[]): ReactSVGElement
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `SVGAttributes`\<`T`, `P`> |
| `T` _extends_ `SVGElement`\<`T`>         |

### Parameters

| Parameter      | Type                                    |
| -------------- | --------------------------------------- |
| `type`         | keyof `ReactSVG`                        |
| `props`?       | `null` \| `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                          |

### Returns

`ReactSVGElement`

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:540

## createElement(type, props, children)

```ts
function createElement<P, T>(
   type: string, 
   props?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): DOMElement<P, T>
```

### Type Parameters

| Type Parameter                           |
| ---------------------------------------- |
| `P` _extends_ `DOMAttributes`\<`T`, `P`> |
| `T` _extends_ `Element`\<`T`>            |

### Parameters

| Parameter      | Type                                    |
| -------------- | --------------------------------------- |
| `type`         | `string`                                |
| `props`?       | `null` \| `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                          |

### Returns

`DOMElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:545

## createElement(type, props, children)

```ts
function createElement<P>(
   type: FunctionComponent<P>, 
   props?: null | Attributes & P, ...
children?: ReactNode[]): FunctionComponentElement<P>
```

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter      | Type                         |
| -------------- | ---------------------------- |
| `type`         | `FunctionComponent`\<`P`>    |
| `props`?       | `null` \| `Attributes` & `P` |
| ...`children`? | `ReactNode`\[]               |

### Returns

`FunctionComponentElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:553

## createElement(type, props, children)

```ts
function createElement<P, T, C>(
   type: ClassType<P, T, C>, 
   props?: null | ClassAttributes<T> & P, ...
children?: ReactNode[]): CElement<P, T>
```

### Type Parameters

| Type Parameter                                                                      |
| ----------------------------------------------------------------------------------- |
| `P` _extends_ `object`                                                              |
| `T` _extends_ [`Component`](/api/react/Class.Component.md)\<`P`, `any`, `any`, `T`> |
| `C` _extends_ `ComponentClass`\<`P`, `any`, `C`>                                    |

### Parameters

| Parameter      | Type                                    |
| -------------- | --------------------------------------- |
| `type`         | `ClassType`\<`P`, `T`, `C`>             |
| `props`?       | `null` \| `ClassAttributes`\<`T`> & `P` |
| ...`children`? | `ReactNode`\[]                          |

### Returns

`CElement`\<`P`, `T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:558

## createElement(type, props, children)

```ts
function createElement<P>(
   type: string | FunctionComponent<P> | ComponentClass<P, any>, 
   props?: null | Attributes & P, ...
children?: ReactNode[]): ReactElement<P>
```

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter      | Type                                                                   |
| -------------- | ---------------------------------------------------------------------- |
| `type`         | `string` \| `FunctionComponent`\<`P`> \| `ComponentClass`\<`P`, `any`> |
| `props`?       | `null` \| `Attributes` & `P`                                           |
| ...`children`? | `ReactNode`\[]                                                         |

### Returns

`ReactElement`\<`P`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:563



---
url: /api/react/Function.createPortal.md
---



[@lynx-js/react](/api/react/index.md) / createPortal

# Function: createPortal()

```ts
function createPortal(vnode: ComponentChild, container: NodesRef): useErrorBoundary<any> | null
```

Create a `Portal` to continue rendering the vnode tree at a different DOM node.

## Parameters

| Parameter   | Type             |
| ----------- | ---------------- |
| `vnode`     | `ComponentChild` |
| `container` | `NodesRef`       |

## Returns

[`useErrorBoundary`](/api/react/Variable.useErrorBoundary.md)\<`any`> | `null`

## Defined in

@lynx-js/react/runtime/lib/snapshot/lynx/portals.d.ts:9



---
url: /api/react/Function.createRef.md
---



[@lynx-js/react](/api/react/index.md) / createRef

# Function: createRef()

```ts
function createRef<T>(): RefObject<T>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Returns

`RefObject`\<`T`>

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1570



---
url: /api/react/Function.forwardRef.md
---



[@lynx-js/react](/api/react/index.md) / forwardRef

# Function: forwardRef()

```ts
function forwardRef<T, P>(render: ForwardRefRenderFunction<T, PropsWithoutRef<P>>): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>
```

Lets your component expose a DOM node to a parent component
using a ref.

## Type Parameters

| Type Parameter | Default type | Description                              |
| -------------- | ------------ | ---------------------------------------- |
| `T`            | -            | The type of the DOM node.                |
| `P`            | `object`     | The props the component accepts, if any. |

## Parameters

| Parameter | Type                                                      | Description                       |
| --------- | --------------------------------------------------------- | --------------------------------- |
| `render`  | `ForwardRefRenderFunction`\<`T`, `PropsWithoutRef`\<`P`>> | See the ForwardRefRenderFunction. |

## Returns

`ForwardRefExoticComponent`\<`PropsWithoutRef`\<`P`> & `RefAttributes`\<`T`>>

## See

- [React Docs](https://react.dev/reference/react/forwardRef)
- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/)

## Example

```tsx
interface Props {
  children?: ReactNode;
  type: "submit" | "button";
}

export const FancyButton = forwardRef<HTMLButtonElement, Props>((props, ref) => (
  <button ref={ref} className="MyClassName" type={props.type}>
    {props.children}
  </button>
));
```

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1614



---
url: /api/react/Function.Fragment.md
---



[@lynx-js/react](/api/react/index.md) / Fragment

# Function: Fragment()

```ts
function Fragment(props: object): null | ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you group elements without a wrapper node.

## Parameters

| Parameter         | Type        |
| ----------------- | ----------- |
| `props`           | `object`    |
| `props.children`? | `ReactNode` |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Fragment)

## Examples

```tsx
import { Fragment } from 'react';

<Fragment>
  <td>Hello</td>
  <td>World</td>
</Fragment>
```

```tsx
// Using the <></> shorthand syntax:

<>
  <td>Hello</td>
  <td>World</td>
</>
```

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:831



---
url: /api/react/Function.GlobalPropsConsumer.md
---



[@lynx-js/react](/api/react/index.md) / GlobalPropsConsumer

# Function: GlobalPropsConsumer()

```ts
function GlobalPropsConsumer(props: ConsumerProps<GlobalProps>): null | ReactElement<any, string | JSXElementConstructor<any>>
```

The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `lynx.__globalProps`.
This should be used with [GlobalPropsProvider](/api/react/Function.GlobalPropsProvider.md)

## Parameters

| Parameter | Type                                                                   |
| --------- | ---------------------------------------------------------------------- |
| `props`   | `ConsumerProps`\<[`GlobalProps`](/api/react/Interface.GlobalProps.md)> |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:175



---
url: /api/react/Function.GlobalPropsProvider.md
---



[@lynx-js/react](/api/react/index.md) / GlobalPropsProvider

# Function: GlobalPropsProvider()

```ts
function GlobalPropsProvider(props: object, deprecatedLegacyContext?: any): null | ReactElement<any, any>
```

The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `lynx.__globalProps`,
you must wrap your JSX inside it

## Parameters

| Parameter                  | Type        | Description                                                                                                                       |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `props`                    | `object`    | -                                                                                                                                 |
| `props.children`?          | `ReactNode` | -                                                                                                                                 |
| `deprecatedLegacyContext`? | `any`       | **Deprecated** **See** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |

## Returns

`null` | `ReactElement`\<`any`, `any`>

## Example

```ts
import { root } from "@lynx-js/react"

function App() {
  return (
    <GlobalPropsConsumer children={(globalProps) => <view>...</view>}/>
  )
}

root.render(
  <GlobalPropsProvider>
     <App/>
  </GlobalPropsProvider>
);

```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:166



---
url: /api/react/Function.InitDataConsumer.md
---



[@lynx-js/react](/api/react/index.md) / InitDataConsumer

# Function: InitDataConsumer()

```ts
function InitDataConsumer(props: ConsumerProps<InitData>): null | ReactElement<any, string | JSXElementConstructor<any>>
```

The [Consumer](https://react.dev/reference/react/createContext#consumer) Component that provide `initData`.
This should be used with [InitDataProvider](/api/react/Function.InitDataProvider.md)

## Parameters

| Parameter | Type                                                             |
| --------- | ---------------------------------------------------------------- |
| `props`   | `ConsumerProps`\<[`InitData`](/api/react/Interface.InitData.md)> |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:107



---
url: /api/react/Function.InitDataProvider.md
---



[@lynx-js/react](/api/react/index.md) / InitDataProvider

# Function: InitDataProvider()

```ts
function InitDataProvider(props: object, deprecatedLegacyContext?: any): null | ReactElement<any, any>
```

The [Provider](https://react.dev/reference/react/createContext#provider) Component that provide `initData`,
you must wrap your JSX inside it

## Parameters

| Parameter                  | Type        | Description                                                                                                                       |
| -------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `props`                    | `object`    | -                                                                                                                                 |
| `props.children`?          | `ReactNode` | -                                                                                                                                 |
| `deprecatedLegacyContext`? | `any`       | **Deprecated** **See** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |

## Returns

`null` | `ReactElement`\<`any`, `any`>

## Example

```ts
import { root } from "@lynx-js/react"

function App() {
  return (
    <InitDataConsumer children={(initData) => <view>...</view>}/>
  )
}

root.render(
  <InitDataProvider>
     <App/>
  </InitDataProvider>
);

```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:98



---
url: /api/react/Function.isValidElement.md
---



[@lynx-js/react](/api/react/index.md) / isValidElement

# Function: isValidElement()

```ts
function isValidElement<P>(object: undefined | null | object): object is ReactElement<P, string | JSXElementConstructor<any>>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `P`            |

## Parameters

| Parameter | Type                              |
| --------- | --------------------------------- |
| `object`  | `undefined` \| `null` \| `object` |

## Returns

object is ReactElement\<P, string | JSXElementConstructor\<any>>

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:789



---
url: /api/react/Function.lazy.md
---



[@lynx-js/react](/api/react/index.md) / lazy

# Function: lazy()

```ts
function lazy<T>(load: () => Promise<object>): LazyExoticComponent<T>
```

Lets you defer loading a component’s code until it is rendered for the first time.

## Type Parameters

| Type Parameter                        |
| ------------------------------------- |
| `T` _extends_ `ComponentType`\<`any`> |

## Parameters

| Parameter | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `load`    | () => `Promise`\<`object`> | A function that returns a `Promise` or another thenable (a `Promise`-like object with a then method). React will not call `load` until the first time you attempt to render the returned component. After React first calls load, it will wait for it to resolve, and then render the resolved value’s `.default` as a React component. Both the returned `Promise` and the `Promise`’s resolved value will be cached, so React will not call load more than once. If the `Promise` rejects, React will throw the rejection reason for the nearest Error Boundary to handle. |

## Returns

`LazyExoticComponent`\<`T`>

## See

[React Docs](https://react.dev/reference/react/lazy)

## Example

```tsx
import { lazy } from 'react';

const MarkdownPreview = lazy(() => import('./MarkdownPreview.js'));
```

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1810



---
url: /api/react/Function.memo.md
---



[@lynx-js/react](/api/react/index.md) / memo

# Function: memo()

## memo(Component, propsAreEqual)

```ts
function memo<P>(Component: FunctionComponent<P>, propsAreEqual?: (prevProps: Readonly<P>, nextProps: Readonly<P>) => boolean): NamedExoticComponent<P>
```

Lets you skip re-rendering a component when its props are unchanged.

### Type Parameters

| Type Parameter         |
| ---------------------- |
| `P` _extends_ `object` |

### Parameters

| Parameter        | Type                                                                        | Description                                                          |
| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Component`      | `FunctionComponent`\<`P`>                                                   | The component to memoize.                                            |
| `propsAreEqual`? | (`prevProps`: `Readonly`\<`P`>, `nextProps`: `Readonly`\<`P`>) => `boolean` | A function that will be used to determine if the props have changed. |

### Returns

`NamedExoticComponent`\<`P`>

### See

[React Docs](https://react.dev/reference/react/memo)

### Example

```tsx
import { memo } from 'react';

const SomeComponent = memo(function SomeComponent(props: { foo: string }) {
  // ...
});
```

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1775

## memo(Component, propsAreEqual)

```ts
function memo<T>(Component: T, propsAreEqual?: (prevProps: Readonly<ComponentProps<T>>, nextProps: Readonly<ComponentProps<T>>) => boolean): MemoExoticComponent<T>
```

### Type Parameters

| Type Parameter                        |
| ------------------------------------- |
| `T` _extends_ `ComponentType`\<`any`> |

### Parameters

| Parameter        | Type                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `Component`      | `T`                                                                                                               |
| `propsAreEqual`? | (`prevProps`: `Readonly`\<`ComponentProps`\<`T`>>, `nextProps`: `Readonly`\<`ComponentProps`\<`T`>>) => `boolean` |

### Returns

`MemoExoticComponent`\<`T`>

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1779



---
url: /api/react/Function.runOnBackground.md
---



[@lynx-js/react](/api/react/index.md) / runOnBackground

# Function: runOnBackground()

```ts
function runOnBackground<R, Fn>(f: Fn): (...args: Parameters<Fn>) => Promise<R>
```

`runOnBackground` allows triggering js functions on the background thread asynchronously.

## Type Parameters

| Type Parameter                              |
| ------------------------------------------- |
| `R`                                         |
| `Fn` _extends_ (...`args`: `any`\[]) => `R` |

## Parameters

| Parameter | Type | Description                   |
| --------- | ---- | ----------------------------- |
| `f`       | `Fn` | The js function to be called. |

## Returns

`Function`

A function. Calling which with the arguments to be passed to the js function to trigger it on the background thread. This function returns a promise that resolves to the return value of the js function.

### Parameters

| Parameter | Type                |
| --------- | ------------------- |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`Promise`\<`R`>

## Example

```ts
import { runOnBackground } from '@lynx-js/react';

async function someMainthreadFunction() {
  'main thread';
  const fn = runOnBackground(() => {
    return 'hello';
  });
  const result = await fn();
}
```

## Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/call/runOnBackground.d.ts:19



---
url: /api/react/Function.runOnMainThread.md
---



[@lynx-js/react](/api/react/index.md) / runOnMainThread

# Function: runOnMainThread()

```ts
function runOnMainThread<R, Fn>(fn: Fn): (...args: Parameters<Fn>) => Promise<R>
```

`runOnMainThread` allows triggering main thread functions on the main thread asynchronously.

## Type Parameters

| Type Parameter                              |
| ------------------------------------------- |
| `R`                                         |
| `Fn` _extends_ (...`args`: `any`\[]) => `R` |

## Parameters

| Parameter | Type | Description                             |
| --------- | ---- | --------------------------------------- |
| `fn`      | `Fn` | The main thread functions to be called. |

## Returns

`Function`

A function. Calling which with the arguments to be passed to the main thread function to trigger it on the main thread. This function returns a promise that resolves to the return value of the main thread function.

### Parameters

| Parameter | Type                |
| --------- | ------------------- |
| ...`args` | `Parameters`\<`Fn`> |

### Returns

`Promise`\<`R`>

## Example

```ts
import { runOnMainThread } from '@lynx-js/react';

async function someFunction() {
  const fn = runOnMainThread(() => {
    'main thread';
    return 'hello';
  });
  const result = await fn();
}
```

## Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/call/runOnMainThread.d.ts:19



---
url: /api/react/Function.Suspense.md
---



[@lynx-js/react](/api/react/index.md) / Suspense

# Function: Suspense()

```ts
function Suspense(props: SuspenseProps): null | ReactElement<any, string | JSXElementConstructor<any>>
```

Lets you display a fallback until its children have finished loading.

## Parameters

| Parameter | Type            |
| --------- | --------------- |
| `props`   | `SuspenseProps` |

## Returns

`null` | `ReactElement`\<`any`, `string` | `JSXElementConstructor`\<`any`>>

## See

[React Docs](https://react.dev/reference/react/Suspense)

## Example

```tsx
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
```

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:883



---
url: /api/react/Function.useCallback.md
---



[@lynx-js/react](/api/react/index.md) / useCallback

# Function: useCallback()

```ts
function useCallback<T>(callback: T, deps: DependencyList): T
```

`useCallback` will return a memoized version of the callback that only changes if one of the `inputs`
has changed.

## Type Parameters

| Type Parameter           |
| ------------------------ |
| `T` _extends_ `Function` |

## Parameters

| Parameter  | Type             |
| ---------- | ---------------- |
| `callback` | `T`              |
| `deps`     | `DependencyList` |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useCallback](https://react.dev/reference/react/useCallback)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2070



---
url: /api/react/Function.useContext.md
---



[@lynx-js/react](/api/react/index.md) / useContext

# Function: useContext()

```ts
function useContext<T>(context: Context<T>): T
```

Accepts a context object (the value returned from `React.createContext`) and returns the current
context value, as given by the nearest context provider for the given context.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type            |
| --------- | --------------- |
| `context` | `Context`\<`T`> |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useContext](https://react.dev/reference/react/useContext)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1877



---
url: /api/react/Function.useDebugValue.md
---



[@lynx-js/react](/api/react/index.md) / useDebugValue

# Function: useDebugValue()

```ts
function useDebugValue<T>(value: T, format?: (value: T) => any): void
```

`useDebugValue` can be used to display a label for custom hooks in React DevTools.

NOTE: We don’t recommend adding debug values to every custom hook.
It’s most valuable for custom hooks that are part of shared libraries.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type                    |
| --------- | ----------------------- |
| `value`   | `T`                     |
| `format`? | (`value`: `T`) => `any` |

## Returns

`void`

## Version

16.8.0

## See

[https://react.dev/reference/react/useDebugValue](https://react.dev/reference/react/useDebugValue)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2090



---
url: /api/react/Function.useEffect.md
---



[@lynx-js/react](/api/react/index.md) / useEffect

# Function: useEffect()

```ts
function useEffect(effect: EffectCallback, deps?: DependencyList): void
```

Accepts a function that contains imperative, possibly effectful code.
The effects run after main thread dom update without blocking it.

## Parameters

| Parameter | Type             | Description                                                                         |
| --------- | ---------------- | ----------------------------------------------------------------------------------- |
| `effect`  | `EffectCallback` | Imperative function that can return a cleanup function                              |
| `deps`?   | `DependencyList` | If present, effect will only activate if the values in the list change (using ===). |

## Returns

`void`

## Defined in

@lynx-js/react/runtime/lib/core/hooks/react.d.ts:13



---
url: /api/react/Function.useGlobalProps.md
---



[@lynx-js/react](/api/react/index.md) / useGlobalProps

# Function: useGlobalProps()

```ts
function useGlobalProps(): GlobalProps
```

A React Hooks for you to get `lynx.__globalProps`.
If `lynx.__globalProps` is changed, a re-render will be triggered automatically.

## Returns

[`GlobalProps`](/api/react/Interface.GlobalProps.md)

## Example

```ts
function App() {
  const globalProps = useGlobalProps();

  globalProps.someProperty // use it
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:192



---
url: /api/react/Function.useGlobalPropsChanged.md
---



[@lynx-js/react](/api/react/index.md) / useGlobalPropsChanged

# Function: useGlobalPropsChanged()

```ts
function useGlobalPropsChanged(callback: (data: GlobalProps) => void): void
```

A React Hooks for you to get notified when `__globalProps` changed.

## Parameters

| Parameter  | Type                                                                     |
| ---------- | ------------------------------------------------------------------------ |
| `callback` | (`data`: [`GlobalProps`](/api/react/Interface.GlobalProps.md)) => `void` |

## Returns

`void`

## Example

```ts
function App() {
  useGlobalPropsChanged((data) => {
    lynx.__globalProps.someProperty // can use lynx.__globalProps
    data.someProperty // can use data
  })
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:207



---
url: /api/react/Function.useImperativeHandle.md
---



[@lynx-js/react](/api/react/index.md) / useImperativeHandle

# Function: useImperativeHandle()

```ts
function useImperativeHandle<T, R>(
   ref: undefined | Ref<T>, 
   init: () => R, 
   deps?: DependencyList): void
```

`useImperativeHandle` customizes the instance value that is exposed to parent components when using
`ref`. As always, imperative code using refs should be avoided in most cases.

`useImperativeHandle` should be used with `React.forwardRef`.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |
| `R`            |

## Parameters

| Parameter | Type                       |
| --------- | -------------------------- |
| `ref`     | `undefined` \| `Ref`\<`T`> |
| `init`    | () => `R`                  |
| `deps`?   | `DependencyList`           |

## Returns

`void`

## Version

16.8.0

## See

[https://react.dev/reference/react/useImperativeHandle](https://react.dev/reference/react/useImperativeHandle)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2057



---
url: /api/react/Function.useInitData.md
---



[@lynx-js/react](/api/react/index.md) / useInitData

# Function: useInitData()

```ts
function useInitData(): InitData
```

A React Hooks for you to get `initData`.
If `initData` is changed, a re-render will be triggered automatically.

## Returns

[`InitData`](/api/react/Interface.InitData.md)

## Example

```ts
function App() {
  const initData = useInitData();

  initData.someProperty // use it
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:124



---
url: /api/react/Function.useInitDataChanged.md
---



[@lynx-js/react](/api/react/index.md) / useInitDataChanged

# Function: useInitDataChanged()

```ts
function useInitDataChanged(callback: (data: InitData) => void): void
```

A React Hooks for you to get notified when `initData` changed.

## Parameters

| Parameter  | Type                                                               |
| ---------- | ------------------------------------------------------------------ |
| `callback` | (`data`: [`InitData`](/api/react/Interface.InitData.md)) => `void` |

## Returns

`void`

## Example

```ts
function App() {
  useInitDataChanged((data) => {
    data.someProperty // can use it
  })
}
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:138



---
url: /api/react/Function.useLayoutEffect.md
---



[@lynx-js/react](/api/react/index.md) / useLayoutEffect

# Function: ~~useLayoutEffect()~~

```ts
function useLayoutEffect(effect: EffectCallback, deps?: DependencyList): void
```

`useLayoutEffect` is now an alias of `useEffect`. Use `useEffect` instead.

Accepts a function that contains imperative, possibly effectful code. The effects run after main thread dom update without blocking it.

## Parameters

| Parameter | Type             | Description                                                                         |
| --------- | ---------------- | ----------------------------------------------------------------------------------- |
| `effect`  | `EffectCallback` | Imperative function that can return a cleanup function                              |
| `deps`?   | `DependencyList` | If present, effect will only activate if the values in the list change (using ===). |

## Returns

`void`

## Deprecated

`useLayoutEffect` in the background thread cannot offer the precise timing for reading layout information and synchronously re-render, which is different from React.

## Defined in

@lynx-js/react/runtime/lib/core/hooks/react.d.ts:26



---
url: /api/react/Function.useLynxGlobalEventListener.md
---



[@lynx-js/react](/api/react/index.md) / useLynxGlobalEventListener

# Function: useLynxGlobalEventListener()

```ts
function useLynxGlobalEventListener<T>(eventName: string, listener: T): void
```

`useLynxGlobalEventListener` helps you `addListener` as early as possible.

## Type Parameters

| Type Parameter                                |
| --------------------------------------------- |
| `T` _extends_ (...`args`: `any`\[]) => `void` |

## Parameters

| Parameter   | Type     | Description          |
| ----------- | -------- | -------------------- |
| `eventName` | `string` | Event name to listen |
| `listener`  | `T`      | Event handler        |

## Returns

`void`

## Example

Use this hooks to listen to event 'exposure' and event 'disexposure'

```jsx
function App() {
  useLynxGlobalEventListener('exposure', (e) => {
    console.log("exposure", e)
  })
  useLynxGlobalEventListener('disexposure', (e) => {
    console.log("disexposure", e)
  })
  return (
    <view
      style='width: 100px; height: 100px; background-color: red;'
      exposure-id='a'
    />
  )
}
```

## Defined in

@lynx-js/react/runtime/lib/core/hooks/useLynxGlobalEventListener.d.ts:29



---
url: /api/react/Function.useMainThreadRef.md
---



[@lynx-js/react](/api/react/index.md) / useMainThreadRef

# Function: useMainThreadRef()

## useMainThreadRef(initValue)

```ts
function useMainThreadRef<T>(initValue: T): MainThreadRef<T>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter   | Type | Description                            |
| ----------- | ---- | -------------------------------------- |
| `initValue` | `T`  | The init value of the `MainThreadRef`. |

### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/ref/workletRef.d.ts:55

## useMainThreadRef(initValue)

```ts
function useMainThreadRef<T>(initValue: null | T): RefObject<T>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter   | Type          | Description                            |
| ----------- | ------------- | -------------------------------------- |
| `initValue` | `null` \| `T` | The init value of the `MainThreadRef`. |

### Returns

`RefObject`\<`T`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/ref/workletRef.d.ts:94

## useMainThreadRef()

```ts
function useMainThreadRef<T>(): MainThreadRef<T | undefined>
```

Create A `MainThreadRef`.

A `MainThreadRef` is a ref that can only be accessed on the main thread. It is used to preserve
states between main thread function calls.
The data saved in `current` property of the `MainThreadRef` can be read and written in
multiple main thread functions.

It is a hook and it should only be called at the top level of your component.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | `undefined`  |

### Returns

[`MainThreadRef`](/api/react/Class.MainThreadRef.md)\<`T` | `undefined`>

### Example

```ts
import { useMainThreadRef } from '@lynx-js/react'
import type { MainThread } from '@lynx-js/types'

export function App() {
  const ref = useMainThreadRef<MainThread.Element>(null)

  const handleTap = () => {
    'main thread'
    ref.current?.setStyleProperty('background-color', 'blue')
  }

  return (
    <view
      main-thread:ref={ref}
      main-thread:bindtap={handleTap}
      style={{ width: '300px', height: '300px' }}
    />
  )
}
```

### Defined in

@lynx-js/react/runtime/lib/snapshot/worklet/ref/workletRef.d.ts:131



---
url: /api/react/Function.useMemo.md
---



[@lynx-js/react](/api/react/index.md) / useMemo

# Function: useMemo()

```ts
function useMemo<T>(factory: () => T, deps: DependencyList): T
```

`useMemo` will only recompute the memoized value when one of the `deps` has changed.

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter | Type             |
| --------- | ---------------- |
| `factory` | () => `T`        |
| `deps`    | `DependencyList` |

## Returns

`T`

## Version

16.8.0

## See

[https://react.dev/reference/react/useMemo](https://react.dev/reference/react/useMemo)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2078



---
url: /api/react/Function.useReducer.md
---



[@lynx-js/react](/api/react/index.md) / useReducer

# Function: useReducer()

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I, 
   initializer: (arg: I) => ReducerStateWithoutAction<R>): [ReducerStateWithoutAction<R>, DispatchWithoutAction]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                               |
| -------------------------------------------- |
| `R` _extends_ `ReducerWithoutAction`\<`any`> |
| `I`                                          |

### Parameters

| Parameter        | Type                                              |
| ---------------- | ------------------------------------------------- |
| `reducer`        | `R`                                               |
| `initializerArg` | `I`                                               |
| `initializer`    | (`arg`: `I`) => `ReducerStateWithoutAction`\<`R`> |

### Returns

\[`ReducerStateWithoutAction`\<`R`>, `DispatchWithoutAction`]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1904

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R>(
   reducer: R, 
   initializerArg: ReducerStateWithoutAction<R>, 
   initializer?: undefined): [ReducerStateWithoutAction<R>, DispatchWithoutAction]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                               |
| -------------------------------------------- |
| `R` _extends_ `ReducerWithoutAction`\<`any`> |

### Parameters

| Parameter        | Type                              |
| ---------------- | --------------------------------- |
| `reducer`        | `R`                               |
| `initializerArg` | `ReducerStateWithoutAction`\<`R`> |
| `initializer`?   | `undefined`                       |

### Returns

\[`ReducerStateWithoutAction`\<`R`>, `DispatchWithoutAction`]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1920

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I & ReducerState<R>, 
   initializer: (arg: I & ReducerState<R>) => ReducerState<R>): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |
| `I`                                    |

### Parameters

| Parameter        | Type                                                        |
| ---------------- | ----------------------------------------------------------- |
| `reducer`        | `R`                                                         |
| `initializerArg` | `I` & `ReducerState`\<`R`>                                  |
| `initializer`    | (`arg`: `I` & `ReducerState`\<`R`>) => `ReducerState`\<`R`> |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1938

## useReducer(reducer, initializerArg, initializer)

```ts
function useReducer<R, I>(
   reducer: R, 
   initializerArg: I, 
   initializer: (arg: I) => ReducerState<R>): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |
| `I`                                    |

### Parameters

| Parameter        | Type                                 |
| ---------------- | ------------------------------------ |
| `reducer`        | `R`                                  |
| `initializerArg` | `I`                                  |
| `initializer`    | (`arg`: `I`) => `ReducerState`\<`R`> |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1954

## useReducer(reducer, initialState, initializer)

```ts
function useReducer<R>(
   reducer: R, 
   initialState: ReducerState<R>, 
   initializer?: undefined): [ReducerState<R>, Dispatch<ReducerAction<R>>]
```

An alternative to `useState`.

`useReducer` is usually preferable to `useState` when you have complex state logic that involves
multiple sub-values. It also lets you optimize performance for components that trigger deep
updates because you can pass `dispatch` down instead of callbacks.

### Type Parameters

| Type Parameter                         |
| -------------------------------------- |
| `R` _extends_ `Reducer`\<`any`, `any`> |

### Parameters

| Parameter      | Type                 |
| -------------- | -------------------- |
| `reducer`      | `R`                  |
| `initialState` | `ReducerState`\<`R`> |
| `initializer`? | `undefined`          |

### Returns

\[`ReducerState`\<`R`>, `Dispatch`\<`ReducerAction`\<`R`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useReducer](https://react.dev/reference/react/useReducer)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1979



---
url: /api/react/Function.useRef.md
---



[@lynx-js/react](/api/react/index.md) / useRef

# Function: useRef()

## useRef(initialValue)

```ts
function useRef<T>(initialValue: T): MutableRefObject<T>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter      | Type |
| -------------- | ---- |
| `initialValue` | `T`  |

### Returns

`MutableRefObject`\<`T`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1994

## useRef(initialValue)

```ts
function useRef<T>(initialValue: null | T): RefObject<T>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

Usage note: if you need the result of useRef to be directly mutable, include `| null` in the type
of the generic argument.

### Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

### Parameters

| Parameter      | Type          |
| -------------- | ------------- |
| `initialValue` | `null` \| `T` |

### Returns

`RefObject`\<`T`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2009

## useRef(initialValue)

```ts
function useRef<T>(initialValue?: undefined): MutableRefObject<T | undefined>
```

`useRef` returns a mutable ref object whose `.current` property is initialized to the passed argument
(`initialValue`). The returned object will persist for the full lifetime of the component.

Note that `useRef()` is useful for more than the `ref` attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `T`            | `undefined`  |

### Parameters

| Parameter       | Type        |
| --------------- | ----------- |
| `initialValue`? | `undefined` |

### Returns

`MutableRefObject`\<`T` | `undefined`>

### Version

16.8.0

### See

[https://react.dev/reference/react/useRef](https://react.dev/reference/react/useRef)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2022



---
url: /api/react/Function.useState.md
---



[@lynx-js/react](/api/react/index.md) / useState

# Function: useState()

## useState(initialState)

```ts
function useState<S>(initialState: S | () => S): [S, Dispatch<SetStateAction<S>>]
```

Returns a stateful value, and a function to update it.

### Type Parameters

| Type Parameter |
| -------------- |
| `S`            |

### Parameters

| Parameter      | Type             |
| -------------- | ---------------- |
| `initialState` | `S` \| () => `S` |

### Returns

\[`S`, `Dispatch`\<`SetStateAction`\<`S`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useState](https://react.dev/reference/react/useState)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1884

## useState()

```ts
function useState<S>(): [S | undefined, Dispatch<SetStateAction<S | undefined>>]
```

Returns a stateful value, and a function to update it.

### Type Parameters

| Type Parameter | Default type |
| -------------- | ------------ |
| `S`            | `undefined`  |

### Returns

\[`S` | `undefined`, `Dispatch`\<`SetStateAction`\<`S` | `undefined`>>]

### Version

16.8.0

### See

[https://react.dev/reference/react/useState](https://react.dev/reference/react/useState)

### Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:1892



---
url: /api/react/Function.useSyncExternalStore.md
---



[@lynx-js/react](/api/react/index.md) / useSyncExternalStore

# Function: useSyncExternalStore()

```ts
function useSyncExternalStore<Snapshot>(
   subscribe: (onStoreChange: () => void) => () => void, 
   getSnapshot: () => Snapshot, 
   getServerSnapshot?: () => Snapshot): Snapshot
```

## Type Parameters

| Type Parameter |
| -------------- |
| `Snapshot`     |

## Parameters

| Parameter            | Type                                            | Description |
| -------------------- | ----------------------------------------------- | ----------- |
| `subscribe`          | (`onStoreChange`: () => `void`) => () => `void` |             |
| `getSnapshot`        | () => `Snapshot`                                |             |
| `getServerSnapshot`? | () => `Snapshot`                                | -           |

## Returns

`Snapshot`

## See

[https://github.com/reactwg/react-18/discussions/86](https://github.com/reactwg/react-18/discussions/86)

## Defined in

.pnpm/@types+react\@18.3.28/node\_modules/@types/react/ts5.0/index.d.ts:2176



---
url: /api/react/Function.withInitDataInState.md
---



[@lynx-js/react](/api/react/index.md) / withInitDataInState

# Function: withInitDataInState()

```ts
function withInitDataInState<P, S>(App: ComponentClass<P, S>): ComponentClass<P, S>
```

Higher-Order Component (HOC) that injects `initData` into the state of the given class component.

This HOC checks if the provided component is a class component. If it is, it wraps the component
and injects the `initData` into its state. It also adds a listener
to update the state when data changes, and removes the listener when the component unmounts.

## Type Parameters

| Type Parameter | Description                                     |
| -------------- | ----------------------------------------------- |
| `P`            | The type of the props of the wrapped component. |
| `S`            | The type of the state of the wrapped component. |

## Parameters

| Parameter | Type                        | Description                                   |
| --------- | --------------------------- | --------------------------------------------- |
| `App`     | `ComponentClass`\<`P`, `S`> | The class component to be wrapped by the HOC. |

## Returns

`ComponentClass`\<`P`, `S`>

The original component if it is not a class component, otherwise a new class component
with `initData` injection and state update functionality.

## Example

```typescript
class App extends React.Component<MyProps, MyState> {
  // component implementation
}

export default withInitDataInState(App);
```

## Defined in

@lynx-js/react/runtime/lib/core/initData.d.ts:44



---
url: /api/react/Interface.DataProcessorDefinition.md
---



[@lynx-js/react](/api/react/index.md) / DataProcessorDefinition

# Interface: DataProcessorDefinition

Definition of DataProcessor(s)

## Properties

### dataProcessors?

```ts
optional dataProcessors: DataProcessors;
```

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:324

***

### defaultDataProcessor()?

```ts
optional defaultDataProcessor: (rawInitData: InitDataRaw) => InitData;
```

You can custom input and output type of `defaultDataProcessor` by extends [InitDataRaw](/api/react/Interface.InitDataRaw.md) and [InitData](/api/react/Interface.InitData.md)

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

#### Parameters

| Parameter     | Type                                                 | Description                      |
| ------------- | ---------------------------------------------------- | -------------------------------- |
| `rawInitData` | [`InitDataRaw`](/api/react/Interface.InitDataRaw.md) | initData passed from native code |

#### Returns

[`InitData`](/api/react/Interface.InitData.md)

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:318



---
url: /api/react/Interface.DataProcessors.md
---



[@lynx-js/react](/api/react/index.md) / DataProcessors

# Interface: DataProcessors

The data processors that registered with [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).

## Example

Extending `dataProcessors` interface

```ts
import type { DataProcessors as WellKnownDataProcessors } from '@lynx-js/react';

declare module '@lynx-js/react' {
  interface DataProcessors extends WellKnownDataProcessors {
    foo(bar: string): number;
  }
}
```

Then you can use `lynx.registerDataProcessors` with types.

```js
lynx.registerDataProcessors({
  dataProcessors: {
    foo(bar) {
      return 1;
    }
  }
})
```

## Indexable

\[`processorName`: `string`]: (...`args`: `any`\[]) => `any`

## Methods

### getScreenMetricsOverride()?

```ts
optional getScreenMetricsOverride(metrics: object): object
```

Optional processor to override screen metrics used by the app

#### Parameters

| Parameter        | Type     | Description                              |
| ---------------- | -------- | ---------------------------------------- |
| `metrics`        | `object` | The physical screen dimensions in pixels |
| `metrics.height` | `number` | The physical pixel height of the screen  |
| `metrics.width`  | `number` | The physical pixel width of the screen   |

#### Returns

`object`

New screen dimensions to be used by the app

##### height

```ts
height: number;
```

##### width

```ts
width: number;
```

#### Example

```ts
lynx.registerDataProcessors({
  dataProcessors: {
    getScreenMetricsOverride: (metrics) => {
      // Force a specific aspect ratio
      return {
        width: metrics.width,
        height: metrics.width * (16/9)
      };
    }
  }
});
```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:282



---
url: /api/react/Interface.GlobalProps.md
---



[@lynx-js/react](/api/react/index.md) / GlobalProps

# Interface: GlobalProps

The interface you can extends so that the `useGlobalProps` returning value can be customized



---
url: /api/react/Interface.InitData.md
---



[@lynx-js/react](/api/react/index.md) / InitData

# Interface: InitData

The interface you can extends so that the `defaultDataProcessor` returning value can be customized

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).



---
url: /api/react/Interface.InitDataRaw.md
---



[@lynx-js/react](/api/react/index.md) / InitDataRaw

# Interface: InitDataRaw

The interface you can extends so that the `defaultDataProcessor` parameter can be customized

Should be used with `lynx.registerDataProcessors`. See more examples at [Lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors).



---
url: /api/react/Interface.Lynx.md
---



[@lynx-js/react](/api/react/index.md) / Lynx

# Interface: Lynx

APIs under `lynx` global variable that added by ReactLynx.

## Example

```ts
lynx.registerDataProcessors(...);
lynx.querySelector(...);
lynx.querySelectorAll(...);
```

## Properties

### registerDataProcessors()

```ts
registerDataProcessors: (dataProcessorDefinition?: DataProcessorDefinition) => void;
```

Register DataProcessors. You MUST call this before `root.render()`.

#### Parameters

| Parameter                  | Type                                                                         |
| -------------------------- | ---------------------------------------------------------------------------- |
| `dataProcessorDefinition`? | [`DataProcessorDefinition`](/api/react/Interface.DataProcessorDefinition.md) |

#### Returns

`void`

#### Examples

You MUST call `lynx.registerDataProcessors` before calling `root.render()`.

```ts
import { root } from "@lynx-js/react"

// You MUST call this before `root.render()`
lynx.registerDataProcessors({
  defaultDataProcessor: () => {...} // default DataProcessor
  dataProcessors: {
    getScreenMetricsOverride: () => {...} // named DataProcessor
  }
})

root.render(<App/>);
```

If you have a class component with `static defaultDataProcessor`
or `static dataProcessors`, you can use it to register DataProcessors.

```ts
import { root, Component } from "@lynx-js/react"

class App extends Component {
  static defaultDataProcessor() {
     ...
  }

  static dataProcessors = {
    getScreenMetricsOverride() {
      ...
    }
  }
}

lynx.registerDataProcessors(App); // You can pass `App` because it has the required shape
root.render(<App/>);
```

For developers who want fully typed `defaultDataProcessor`,
they can achieve it by extends interface `InitDataRaw` and `InitData`.

```ts
import { root } from "@lynx-js/react"

interface ExistingInterface {
  somePropertyFromExistingInterface: number
}

declare module '@lynx-js/react' {
  interface InitDataRaw extends ExistingInterface {
    someAnotherCustomProperty: string
  }
}

lynx.registerDataProcessors({
  defaultDataProcessor: (initDataRaw) => {
    initDataRaw.somePropertyFromExistingInterface // will be typed
  }
})

```

For developers who want fully typed `defaultDataProcessor`,
they can achieve it by extends interface `InitDataRaw` and `InitData`.

```ts
import { root, useInitData } from "@lynx-js/react"

interface AnotherExistingInterface {
  someAnotherPropertyFromExistingInterface: number
}

declare module '@lynx-js/react' {
  interface InitData extends AnotherExistingInterface {
    someCustomProperty: string
  }
}

root.registerDataProcessors({
  defaultDataProcessor: () => {
    return {
      someCustomProperty: 'value', // will be typed
      someAnotherPropertyFromExistingInterface: 1, // will be typed
    }
  }
})

function App() {
  const initData = useInitData();

  initData.someCustomProperty // will be typed
  initData.someAnotherPropertyFromExistingInterface // will be typed
}

```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:454

***

### triggerGlobalEventFromLepus()

```ts
triggerGlobalEventFromLepus: (eventName: string, params: any) => void;
```

An alias of `lynx.getJSModule("GlobalEventEmitter").trigger(eventName, params)` only in Lepus

#### Parameters

| Parameter   | Type     |
| ----------- | -------- |
| `eventName` | `string` |
| `params`    | `any`    |

#### Returns

`void`

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:345



---
url: /api/react/Interface.Root.md
---



[@lynx-js/react](/api/react/index.md) / Root

# Interface: Root

The default root exported by `@lynx-js/react` for you to render a JSX

## Properties

### ~~registerDataProcessors()~~

```ts
registerDataProcessors: (dataProcessorDefinition: DataProcessorDefinition) => void;
```

Register DataProcessors. You MUST call this before `root.render()`.

#### Parameters

| Parameter                 | Type                                                                         |
| ------------------------- | ---------------------------------------------------------------------------- |
| `dataProcessorDefinition` | [`DataProcessorDefinition`](/api/react/Interface.DataProcessorDefinition.md) |

#### Returns

`void`

#### Deprecated

use [lynx.registerDataProcessors](/api/react/Interface.Lynx.md#registerdataprocessors) instead

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:60

***

### render()

```ts
render: (jsx: ReactNode) => void;
```

Use this API to pass in your JSX to render

#### Parameters

| Parameter | Type        |
| --------- | ----------- |
| `jsx`     | `ReactNode` |

#### Returns

`void`

#### Examples

```ts
import { root } from "@lynx-js/react"

function App() {
  // Your app
  return <view>...</view>
}

root.render(<App/>);
```

```tsx
import { root } from "@lynx-js/react"

function App() {
  // Your app
  return <view>...</view>
}

if (__MAIN_THREAD__) {
  root.render(
    <DataProvider data={DEFAULT_DATA}>
       <App/>
    </DataProvider>
  );
} else if (__BACKGROUND__) {
  fetchData().then((data) => {
    root.render(
      <DataProvider data={data}>
         <App/>
      </DataProvider>
    ); // You can render later after your data is ready
  })
}
```

#### Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:54



---
url: /api/react/Variable.root.md
---



[@lynx-js/react](/api/react/index.md) / root

# Variable: root

```ts
const root: Root;
```

The default and only root of ReactLynx for you to render JSX

## Example

```ts
import { root } from "@lynx-js/react"
```

## Defined in

@lynx-js/react/runtime/lib/lynx-api.d.ts:71



---
url: /api/react/Variable.useErrorBoundary.md
---



[@lynx-js/react](/api/react/index.md) / useErrorBoundary

# Variable: useErrorBoundary

```ts
useErrorBoundary: any;
```



---
url: /api/rspeedy/index.md
---

# Overview

## environments

### [environments](/api/rspeedy/rspeedy.config.environments.md)

- [Config.environments property](/api/rspeedy/rspeedy.config.environments.md#configenvironments-property)
- [Default Value](/api/rspeedy/rspeedy.config.environments.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.config.environments.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.config.environments.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.config.environments.md#example-2)
## mode

### [mode](/api/rspeedy/rspeedy.config.mode.md)

- [Config.mode property](/api/rspeedy/rspeedy.config.mode.md#configmode-property)
- [Default Value](/api/rspeedy/rspeedy.config.mode.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.config.mode.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.config.mode.md#example-2)
## dev

### [assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md)

- [Dev.assetPrefix property](/api/rspeedy/rspeedy.dev.assetprefix.md#devassetprefix-property)
- [Default Value](/api/rspeedy/rspeedy.dev.assetprefix.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.dev.assetprefix.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.dev.assetprefix.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.dev.assetprefix.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.dev.assetprefix.md#example-3)

### [client](/api/rspeedy/rspeedy.dev.client.md)

- [Dev.client property](/api/rspeedy/rspeedy.dev.client.md#devclient-property)
- [Default Value](/api/rspeedy/rspeedy.dev.client.md#default-value)

### [hmr](/api/rspeedy/rspeedy.dev.hmr.md)

- [Dev.hmr property](/api/rspeedy/rspeedy.dev.hmr.md#devhmr-property)
- [Default Value](/api/rspeedy/rspeedy.dev.hmr.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.dev.hmr.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.dev.hmr.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.dev.hmr.md#example-2)

### [liveReload](/api/rspeedy/rspeedy.dev.livereload.md)

- [Dev.liveReload property](/api/rspeedy/rspeedy.dev.livereload.md#devlivereload-property)
- [Default Value](/api/rspeedy/rspeedy.dev.livereload.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.dev.livereload.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.dev.livereload.md#example-2)

### [progressBar](/api/rspeedy/rspeedy.dev.progressbar.md)

- [Dev.progressBar property](/api/rspeedy/rspeedy.dev.progressbar.md#devprogressbar-property)
- [Default Value](/api/rspeedy/rspeedy.dev.progressbar.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.dev.progressbar.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.dev.progressbar.md#example-2)

### [watchFiles](/api/rspeedy/rspeedy.dev.watchfiles.md)

- [Dev.watchFiles property](/api/rspeedy/rspeedy.dev.watchfiles.md#devwatchfiles-property)
- [Default Value](/api/rspeedy/rspeedy.dev.watchfiles.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.dev.watchfiles.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.dev.watchfiles.md#example-2)

### [writeToDisk](/api/rspeedy/rspeedy.dev.writetodisk.md)

- [Dev.writeToDisk property](/api/rspeedy/rspeedy.dev.writetodisk.md#devwritetodisk-property)
- [Default Value](/api/rspeedy/rspeedy.dev.writetodisk.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.dev.writetodisk.md#remarks)
- [Example](/api/rspeedy/rspeedy.dev.writetodisk.md#example)
## output

### [assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md)

- [Output.assetPrefix property](/api/rspeedy/rspeedy.output.assetprefix.md#outputassetprefix-property)
- [Default Value](/api/rspeedy/rspeedy.output.assetprefix.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.assetprefix.md#remarks)
- [Example](/api/rspeedy/rspeedy.output.assetprefix.md#example)

### [cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md)

- [Output.cleanDistPath property](/api/rspeedy/rspeedy.output.cleandistpath.md#outputcleandistpath-property)
- [Default Value](/api/rspeedy/rspeedy.output.cleandistpath.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.cleandistpath.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.output.cleandistpath.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.output.cleandistpath.md#example-2)

### [copy](/api/rspeedy/rspeedy.output.copy.md)

- [Output.copy property](/api/rspeedy/rspeedy.output.copy.md#outputcopy-property)
- [Default Value](/api/rspeedy/rspeedy.output.copy.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.copy.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.output.copy.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.output.copy.md#example-2)

### [cssModules](/api/rspeedy/rspeedy.output.cssmodules.md)

- [Output.cssModules property](/api/rspeedy/rspeedy.output.cssmodules.md#outputcssmodules-property)
- [Default Value](/api/rspeedy/rspeedy.output.cssmodules.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.cssmodules.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.output.cssmodules.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.output.cssmodules.md#example-2)

### [dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md)

- [Output.dataUriLimit property](/api/rspeedy/rspeedy.output.dataurilimit.md#outputdataurilimit-property)
- [Default Value](/api/rspeedy/rspeedy.output.dataurilimit.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.output.dataurilimit.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.output.dataurilimit.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.output.dataurilimit.md#example-3)
- [Example 4](/api/rspeedy/rspeedy.output.dataurilimit.md#example-4)

### [distPath](/api/rspeedy/rspeedy.output.distpath.md)

- [Output.distPath property](/api/rspeedy/rspeedy.output.distpath.md#outputdistpath-property)
- [Default Value](/api/rspeedy/rspeedy.output.distpath.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.distpath.md#remarks)
- [Example](/api/rspeedy/rspeedy.output.distpath.md#example)

### [filename](/api/rspeedy/rspeedy.output.filename.md)

- [Output.filename property](/api/rspeedy/rspeedy.output.filename.md#outputfilename-property)
- [Default Value](/api/rspeedy/rspeedy.output.filename.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.filename.md#remarks)
- [Example](/api/rspeedy/rspeedy.output.filename.md#example)

### [filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)

- [Output.filenameHash property](/api/rspeedy/rspeedy.output.filenamehash.md#outputfilenamehash-property)
- [Default Value](/api/rspeedy/rspeedy.output.filenamehash.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.filenamehash.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.output.filenamehash.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.output.filenamehash.md#example-2)

### [inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md)

- [Output.inlineScripts property](/api/rspeedy/rspeedy.output.inlinescripts.md#outputinlinescripts-property)
- [Default Value](/api/rspeedy/rspeedy.output.inlinescripts.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.inlinescripts.md#remarks)
- [Example](/api/rspeedy/rspeedy.output.inlinescripts.md#example)

### [legalComments](/api/rspeedy/rspeedy.output.legalcomments.md)

- [Output.legalComments property](/api/rspeedy/rspeedy.output.legalcomments.md#outputlegalcomments-property)
- [Default Value](/api/rspeedy/rspeedy.output.legalcomments.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.output.legalcomments.md#remarks)

### [minify](/api/rspeedy/rspeedy.output.minify.md)

- [Output.minify property](/api/rspeedy/rspeedy.output.minify.md#outputminify-property)
- [Default Value](/api/rspeedy/rspeedy.output.minify.md#default-value)
- [Example](/api/rspeedy/rspeedy.output.minify.md#example)

### [sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md)

- [Output.sourceMap property](/api/rspeedy/rspeedy.output.sourcemap.md#outputsourcemap-property)
- [Default Value](/api/rspeedy/rspeedy.output.sourcemap.md#default-value)
## performance

### [buildCache](/api/rspeedy/rspeedy.performance.buildcache.md)

- [Performance.buildCache property](/api/rspeedy/rspeedy.performance.buildcache.md#performancebuildcache-property)
- [Default Value](/api/rspeedy/rspeedy.performance.buildcache.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.performance.buildcache.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.performance.buildcache.md#example-2)

### [chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md)

- [Performance.chunkSplit property](/api/rspeedy/rspeedy.performance.chunksplit.md#performancechunksplit-property)
- [Default Value](/api/rspeedy/rspeedy.performance.chunksplit.md#default-value)

### [printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)

- [Performance.printFileSize property](/api/rspeedy/rspeedy.performance.printfilesize.md#performanceprintfilesize-property)
- [Default Value](/api/rspeedy/rspeedy.performance.printfilesize.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.performance.printfilesize.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.performance.printfilesize.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.performance.printfilesize.md#example-3)
- [Example 4](/api/rspeedy/rspeedy.performance.printfilesize.md#example-4)
- [Example 5](/api/rspeedy/rspeedy.performance.printfilesize.md#example-5)
- [Example 6](/api/rspeedy/rspeedy.performance.printfilesize.md#example-6)

### [profile](/api/rspeedy/rspeedy.performance.profile.md)

- [Performance.profile property](/api/rspeedy/rspeedy.performance.profile.md#performanceprofile-property)
- [Default Value](/api/rspeedy/rspeedy.performance.profile.md#default-value)
- [Example](/api/rspeedy/rspeedy.performance.profile.md#example)

### [removeConsole](/api/rspeedy/rspeedy.performance.removeconsole.md)

- [Performance.removeConsole property](/api/rspeedy/rspeedy.performance.removeconsole.md#performanceremoveconsole-property)
- [Default Value](/api/rspeedy/rspeedy.performance.removeconsole.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.performance.removeconsole.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.performance.removeconsole.md#example-2)
## resolve

### [alias](/api/rspeedy/rspeedy.resolve.alias.md)

- [Resolve.alias property](/api/rspeedy/rspeedy.resolve.alias.md#resolvealias-property)
- [Default Value](/api/rspeedy/rspeedy.resolve.alias.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.resolve.alias.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.resolve.alias.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.resolve.alias.md#example-3)

### [aliasStrategy](/api/rspeedy/rspeedy.resolve.aliasstrategy.md)

- [Resolve.aliasStrategy property](/api/rspeedy/rspeedy.resolve.aliasstrategy.md#resolvealiasstrategy-property)
- [Default Value](/api/rspeedy/rspeedy.resolve.aliasstrategy.md#default-value)
- [Example](/api/rspeedy/rspeedy.resolve.aliasstrategy.md#example)

### [dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md)

- [Resolve.dedupe property](/api/rspeedy/rspeedy.resolve.dedupe.md#resolvededupe-property)
- [Default Value](/api/rspeedy/rspeedy.resolve.dedupe.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.resolve.dedupe.md#remarks)
- [Example](/api/rspeedy/rspeedy.resolve.dedupe.md#example)

### [extensions](/api/rspeedy/rspeedy.resolve.extensions.md)

- [Resolve.extensions property](/api/rspeedy/rspeedy.resolve.extensions.md#resolveextensions-property)
- [Default Value](/api/rspeedy/rspeedy.resolve.extensions.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.resolve.extensions.md#remarks)
- [Example](/api/rspeedy/rspeedy.resolve.extensions.md#example)
## server

### [base](/api/rspeedy/rspeedy.server.base.md)

- [Server.base property](/api/rspeedy/rspeedy.server.base.md#serverbase-property)
- [Default Value](/api/rspeedy/rspeedy.server.base.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.server.base.md#remarks)
- [Example](/api/rspeedy/rspeedy.server.base.md#example)

### [compress](/api/rspeedy/rspeedy.server.compress.md)

- [Server.compress property](/api/rspeedy/rspeedy.server.compress.md#servercompress-property)
- [Default Value](/api/rspeedy/rspeedy.server.compress.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.server.compress.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.server.compress.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.server.compress.md#example-3)

### [cors](/api/rspeedy/rspeedy.server.cors.md)

- [Server.cors property](/api/rspeedy/rspeedy.server.cors.md#servercors-property)
- [Default Value](/api/rspeedy/rspeedy.server.cors.md#default-value)
- [Example](/api/rspeedy/rspeedy.server.cors.md#example)

### [headers](/api/rspeedy/rspeedy.server.headers.md)

- [Server.headers property](/api/rspeedy/rspeedy.server.headers.md#serverheaders-property)
- [Default Value](/api/rspeedy/rspeedy.server.headers.md#default-value)
- [Example](/api/rspeedy/rspeedy.server.headers.md#example)

### [host](/api/rspeedy/rspeedy.server.host.md)

- [Server.host property](/api/rspeedy/rspeedy.server.host.md#serverhost-property)
- [Default Value](/api/rspeedy/rspeedy.server.host.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.server.host.md#remarks)
- [Example](/api/rspeedy/rspeedy.server.host.md#example)

### [port](/api/rspeedy/rspeedy.server.port.md)

- [Server.port property](/api/rspeedy/rspeedy.server.port.md#serverport-property)
- [Default Value](/api/rspeedy/rspeedy.server.port.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.server.port.md#remarks)
- [Example](/api/rspeedy/rspeedy.server.port.md#example)

### [proxy](/api/rspeedy/rspeedy.server.proxy.md)

- [Server.proxy property](/api/rspeedy/rspeedy.server.proxy.md#serverproxy-property)
- [Default Value](/api/rspeedy/rspeedy.server.proxy.md#default-value)
- [Example](/api/rspeedy/rspeedy.server.proxy.md#example)

### [strictPort](/api/rspeedy/rspeedy.server.strictport.md)

- [Server.strictPort property](/api/rspeedy/rspeedy.server.strictport.md#serverstrictport-property)
- [Default Value](/api/rspeedy/rspeedy.server.strictport.md#default-value)
## source

### [~~alias~~](/api/rspeedy/rspeedy.source.alias.md)

- [Source.alias property](/api/rspeedy/rspeedy.source.alias.md#sourcealias-property)
- [Default Value](/api/rspeedy/rspeedy.source.alias.md#default-value)

### [assetsInclude](/api/rspeedy/rspeedy.source.assetsinclude.md)

- [Source.assetsInclude property](/api/rspeedy/rspeedy.source.assetsinclude.md#sourceassetsinclude-property)
- [Default Value](/api/rspeedy/rspeedy.source.assetsinclude.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.assetsinclude.md#remarks)
- [Example](/api/rspeedy/rspeedy.source.assetsinclude.md#example)

### [decorators](/api/rspeedy/rspeedy.source.decorators.md)

- [Source.decorators property](/api/rspeedy/rspeedy.source.decorators.md#sourcedecorators-property)
- [Default Value](/api/rspeedy/rspeedy.source.decorators.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.decorators.md#remarks)

### [define](/api/rspeedy/rspeedy.source.define.md)

- [Source.define property](/api/rspeedy/rspeedy.source.define.md#sourcedefine-property)
- [Default Value](/api/rspeedy/rspeedy.source.define.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.define.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.source.define.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.source.define.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.source.define.md#example-3)

### [entry](/api/rspeedy/rspeedy.source.entry.md)

- [Source.entry property](/api/rspeedy/rspeedy.source.entry.md#sourceentry-property)
- [Default Value](/api/rspeedy/rspeedy.source.entry.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.source.entry.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.source.entry.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.source.entry.md#example-3)
- [Example 4](/api/rspeedy/rspeedy.source.entry.md#example-4)

### [exclude](/api/rspeedy/rspeedy.source.exclude.md)

- [Source.exclude property](/api/rspeedy/rspeedy.source.exclude.md#sourceexclude-property)
- [Default Value](/api/rspeedy/rspeedy.source.exclude.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.exclude.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.source.exclude.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.source.exclude.md#example-2)

### [include](/api/rspeedy/rspeedy.source.include.md)

- [Source.include property](/api/rspeedy/rspeedy.source.include.md#sourceinclude-property)
- [Default Value](/api/rspeedy/rspeedy.source.include.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.include.md#remarks)
- [Example 1](/api/rspeedy/rspeedy.source.include.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.source.include.md#example-2)

### [preEntry](/api/rspeedy/rspeedy.source.preentry.md)

- [Source.preEntry property](/api/rspeedy/rspeedy.source.preentry.md#sourcepreentry-property)
- [Default Value](/api/rspeedy/rspeedy.source.preentry.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.preentry.md#remarks)
- [Example](/api/rspeedy/rspeedy.source.preentry.md#example)

### [transformImport](/api/rspeedy/rspeedy.source.transformimport.md)

- [Source.transformImport property](/api/rspeedy/rspeedy.source.transformimport.md#sourcetransformimport-property)
- [Default Value](/api/rspeedy/rspeedy.source.transformimport.md#default-value)
- [Example](/api/rspeedy/rspeedy.source.transformimport.md#example)

### [tsconfigPath](/api/rspeedy/rspeedy.source.tsconfigpath.md)

- [Source.tsconfigPath property](/api/rspeedy/rspeedy.source.tsconfigpath.md#sourcetsconfigpath-property)
- [Default Value](/api/rspeedy/rspeedy.source.tsconfigpath.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.source.tsconfigpath.md#remarks)
- [Example](/api/rspeedy/rspeedy.source.tsconfigpath.md#example)
## splitChunks

### [splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md)

- [Config.splitChunks property](/api/rspeedy/rspeedy.config.splitchunks.md#configsplitchunks-property)
- [Default Value](/api/rspeedy/rspeedy.config.splitchunks.md#default-value)
## tools

### [bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md)

- [Tools.bundlerChain property](/api/rspeedy/rspeedy.tools.bundlerchain.md#toolsbundlerchain-property)
- [Default Value](/api/rspeedy/rspeedy.tools.bundlerchain.md#default-value)
- [Example](/api/rspeedy/rspeedy.tools.bundlerchain.md#example)

### [cssExtract](/api/rspeedy/rspeedy.tools.cssextract.md)

- [Tools.cssExtract property](/api/rspeedy/rspeedy.tools.cssextract.md#toolscssextract-property)
- [Default Value](/api/rspeedy/rspeedy.tools.cssextract.md#default-value)

### [cssLoader](/api/rspeedy/rspeedy.tools.cssloader.md)

- [Tools.cssLoader property](/api/rspeedy/rspeedy.tools.cssloader.md#toolscssloader-property)
- [Default Value](/api/rspeedy/rspeedy.tools.cssloader.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.tools.cssloader.md#remarks)

### [rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md)

- [Tools.rsdoctor property](/api/rspeedy/rspeedy.tools.rsdoctor.md#toolsrsdoctor-property)
- [Default Value](/api/rspeedy/rspeedy.tools.rsdoctor.md#default-value)
- [Remarks](/api/rspeedy/rspeedy.tools.rsdoctor.md#remarks)
- [Example](/api/rspeedy/rspeedy.tools.rsdoctor.md#example)

### [rspack](/api/rspeedy/rspeedy.tools.rspack.md)

- [Tools.rspack property](/api/rspeedy/rspeedy.tools.rspack.md#toolsrspack-property)
- [Default Value](/api/rspeedy/rspeedy.tools.rspack.md#default-value)
- [Example 1](/api/rspeedy/rspeedy.tools.rspack.md#example-1)
- [Example 2](/api/rspeedy/rspeedy.tools.rspack.md#example-2)
- [Example 3](/api/rspeedy/rspeedy.tools.rspack.md#example-3)
- [Example 4](/api/rspeedy/rspeedy.tools.rspack.md#example-4)

### [swc](/api/rspeedy/rspeedy.tools.swc.md)

- [Tools.swc property](/api/rspeedy/rspeedy.tools.swc.md#toolsswc-property)
- [Default Value](/api/rspeedy/rspeedy.tools.swc.md#default-value)



---
url: /api/rspeedy/rspeedy.config.environments.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [environments](/api/rspeedy/rspeedy.config.environments.md)

## Config.environments property

The [Config.environments](/api/rspeedy/rspeedy.config.environments.md) option is used to set the output environment.

**Signature:**

```typescript
environments?: RsbuildConfig['environments'] | undefined;
```

## Default Value

When this option is unset, Rspeedy passes `{ lynx: {} }` to Rsbuild.

## Remarks

Normally you don't need this if you are not using Lynx for Web.

## Example 1

- Using different entries for Lynx and Web.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  environments: {
    lynx: {},
    web: {
      source: { entry: { web: './src/index.web.jsx' } },
    },
  },
  source: {
    entry: './src/index.jsx',
  },
})
```

## Example 2

- Building Web-only outputs.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  environments: {
    web: {
      source: { entry: { web: './src/index.web.jsx' } },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.config.mode.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [mode](/api/rspeedy/rspeedy.config.mode.md)

## Config.mode property

Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.

**Signature:**

```typescript
mode?: 'development' | 'production' | 'none' | undefined;
```

## Default Value

Depends on `process.env.NODE_ENV`<!-- -->: `'production'` when `NODE_ENV` is `'production'`<!-- -->, `'development'` when `NODE_ENV` is `'development'`<!-- -->, and `'none'` otherwise. When using Rspeedy's CLI, `rspeedy dev` and `rspeedy preview` default to `'development'`<!-- -->, while `rspeedy build` defaults to `'production'`<!-- -->.

## Example 1

If the value of `mode` is `'development'`<!-- -->:

- Enable HMR and register the [HotModuleReplacementPlugin](https://rspack.rs/plugins/webpack/hot-module-replacement-plugin)<!-- -->.

- Generate JavaScript source maps, but do not generate CSS source maps. See [Output.sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md) for details.

- The `process.env.NODE_ENV` in the source code will be replaced with `'development'`<!-- -->.

- The `import.meta.env.MODE` in the source code will be replaced with `'development'`<!-- -->.

- The `import.meta.env.DEV` in the source code will be replaced with `true`<!-- -->.

- The `import.meta.env.PROD` in the source code will be replaced with `false`<!-- -->.

## Example 2

If the value of `mode` is `'production'`<!-- -->:

- Enable JavaScript code minification and register the [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin)<!-- -->.

- Generated JavaScript and CSS filenames will have hash suffixes, see [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)<!-- -->.

- Generated CSS Modules classnames will be shorter, see [CssModules.localIdentName](/api/rspeedy/rspeedy.cssmodules.localidentname.md)<!-- -->.

- Do not generate JavaScript and CSS source maps, see [Output.sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md)<!-- -->.

- The `process.env.NODE_ENV` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.MODE` in the source code will be replaced with `'production'`<!-- -->.

- The `import.meta.env.DEV` in the source code will be replaced with `false`<!-- -->.

- The `import.meta.env.PROD` in the source code will be replaced with `true`<!-- -->.



---
url: /api/rspeedy/rspeedy.dev.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md)

## Dev interface

The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

**Signature:**

```typescript
export interface Dev 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[assetPrefix?](/api/rspeedy/rspeedy.dev.assetprefix.md)

</td><td>

</td><td>

string | boolean | undefined

</td><td>

_(Optional)_ The [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is used to set the URL prefix for static assets during development.

</td></tr>
<tr><td>

[client?](/api/rspeedy/rspeedy.dev.client.md)

</td><td>

</td><td>

[Client](/api/rspeedy/rspeedy.devclient.md) | undefined

</td><td>

_(Optional)_ Configuration of the development client.

</td></tr>
<tr><td>

[hmr?](/api/rspeedy/rspeedy.dev.hmr.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether to enable Hot Module Replacement (HMR).

</td></tr>
<tr><td>

[liveReload?](/api/rspeedy/rspeedy.dev.livereload.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether to enable live reload functionality.

</td></tr>
<tr><td>

[progressBar?](/api/rspeedy/rspeedy.dev.progressbar.md)

</td><td>

</td><td>

boolean | \{ id?: string; } | undefined

</td><td>

_(Optional)_ Whether to display progress bar during compilation.

</td></tr>
<tr><td>

[watchFiles?](/api/rspeedy/rspeedy.dev.watchfiles.md)

</td><td>

</td><td>

WatchFiles | WatchFiles\[] | undefined

</td><td>

_(Optional)_ Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.

</td></tr>
<tr><td>

[writeToDisk?](/api/rspeedy/rspeedy.dev.writetodisk.md)

</td><td>

</td><td>

boolean | ((filename: string) => boolean) | undefined

</td><td>

_(Optional)_ Used to control whether the build artifacts of the development environment are written to the disk.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.dev.assetprefix.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md)

## Dev.assetPrefix property

The [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is used to set the URL prefix for static assets during development.

**Signature:**

```typescript
assetPrefix?: string | boolean | undefined;
```

## Default Value

undefined

## Remarks

During `rspeedy dev`<!-- -->, if this option is not set to `false`<!-- -->, the dev plugin normalizes it to `http://<detected-host>:<port>/` and appends `server.base` when configured.

The functionality of [Dev.assetPrefix](/api/rspeedy/rspeedy.dev.assetprefix.md) is basically the same as the [output.publicPath](https://rspack.rs/config/output#outputpublicpath) config in Rspack. With the following differences:

- `dev.assetPrefix` only takes effect during development.

- `dev.assetPrefix` automatically appends a trailing `/` by default.

- The value of `dev.assetPrefix` is written to the `process.env.ASSET_PREFIX` environment variable.

## Example 1

If `dev.assetPrefix` is set to true, the URL prefix will be `http://<host>:<port>/`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: true,
  },
})
```

## Example 2

If `dev.assetPrefix` is set to a string, the value will be used as a prefix and automatically appended to the static resource URL.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: 'https://example.com/assets/',
  },
})
```

## Example 3

The port number that Rspeedy server listens on may change. For example, if the port is in use, Rspeedy will automatically increment the port number until it finds an available port.

To avoid `dev.assetPrefix` becoming invalid due to port changes, you can use one of the following methods:

- Enable `server.strictPort`<!-- -->.

- Use the `<port>` placeholder to refer to the current port number. Rspeedy will replace the placeholder with the actual port number it is listening on.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    assetPrefix: 'https://example.com:<port>/assets/',
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.client.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [client](/api/rspeedy/rspeedy.dev.client.md)

## Dev.client property

Configuration of the development client.

**Signature:**

```typescript
client?: Client | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.devclient.websockettransport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DevClient](/api/rspeedy/rspeedy.devclient.md) > [websocketTransport](/api/rspeedy/rspeedy.devclient.websockettransport.md)

## DevClient.websocketTransport property

The path to websocket.

**Signature:**

```typescript
websocketTransport?: string | undefined;
```

## Default Value

`require.resolve('@lynx-js/websocket')`



---
url: /api/rspeedy/rspeedy.dev.hmr.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [hmr](/api/rspeedy/rspeedy.dev.hmr.md)

## Dev.hmr property

Whether to enable Hot Module Replacement (HMR).

**Signature:**

```typescript
hmr?: boolean | undefined;
```

## Default Value

true

## Remarks

By default, Rspeedy uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to [Dev.liveReload](/api/rspeedy/rspeedy.dev.livereload.md)<!-- -->.

To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`<!-- -->. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.

## Example 1

Disable HMR:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
  },
})
```

## Example 2

Disable both HMR and live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
    liveReload: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.livereload.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [liveReload](/api/rspeedy/rspeedy.dev.livereload.md)

## Dev.liveReload property

Whether to enable live reload functionality.

**Signature:**

```typescript
liveReload?: boolean | undefined;
```

## Default Value

true

Live reload is used as a fallback when [Dev.hmr](/api/rspeedy/rspeedy.dev.hmr.md) is disabled or cannot be used in certain scenarios. When enabled, the page will automatically refresh when source files are changed.

To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`<!-- -->. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.

## Example 1

Disable live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    liveReload: false,
  },
})
```

## Example 2

Disable both HMR and live reload:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    hmr: false,
    liveReload: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.progressbar.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [progressBar](/api/rspeedy/rspeedy.dev.progressbar.md)

## Dev.progressBar property

Whether to display progress bar during compilation.

**Signature:**

```typescript
progressBar?: boolean | {
        id?: string;
    } | undefined;
```

## Default Value

true

## Example 1

Disable the progress bar.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    progressBar: false,
  },
})
```

## Example 2

Modify the progress bar `id`

To modify the text displayed on the left side of the progress bar, set the `id` option:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    progressBar: {
      id: 'Some Text'
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.watchfiles.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [watchFiles](/api/rspeedy/rspeedy.dev.watchfiles.md)

## Dev.watchFiles property

Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.

**Signature:**

```typescript
watchFiles?: WatchFiles | WatchFiles[] | undefined;
```

## Default Value

undefined

## Example 1

- Specify the files and directories watched for changes.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    watchFiles: {
      paths: ['src/**', 'public/**'],
    },
  },
})
```

## Example 2

- Use [chokidar](https://github.com/paulmillr/chokidar#api) options for watching.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  dev: {
    watchFiles: {
      paths: ['src/**', 'public/**'],
      options: { usePolling: false },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.dev.writetodisk.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Dev](/api/rspeedy/rspeedy.dev.md) > [writeToDisk](/api/rspeedy/rspeedy.dev.writetodisk.md)

## Dev.writeToDisk property

Used to control whether the build artifacts of the development environment are written to the disk.

**Signature:**

```typescript
writeToDisk?: boolean | ((filename: string) => boolean) | undefined;
```

## Default Value

true

## Remarks

This is bypassed to [\`webpack-dev-middleware\`](https://github.com/webpack/webpack-dev-middleware?tab=readme-ov-file#writetodisk)<!-- -->.

Setting `writeToDisk: true` won't change the behavior of the `webpack-dev-middleware`<!-- -->, and bundle files accessed through the browser will still be served from memory.

This option also accepts a `Function` value, which can be used to filter which files are written to disk.

The function follows the same premise as `Array#filter` in which a return value of `false` will not write the file, and a return value of `true` will write the file to disk.

## Example

```js
// lynx.config.ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  dev: {
    writeToDisk: (filePath) => /superman\.css$/.test(filePath),
  },
})
```



---
url: /api/rspeedy/rspeedy.output.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md)

## Output interface

The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

**Signature:**

```typescript
export interface Output 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[assetPrefix?](/api/rspeedy/rspeedy.output.assetprefix.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is used to set the URL prefix for static assets.

</td></tr>
<tr><td>

[cleanDistPath?](/api/rspeedy/rspeedy.output.cleandistpath.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ The [Output.cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md) option determines whether all files in the output directory (default: `dist`<!-- -->) are removed before the build starts.

</td></tr>
<tr><td>

[copy?](/api/rspeedy/rspeedy.output.copy.md)

</td><td>

</td><td>

Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions\['patterns'] | undefined

</td><td>

_(Optional)_ The [Output.copy](/api/rspeedy/rspeedy.output.copy.md) option is used for copying files to the dist directory.

</td></tr>
<tr><td>

[cssModules?](/api/rspeedy/rspeedy.output.cssmodules.md)

</td><td>

</td><td>

[CssModules](/api/rspeedy/rspeedy.cssmodules.md) | undefined

</td><td>

_(Optional)_ The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

</td></tr>
<tr><td>

[dataUriLimit?](/api/rspeedy/rspeedy.output.dataurilimit.md)

</td><td>

</td><td>

number | DataUriLimit | undefined

</td><td>

_(Optional)_ The [Output.dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md) option is used to set the size threshold to inline static assets such as images and fonts.

</td></tr>
<tr><td>

[distPath?](/api/rspeedy/rspeedy.output.distpath.md)

</td><td>

</td><td>

[DistPath](/api/rspeedy/rspeedy.distpath.md) | undefined

</td><td>

_(Optional)_ Set the directory of the dist files.

</td></tr>
<tr><td>

[filename?](/api/rspeedy/rspeedy.output.filename.md)

</td><td>

</td><td>

string | [Filename](/api/rspeedy/rspeedy.filename.md) | undefined

</td><td>

_(Optional)_ The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

</td></tr>
<tr><td>

[filenameHash?](/api/rspeedy/rspeedy.output.filenamehash.md)

</td><td>

</td><td>

boolean | string | undefined

</td><td>

_(Optional)_ The [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md) option controls whether to add a hash value to the filename after the production build.

</td></tr>
<tr><td>

[inlineScripts?](/api/rspeedy/rspeedy.output.inlinescripts.md)

</td><td>

</td><td>

InlineChunkConfig | undefined

</td><td>

_(Optional)_ The [Output.inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md) option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`<!-- -->).

</td></tr>
<tr><td>

[legalComments?](/api/rspeedy/rspeedy.output.legalcomments.md)

</td><td>

</td><td>

'none' | 'inline' | 'linked' | undefined

</td><td>

_(Optional)_ The [Output.legalComments](/api/rspeedy/rspeedy.output.legalcomments.md) controls how to handle the legal comment.

</td></tr>
<tr><td>

[minify?](/api/rspeedy/rspeedy.output.minify.md)

</td><td>

</td><td>

[Minify](/api/rspeedy/rspeedy.minify.md) | boolean | undefined

</td><td>

_(Optional)_ The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

</td></tr>
<tr><td>

[sourceMap?](/api/rspeedy/rspeedy.output.sourcemap.md)

</td><td>

</td><td>

boolean | [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) | undefined

</td><td>

_(Optional)_ The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.output.assetprefix.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md)

## Output.assetPrefix property

The [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is used to set the URL prefix for static assets.

**Signature:**

```typescript
assetPrefix?: string | undefined;
```

## Default Value

undefined

## Remarks

The functionality of [Output.assetPrefix](/api/rspeedy/rspeedy.output.assetprefix.md) is basically the same as the [output.publicPath](https://rspack.rs/config/output#outputpublicpath) config in Rspack. With the following differences:

- `output.assetPrefix` only takes effect in the production build.

- `output.assetPrefix` automatically appends a trailing `/` by default.

- The value of `output.assetPrefix` is written to the `process.env.ASSET_PREFIX` environment variable.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    assetPrefix: 'https://cdn.example.com/assets/',
  },
})
```



---
url: /api/rspeedy/rspeedy.output.cleandistpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md)

## Output.cleanDistPath property

The [Output.cleanDistPath](/api/rspeedy/rspeedy.output.cleandistpath.md) option determines whether all files in the output directory (default: `dist`<!-- -->) are removed before the build starts.

**Signature:**

```typescript
cleanDistPath?: boolean | undefined;
```

## Default Value

Automatically enabled when `output.distPath.root` is a subdirectory of the project root; otherwise disabled.

## Remarks

By default, if the output directory is a subdirectory of the project root path, Rspeedy will automatically clean all files in the build directory.

When [output.distPath.root](https://rsbuild.rs/config/output/dist-path#root-directory) is an external directory or the same as the project root directory, `cleanDistPath` is not enabled by default to prevent accidental deletion of files from other directories.

## Example 1

- Disable cleaning files:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cleanDistPath: false,
  },
})
```

## Example 2

- Only clean files before the production build:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cleanDistPath: process.env.NODE_ENV === 'production',
  },
})
```



---
url: /api/rspeedy/rspeedy.output.copy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [copy](/api/rspeedy/rspeedy.output.copy.md)

## Output.copy property

The [Output.copy](/api/rspeedy/rspeedy.output.copy.md) option is used for copying files to the dist directory.

**Signature:**

```typescript
copy?: Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns'] | undefined;
```

## Default Value

undefined

## Remarks

For more options, see [Rspack.CopyRspackPlugin](https://rspack.rs/plugins/rspack/copy-rspack-plugin)<!-- -->.

## Example 1

- Copy files from `./src/assets` to the `./dist` directory:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/image.png`
      { from: './src/assets' },
    ],
  },
})
```

## Example 2

- Copy files from ./src/assets to the ./dist/assets directory:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/assets/image.png`
      { from: './src/assets', to: 'assets' },
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.output.cssmodules.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [cssModules](/api/rspeedy/rspeedy.output.cssmodules.md)

## Output.cssModules property

The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

**Signature:**

```typescript
cssModules?: CssModules | undefined;
```

## Default Value

undefined

## Remarks

The CSS module is enabled for `*.module.css`<!-- -->, `*.module.scss` and `*.module.less`<!-- -->. Use [CssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Example 1

Disable CSS modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: false,
    },
  },
})
```

## Example 2

Enable CSS modules for all CSS files:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: () => true,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssmodules.auto.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [auto](/api/rspeedy/rspeedy.cssmodules.auto.md)

## CssModules.auto property

The `auto` option allows CSS modules to be automatically enabled based on their filenames.

**Signature:**

```typescript
auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
```

## Default Value

true

## Remarks

Given the various `auto` values, the behavior is described as follows:

- `true`<!-- -->: enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` RegExp.

- `false`<!-- -->: disable CSS modules.

- `RegExp`<!-- -->: enable CSS modules for all files matching the `auto.test(filename)` RegExp.

- `function`<!-- -->: enable CSS modules based on the filter function.

See [css-loader#auto](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#auto) for details.

## Example

Enable CSS module for `*.module.css` and `shared/*.css`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      auto: (filename) => {
        return filename.includes('.module.') || filename.includes('shared/')
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssmodules.exportglobals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [exportGlobals](/api/rspeedy/rspeedy.cssmodules.exportglobals.md)

## CssModules.exportGlobals property

Allows exporting names from global class names, so you can use them via import.

**Signature:**

```typescript
exportGlobals?: boolean | undefined;
```

## Default Value

false

## Remarks

See [css-loader#exportGlobals](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportglobals) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [exportLocalsConvention](/api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md)

## CssModules.exportLocalsConvention property

The style of exported class names.

**Signature:**

```typescript
exportLocalsConvention?: CssModuleLocalsConvention | undefined;
```

## Default Value

`'camelCase'`

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.localidentname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md) > [localIdentName](/api/rspeedy/rspeedy.cssmodules.localidentname.md)

## CssModules.localIdentName property

Sets the format of the className generated by CSS Modules after compilation.

**Signature:**

```typescript
localIdentName?: string | undefined;
```

## Default Value

`'[local]-[hash:base64:6]'`

## Remarks

Available placeholders:

- `[local]`<!-- -->: Original class name

- `[hash]`<!-- -->: Hash of the class name

- `[path]`<!-- -->: File path

- `[name]`<!-- -->: File name

- `[ext]`<!-- -->: File extension

See [css-loader#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.

## Example 1

Use only hash for shorter class names:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      localIdentName: '[hash:base64:8]',
    },
  },
})
```

## Example 2

Include file name for debugging:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    cssModules: {
      localIdentName: '[name]__[local]--[hash:base64:5]',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.dataurilimit.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md)

## Output.dataUriLimit property

The [Output.dataUriLimit](/api/rspeedy/rspeedy.output.dataurilimit.md) option is used to set the size threshold to inline static assets such as images and fonts.

**Signature:**

```typescript
dataUriLimit?: number | DataUriLimit | undefined;
```

## Default Value

2048

## Example 1

Inline all static assets less than 4kB:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: 4 * 1024,
  },
})
```

## Example 2

Disable inlining of static assets:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: 0,
  },
})
```

## Example 3

Inline all static assets:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    dataUriLimit: Number.MAX_SAFE_INTEGER,
  },
})
```

## Example 4

Disable inlining of all media but not images.

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.distpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [distPath](/api/rspeedy/rspeedy.output.distpath.md)

## Output.distPath property

Set the directory of the dist files.

**Signature:**

```typescript
distPath?: DistPath | undefined;
```

## Default Value

Uses Rsbuild's default distPath configuration with `root: 'dist'`<!-- -->.

## Remarks

More options can be found at [Rsbuild - distPath](https://rsbuild.rs/config/output/dist-path)<!-- -->.

## Example

Use `output` instead of `dist`<!-- -->(the default value):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    distPath: {
      root: './output',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.distpath.intermediate.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md) > [intermediate](/api/rspeedy/rspeedy.distpath.intermediate.md)

## DistPath.intermediate property

> Warning: This API is now obsolete.
>
> This option is never read and will be removed in the future version.

The output directory of the intermediate files.

**Signature:**

```typescript
intermediate?: string | undefined;
```

## Default Value

`'.rspeedy'`



---
url: /api/rspeedy/rspeedy.output.filename.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [filename](/api/rspeedy/rspeedy.output.filename.md)

## Output.filename property

The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

**Signature:**

```typescript
filename?: string | Filename | undefined;
```

## Default Value

`{ bundle: '[name].[platform].bundle', template: '[name].[platform].bundle' }`

## Remarks

If a string is provided, it will be used as [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md)<!-- -->.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    filename: '[name]/[name].lynx.bundle',
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.assets.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [assets](/api/rspeedy/rspeedy.filename.assets.md)

## Filename.assets property

The name of other assets, except for above (image, svg, font, html, wasm...)

**Signature:**

```typescript
assets?: Rspack.AssetModuleFilename;
```

## Default Value

`'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.bundle.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [bundle](/api/rspeedy/rspeedy.filename.bundle.md)

## Filename.bundle property

The name of the bundle files.

**Signature:**

```typescript
bundle?: BundleFilename | undefined;
```

## Default Value

`'[name].[platform].bundle'`

## Remarks

The following placeholder is supported:

- `[name]`<!-- -->: the name of the entry. - `[contenthash]`<!-- -->: the contenthash of the bundle. - `[platform]`<!-- -->: the environment name of the bundle.

## Example 1

- Using content hash in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      bundle: '[name].[contenthash].bundle',
    },
  },
})
```

## Example 2

- Using content hash with length in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      bundle: '[name].[contenthash:8].bundle',
    },
  },
})
```

## Example 3

- Using a function to control the main bundle and the lazy bundles separately (e.g. emit lazy bundles into another directory with a git commit hash appended):

```js
import { execSync } from 'node:child_process'

import { defineConfig } from '@lynx-js/rspeedy'

const gitHash = execSync('git rev-parse --short HEAD').toString().trim()

export default defineConfig({
  output: {
    filename: {
      bundle: ({ lazyBundle, platform }) =>
        lazyBundle
          ? `my-lazy-bundles/[name].[fullhash]-${gitHash}.bundle`
          : `[name].${platform}.bundle`,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.css.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [css](/api/rspeedy/rspeedy.filename.css.md)

## Filename.css property

The name of the CSS files.

**Signature:**

```typescript
css?: Rspack.CssFilename | undefined;
```

## Default Value

`'[name]/[name].css'`

## Example

- Using a function to dynamically set the filename based on the file information:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      css: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].css' : '[name].css';
        }
        return '/some-path/[name].css';
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.font.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [font](/api/rspeedy/rspeedy.filename.font.md)

## Filename.font property

The name of the font files.

**Signature:**

```typescript
font?: Rspack.AssetModuleFilename | undefined;
```

## Default Value

`'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.image.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [image](/api/rspeedy/rspeedy.filename.image.md)

## Filename.image property

The name of non-SVG images.

**Signature:**

```typescript
image?: Rspack.AssetModuleFilename | undefined;
```

## Default Value

`'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.js.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [js](/api/rspeedy/rspeedy.filename.js.md)

## Filename.js property

The name of the JavaScript files.

**Signature:**

```typescript
js?: Rspack.Filename | undefined;
```

## Default Value

`'[name].js'` in development, `'[name].[contenthash:8].js'` in production web builds, and `'[name].js'` in production node builds

## Example

- Using a function to dynamically set the filename based on the file information:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      js: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].js' : '[name].js';
        }
        return '/some-path/[name].js';
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.media.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [media](/api/rspeedy/rspeedy.filename.media.md)

## Filename.media property

The name of media assets, such as video.

**Signature:**

```typescript
media?: Rspack.AssetModuleFilename | undefined;
```

## Default Value

`'[name].[contenthash:8][ext]'`



---
url: /api/rspeedy/rspeedy.filename.svg.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [svg](/api/rspeedy/rspeedy.filename.svg.md)

## Filename.svg property

The name of the SVG images.

**Signature:**

```typescript
svg?: Rspack.AssetModuleFilename | undefined;
```

## Default Value

`'[name].[contenthash:8].svg'`



---
url: /api/rspeedy/rspeedy.filename.template.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [template](/api/rspeedy/rspeedy.filename.template.md)

## Filename.template property

> Warning: This API is now obsolete.
>
> Use [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md) instead.

The name of the template files.

**Signature:**

```typescript
template?: string | undefined;
```

## Default Value

`'[name].[platform].bundle'`

## Remarks

The following placeholder is supported:

- `[name]`<!-- -->: the name of the entry. - `[contenthash]`<!-- -->: the contenthash of the template.

## Example 1

- Using content hash in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      template: '[name].[contenthash].bundle',
    },
  },
})
```

## Example 2

- Using content hash with length in bundle filename:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filename: {
      template: '[name].[contenthash:8].bundle',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.filename.wasm.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md) > [wasm](/api/rspeedy/rspeedy.filename.wasm.md)

## Filename.wasm property

The name of WebAssembly files.

**Signature:**

```typescript
wasm?: Rspack.WebassemblyModuleFilename;
```

## Default Value

`'[contenthash:8].module.wasm'`



---
url: /api/rspeedy/rspeedy.output.filenamehash.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)

## Output.filenameHash property

The [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md) option controls whether to add a hash value to the filename after the production build.

**Signature:**

```typescript
filenameHash?: boolean | string | undefined;
```

## Default Value

In production web builds, Rsbuild defaults this option to `true`<!-- -->; development builds and non-web outputs omit hashes by default.

## Remarks

[Output.filename](/api/rspeedy/rspeedy.output.filename.md) has a higher priority than [Output.filenameHash](/api/rspeedy/rspeedy.output.filenamehash.md)<!-- -->.

## Example 1

- Disable hash

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filenameHash: false,
  },
})
```

## Example 2

- Change hash format

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    filenameHash: 'fullhash:16',
  },
})
```

The available hash formats are:

- `fullhash`<!-- -->: The hash value of the entire compilation. If any file changes, the hash values of all output files in the entire project will change.

- `chunkhash`<!-- -->: The hash value of the chunk. The hash value will only change when the content of the chunk (and its included modules) changes.

- `contenthash`<!-- -->: The hash value of the file content. The hash value will only change when the content of the file itself changes.



---
url: /api/rspeedy/rspeedy.output.inlinescripts.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md)

## Output.inlineScripts property

The [Output.inlineScripts](/api/rspeedy/rspeedy.output.inlinescripts.md) option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`<!-- -->).

**Signature:**

```typescript
inlineScripts?: InlineChunkConfig | undefined;
```

## Default Value

Rspeedy defaults this to `true` and only switches it to `false` when the user explicitly enables the top-level `splitChunks` option.

## Remarks

This is different with [output.inlineScripts](https://rsbuild.rs/config/output/inline-scripts) since we normally want to inline scripts in Lynx bundle (`.lynx.bundle`<!-- -->).

There are two points that need to be especially noted:

1. Only background thread scripts can remain non-inlined, whereas the main thread script is always inlined.

2. Currently, when `experimental_isLazyBundle` is enabled, `inlineScripts` will always be `true`<!-- -->.

## Example

Disable inlining background thread scripts.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    inlineScripts: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.output.legalcomments.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [legalComments](/api/rspeedy/rspeedy.output.legalcomments.md)

## Output.legalComments property

The [Output.legalComments](/api/rspeedy/rspeedy.output.legalcomments.md) controls how to handle the legal comment.

**Signature:**

```typescript
legalComments?: 'none' | 'inline' | 'linked' | undefined;
```

## Default Value

`'none'`

## Remarks

This is different with Rsbuild since we normally do not want a `.LEGAL.txt` file in Lynx outputs.

This behavior can be configured by using one of the following options:

- `linked`<!-- -->: Extract all legal comments to a `.LEGAL.txt` file and link to them with a comment.

- `inline`<!-- -->: Preserve all legal comments in original position.

- `none`<!-- -->: Remove all legal comments.



---
url: /api/rspeedy/rspeedy.output.minify.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [minify](/api/rspeedy/rspeedy.output.minify.md)

## Output.minify property

The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

**Signature:**

```typescript
minify?: Minify | boolean | undefined;
```

## Default Value

`true` in production builds and `false` otherwise

## Example

Disable minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  output: {
    minify: false,
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.css.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [css](/api/rspeedy/rspeedy.minify.css.md)

## Minify.css property

Whether enable the CSS minification.

**Signature:**

```typescript
css?: boolean | undefined;
```

## Default Value

When `output.minify` is enabled and `css` is unset, this defaults to `true`<!-- -->.

## Remarks

When building for production, [@rsbuild/plugin-css-minimizer](https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer) is used to minify CSS assets for better transmission efficiency.

## Example

- Disable the CSS minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      css: false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.js.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [js](/api/rspeedy/rspeedy.minify.js.md)

## Minify.js property

Whether enable the JavaScript minification.

**Signature:**

```typescript
js?: boolean | undefined;
```

## Default Value

When `output.minify` is enabled and `js` is unset, this defaults to `true`<!-- -->.

## Example

- Disable the JavaScript minification.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      js: false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.jsoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md)

## Minify.jsOptions property

[Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) is used to configure SWC minification options.

**Signature:**

```typescript
jsOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
```

## Default Value

When JavaScript minification is enabled and `jsOptions` is unset, this defaults to `{}`<!-- -->.

## Remarks

For detailed configurations, please refer to [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin)<!-- -->.

## Example

- Disable the mangle feature.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          mangle: false,
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.output.sourcemap.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Output](/api/rspeedy/rspeedy.output.md) > [sourceMap](/api/rspeedy/rspeedy.output.sourcemap.md)

## Output.sourceMap property

The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
sourceMap?: boolean | SourceMap | undefined;
```

## Default Value

When this option is unset, JavaScript source maps use `'cheap-module-source-map'` in development and are otherwise disabled; CSS source maps are disabled.



---
url: /api/rspeedy/rspeedy.sourcemap.css.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) > [css](/api/rspeedy/rspeedy.sourcemap.css.md)

## SourceMap.css property

Whether to generate CSS source maps.

**Signature:**

```typescript
css?: boolean | undefined;
```

## Remarks

Defaults to `true`<!-- -->.

## Example

Disable CSS sourcemap.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      css: false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.sourcemap.js.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) > [js](/api/rspeedy/rspeedy.sourcemap.js.md)

## SourceMap.js property

How the source map should be generated. Setting it to `false` will disable the source map.

**Signature:**

```typescript
js?: Rspack.DevTool | undefined | `${Exclude<Rspack.DevTool, false | 'eval'>}-debugids`;
```

## Default Value

When `output.sourceMap` is an object and `js` is unset, it defaults to `'cheap-module-source-map'` in development and `false` in production.

## Remarks

See [Rspack - Devtool](https://rspack.rs/config/devtool) for details.

## Example 1

- Enable high-quality source-maps for production:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: process.env['NODE_ENV'] === 'production'
        ? 'source-map'
        : 'cheap-module-source-map',
    },
  },
})
```

## Example 2

- Disable source-map generation:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: false,
    },
  },
})
```

## Example 3

- Use high-quality source-maps for all environments:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    sourceMap: {
      js: 'source-map',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.performance.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md)

## Performance interface

The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

**Signature:**

```typescript
export interface Performance 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[buildCache?](/api/rspeedy/rspeedy.performance.buildcache.md)

</td><td>

</td><td>

[BuildCache](/api/rspeedy/rspeedy.buildcache.md) | boolean | undefined

</td><td>

**_(BETA)_** _(Optional)_ Enable or configure persistent build cache.

</td></tr>
<tr><td>

[chunkSplit?](/api/rspeedy/rspeedy.performance.chunksplit.md)

</td><td>

</td><td>

[ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) | [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) | [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) | undefined

</td><td>

_(Optional)_ [Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

</td></tr>
<tr><td>

[printFileSize?](/api/rspeedy/rspeedy.performance.printfilesize.md)

</td><td>

</td><td>

PerformanceConfig\['printFileSize'] | undefined

</td><td>

_(Optional)_ Whether to print the file sizes after production build.

</td></tr>
<tr><td>

[profile?](/api/rspeedy/rspeedy.performance.profile.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether capture timing information in Lynx runtime integrations such as ReactLynx.

</td></tr>
<tr><td>

[removeConsole?](/api/rspeedy/rspeedy.performance.removeconsole.md)

</td><td>

</td><td>

boolean | [ConsoleType](/api/rspeedy/rspeedy.consoletype.md)<!-- -->\[] | undefined

</td><td>

_(Optional)_ Whether to remove `console.[methodName]` in production build.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.performance.buildcache.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [buildCache](/api/rspeedy/rspeedy.performance.buildcache.md)

## Performance.buildCache property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Enable or configure persistent build cache.

**Signature:**

```typescript
buildCache?: BuildCache | boolean | undefined;
```

## Default Value

false

This feature is experimental and may be changed in the future.

## Example 1

Enable persistent build cache.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: true,
  },
})
```

## Example 2

Customize build cache.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
      buildDependencies: ['postcss.config.js'],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.buildcache.builddependencies.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [buildDependencies](/api/rspeedy/rspeedy.buildcache.builddependencies.md)

## BuildCache.buildDependencies property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

An array of files containing build dependencies. Rspack will use the hash of each of these files to invalidate the persistent cache.

**Signature:**

```typescript
buildDependencies?: string[] | undefined;
```

## Default Value

`['package.json', 'tsconfig.json' (or source.tsconfigPath), '.env', '.env.*', 'tailwindcss.config.*']`<!-- -->; when using the Rspeedy CLI with `performance.buildCache` enabled, the loaded `lynx.config.*` file is also added.

## Example

Add `postcss.config.js` to the build dependencies.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      buildDependencies: ['postcss.config.js'],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.buildcache.cachedigest.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [cacheDigest](/api/rspeedy/rspeedy.buildcache.cachedigest.md)

## BuildCache.cacheDigest property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.

**Signature:**

```typescript
cacheDigest?: Array<string | undefined> | undefined;
```

## Default Value

undefined

## Example

Add `process.env.SOME_ENV` to the cache digest.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.buildcache.cachedirectory.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md) > [cacheDirectory](/api/rspeedy/rspeedy.buildcache.cachedirectory.md)

## BuildCache.cacheDirectory property

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

The output directory of the cache files.

**Signature:**

```typescript
cacheDirectory?: string | undefined;
```

## Default Value

'node\_modules/.cache'



---
url: /api/rspeedy/rspeedy.performance.chunksplit.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md)

## Performance.chunkSplit property

> Warning: This API is now obsolete.
>
> Use the top-level [Config.splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md) option instead.

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
chunkSplit?: ChunkSplit | ChunkSplitBySize | ChunkSplitCustom | undefined;
```

## Default Value

For web builds, Rsbuild currently uses `{ strategy: 'split-by-experience' }` when this option is unset.



---
url: /api/rspeedy/rspeedy.chunksplit.override.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) > [override](/api/rspeedy/rspeedy.chunksplit.override.md)

## ChunkSplit.override property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
override?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```

## Default Value

undefined

## Example

- Split `@lynx-js/react` and `react-router` into chunk `lib-react`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
      override: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](@lynx-js[\\/]react|react-router)[\\/]/,
            name: 'lib-react',
          },
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplit.strategy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md) > [strategy](/api/rspeedy/rspeedy.chunksplit.strategy.md)

## ChunkSplit.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy?: 'all-in-one' | 'split-by-module' | 'split-by-experience' | 'single-vendor' | undefined;
```

## Default Value

In Rsbuild's default chunk splitting behavior, the strategy is `'split-by-experience'`<!-- -->.

## Remarks

- `split-by-experience`<!-- -->(Rsbuild default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.

## Example 1

- Use `all-in-one` to put all modules in one chunk.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
})
```

## Example 2

- Use `single-vendor` to put all third-party dependencies in one chunk. And source code in another chunk.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'single-vendor',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.maxsize.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [maxSize](/api/rspeedy/rspeedy.chunksplitbysize.maxsize.md)

## ChunkSplitBySize.maxSize property

The maximum size of a chunk, unit in bytes.

**Signature:**

```typescript
maxSize?: number | undefined;
```

## Default Value

`Number.POSITIVE_INFINITY`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      maxSize: 50000,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitbysize.minsize.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [minSize](/api/rspeedy/rspeedy.chunksplitbysize.minsize.md)

## ChunkSplitBySize.minSize property

The minimum size of a chunk, unit in bytes.

**Signature:**

```typescript
minSize?: number | undefined;
```

## Default Value

10000

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 20000,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) > [splitChunks](/api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md)

## ChunkSplitCustom.splitChunks property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
splitChunks?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```

## Default Value

undefined

## Example

- Split `@lynx-js/react` and `react-router` into chunk `lib-react`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'custom',
      splitChunks: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](@lynx-js[\\/]react|react-router)[\\/]/,
            name: 'lib-react',
          },
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.performance.printfilesize.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)

## Performance.printFileSize property

Whether to print the file sizes after production build.

**Signature:**

```typescript
printFileSize?: PerformanceConfig['printFileSize'] | undefined;
```

## Default Value

true

[Performance.printFileSize](/api/rspeedy/rspeedy.performance.printfilesize.md)

See [Rsbuild - performance.printFileSize](https://rsbuild.rs/config/performance/print-file-size) for details.

## Example 1

If you don't want to print any information, you can disable it by setting printFileSize to false:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: false
  },
})
```

## Example 2

Set total to false to disable total size output.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      total: false,
    },
  },
})
```

## Example 3

Set detail to false to disable per-asset size output.

If you don't need to view the size of each static asset, you can set detail to false. In this case, only the total size will be output:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      detail: false,
    },
  },
})
```

## Example 4

If you don't need to view the gzipped size, you can set compressed to false. This can save some gzip computation time for large projects:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      compressed: false,
    },
  },
})
```

## Example 5

To include only static assets that meet certain criteria, use a filter function with include.

If returned false, the static asset will be excluded and not included in the total size or detailed size.

only output static assets larger than 10kB:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      include: (asset) => asset.size > 10 * 1000,
    }
  },
})
```

## Example 6

To exclude static assets that meet certain criteria, use a filter function with exclude. If both include and exclude are set, exclude will take precedence.

Rspeedy defaults to excluding source map, license files, and .d.ts type files, as these files do not affect page load performance.

exclude .html files in addition to the default:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    printFileSize: {
      exclude: (asset) =>
        /\.(?:map|LICENSE\.txt)$/.test(asset.name) ||
        /\.html$/.test(asset.name),
    }
  },
})
```



---
url: /api/rspeedy/rspeedy.performance.profile.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [profile](/api/rspeedy/rspeedy.performance.profile.md)

## Performance.profile property

Whether capture timing information in Lynx runtime integrations such as ReactLynx.

**Signature:**

```typescript
profile?: boolean | undefined;
```

## Default Value

Rspeedy sets this to `true` when `DEBUG` contains `rspeedy`<!-- -->; otherwise it leaves the option unset.

## Example

Enable profile.

- Frameworks like ReactLynx will include runtime information using `console.profile`<!-- -->. - Rspeedy will emit `dist/stats.json` after build for bundle analysis compatibility.

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: { profile: true },
})
```



---
url: /api/rspeedy/rspeedy.performance.removeconsole.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Performance](/api/rspeedy/rspeedy.performance.md) > [removeConsole](/api/rspeedy/rspeedy.performance.removeconsole.md)

## Performance.removeConsole property

Whether to remove `console.[methodName]` in production build.

**Signature:**

```typescript
removeConsole?: boolean | ConsoleType[] | undefined;
```

## Default Value

false

## Example 1

- Remove all `console` methods

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    removeConsole: true,
  },
})
```

## Example 2

- Remove specific `console` methods

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  performance: {
    removeConsole: ['log', 'warn']
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md)

## Resolve interface

The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

**Signature:**

```typescript
export interface Resolve 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[alias?](/api/rspeedy/rspeedy.resolve.alias.md)

</td><td>

</td><td>

Record\<string, string | false | string\[]> | undefined

</td><td>

_(Optional)_ Create aliases to `import` or `require` certain modules more easily.

</td></tr>
<tr><td>

[aliasStrategy?](/api/rspeedy/rspeedy.resolve.aliasstrategy.md)

</td><td>

</td><td>

'prefer-tsconfig' | 'prefer-alias' | undefined

</td><td>

_(Optional)_ Set the strategy for path alias resolution, to control the priority relationship between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild.

</td></tr>
<tr><td>

[dedupe?](/api/rspeedy/rspeedy.resolve.dedupe.md)

</td><td>

</td><td>

string\[] | undefined

</td><td>

_(Optional)_ Force to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

</td></tr>
<tr><td>

[extensions?](/api/rspeedy/rspeedy.resolve.extensions.md)

</td><td>

</td><td>

string\[] | undefined

</td><td>

_(Optional)_ Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.resolve.alias.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [alias](/api/rspeedy/rspeedy.resolve.alias.md)

## Resolve.alias property

Create aliases to `import` or `require` certain modules more easily.

**Signature:**

```typescript
alias?: Record<string, string | false | string[]> | undefined;
```

## Default Value

undefined

## Example 1

A trailing `$` can also be added to the given object's keys to signify an exact match:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  resolve: {
    alias: {
      xyz$: 'path/to/file.js',
    },
  },
})
```

which would yield these results:

```js
import Test1 from 'xyz'; // Exact match, so path/to/file.js is resolved and imported
import Test2 from 'xyz/file.js'; // Not an exact match, normal resolution takes place
```

## Example 2

`resolve.alias` is useful to control how a npm package is resolved.

- Change `react` to `@lynx-js/react`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
export default defineConfig({
  resolve: {
    alias: {
      react: require.resolve('@lynx-js/react'),
    },
  },
})
```

This allows you to use some third-party libraries that directly uses `react` as dependencies in ReactLynx.

- Force using the same version of `dayjs`<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
export default defineConfig({
  resolve: {
    alias: {
      dayjs: require.resolve('dayjs'),
    },
  },
})
```

Please note that this is dangerous, since all the `dayjs`<!-- -->(including the dependencies of a dependencies) is resolved to the version in the project. It may cause both compile-time and runtime errors due to version mismatch.

## Example 3

Setting `resolve.alias` to `false` will ignore a module.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  resolve: {
    alias: {
      'ignored-module': false,
      './ignored-module': false,
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.aliasstrategy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [aliasStrategy](/api/rspeedy/rspeedy.resolve.aliasstrategy.md)

## Resolve.aliasStrategy property

Set the strategy for path alias resolution, to control the priority relationship between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild.

**Signature:**

```typescript
aliasStrategy?: 'prefer-tsconfig' | 'prefer-alias' | undefined;
```

## Default Value

`'prefer-tsconfig'`

- `prefer-tsconfig` (default): The `paths` option in `tsconfig.json` will take precedence over the `resolve.alias` option of Rsbuild. - `prefer-alias`<!-- -->: The `resolve.alias` option of Rsbuild will take precedence over the `paths` option in `tsconfig.json`<!-- -->.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  resolve: {
    alias: {
      '@': './src',
    },
    aliasStrategy: 'prefer-alias',
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.dedupe.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md)

## Resolve.dedupe property

Force to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

**Signature:**

```typescript
dedupe?: string[] | undefined;
```

## Default Value

undefined

## Remarks

[Resolve.dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md) is implemented based on [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md)<!-- -->, it will get the path of the specified package through `require.resolve` in the project root directory and set it to the alias.

The alias generated by [Resolve.dedupe](/api/rspeedy/rspeedy.resolve.dedupe.md) will be merged with the configured [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) in the project, and the [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) config will take precedence when the keys are the same.

## Example

Use `tslib` from the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  resolve: {
    dedupe: ['tslib'],
  },
})
```



---
url: /api/rspeedy/rspeedy.resolve.extensions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Resolve](/api/rspeedy/rspeedy.resolve.md) > [extensions](/api/rspeedy/rspeedy.resolve.extensions.md)

## Resolve.extensions property

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

**Signature:**

```typescript
extensions?: string[] | undefined;
```

## Default Value

`['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json', '.cjs']`

For example, if importing './index', Rsbuild will try to resolve using the following order:

- `./index.ts`

- `./index.tsx`

- `./index.mjs`

- `./index.js`

- `./index.jsx`

- `./index.json`

- `./index.cjs`

## Remarks

The difference between `resolve.extensions` and `tools.rspack.resolve.extensions`<!-- -->:

`resolve.extensions`<!-- -->: Completely overrides Rspeedy's default resolution.

`tools.rspack.resolve.extensions`<!-- -->: Merges with the default configuration using \[`webpack-merge`<!-- -->]\([https://github.com/survivejs/webpack-merge](https://github.com/survivejs/webpack-merge)).

## Example

```js
export default {
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
}
```



---
url: /api/rspeedy/rspeedy.server.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md)

## Server interface

The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

**Signature:**

```typescript
export interface Server 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[base?](/api/rspeedy/rspeedy.server.base.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Configure the base path of the server.

</td></tr>
<tr><td>

[compress?](/api/rspeedy/rspeedy.server.compress.md)

</td><td>

</td><td>

boolean | CompressOptions | undefined

</td><td>

_(Optional)_ Configure whether to enable [gzip compression](https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression) for static assets served by the dev server or preview server.

</td></tr>
<tr><td>

[cors?](/api/rspeedy/rspeedy.server.cors.md)

</td><td>

</td><td>

ServerConfig\['cors'] | undefined

</td><td>

_(Optional)_ Configure CORS for the dev server or preview server.

</td></tr>
<tr><td>

[headers?](/api/rspeedy/rspeedy.server.headers.md)

</td><td>

</td><td>

Record\<string, string | string\[]> | undefined

</td><td>

_(Optional)_ Adds headers to all responses.

</td></tr>
<tr><td>

[host?](/api/rspeedy/rspeedy.server.host.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Specify the host that the Rspeedy Server listens to.

</td></tr>
<tr><td>

[port?](/api/rspeedy/rspeedy.server.port.md)

</td><td>

</td><td>

number | undefined

</td><td>

_(Optional)_ Specify the port that the Rspeedy Server listens to.

</td></tr>
<tr><td>

[proxy?](/api/rspeedy/rspeedy.server.proxy.md)

</td><td>

</td><td>

ProxyConfig | undefined

</td><td>

_(Optional)_ Configure proxy rules for the dev server or preview server to proxy requests to the specified service.

</td></tr>
<tr><td>

[strictPort?](/api/rspeedy/rspeedy.server.strictport.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ When a port is occupied, Rspeedy will automatically increment the port number until an available port is found.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.server.base.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [base](/api/rspeedy/rspeedy.server.base.md)

## Server.base property

Configure the base path of the server.

**Signature:**

```typescript
base?: string | undefined;
```

## Default Value

`'/'`

## Remarks

Users can access lynx bundle through `http://<host>:<port>/main.lynx.bundle` by default.

If you want to access lynx bundle through `http://<host>:<port>/foo/main.lynx.bundle`<!-- -->, you can change `server.base` to `/foo`

you can refer to [server.base](https://rsbuild.rs/config/server/base) for more information.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    base: '/dist'
  },
})
```



---
url: /api/rspeedy/rspeedy.server.compress.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [compress](/api/rspeedy/rspeedy.server.compress.md)

## Server.compress property

Configure whether to enable [gzip compression](https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression) for static assets served by the dev server or preview server.

**Signature:**

```typescript
compress?: boolean | CompressOptions | undefined;
```

## Default Value

true

See [Rsbuild - server.compress](https://rsbuild.rs/config/server/compress) for details.

## Example 1

To disable the gzip compression, set compress to false:

```js
export default {
  server: {
    compress: false,
  },
}
```

## Example 2

Compress if it starts with /foo

```js
export default {
  server: {
    compress: {
      filter: (req) => {
        if (req.url?.includes('/foo')) {
          return false;
        }
        return true;
      },
    },
  },
}
```

## Example 3

set level of zlib compression

```js
export default {
  server: {
    compress: {
      level: 6,
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.cors.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [cors](/api/rspeedy/rspeedy.server.cors.md)

## Server.cors property

Configure CORS for the dev server or preview server.

**Signature:**

```typescript
cors?: ServerConfig['cors'] | undefined;
```

## Default Value

Uses Rsbuild's default CORS options.

- Set to an object to enable CORS with the specified options.

- Set to `true` to enable CORS with the default options (allows all origins, not recommended).

- Set to `false` to disable CORS.

See [Rsbuild - server.cors](https://rsbuild.rs/config/server/cors) for details.

## Example

```js
export default {
  server: {
    cors: {
      origin: 'https://example.com',
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.headers.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [headers](/api/rspeedy/rspeedy.server.headers.md)

## Server.headers property

Adds headers to all responses.

**Signature:**

```typescript
headers?: Record<string, string | string[]> | undefined;
```

## Default Value

undefined

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    headers: {
      'Access-Control-Allow-Origin': '**',
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.server.host.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [host](/api/rspeedy/rspeedy.server.host.md)

## Server.host property

Specify the host that the Rspeedy Server listens to.

**Signature:**

```typescript
host?: string | undefined;
```

## Default Value

"0.0.0.0"

## Remarks

During `rspeedy dev`<!-- -->, if `server.host` is unset, the dev plugin resolves dev-server-related URLs and client host settings with a detected local IPv4 address, such as `192.168.1.50`<!-- -->. If you have multiple network interfaces, set `server.host` explicitly to choose the desired address.

## Example

Set the host to a custom value:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    host: "192.168.1.50",
  },
})
```



---
url: /api/rspeedy/rspeedy.server.port.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [port](/api/rspeedy/rspeedy.server.port.md)

## Server.port property

Specify the port that the Rspeedy Server listens to.

**Signature:**

```typescript
port?: number | undefined;
```

## Default Value

Rsbuild defaults this option to `3000`<!-- -->.

## Remarks

By default, the server automatically increments the port number when the configured port is occupied.

## Example

Set the port to a custom value:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  server: {
    port: 3470,
  },
})
```



---
url: /api/rspeedy/rspeedy.server.proxy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [proxy](/api/rspeedy/rspeedy.server.proxy.md)

## Server.proxy property

Configure proxy rules for the dev server or preview server to proxy requests to the specified service.

**Signature:**

```typescript
proxy?: ProxyConfig | undefined;
```

## Default Value

undefined

## Example

```js
export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000/api
      // http://localhost:3000/api/foo -> http://localhost:3000/api/foo
      '/api': 'http://localhost:3000',
    },
  },
}
```



---
url: /api/rspeedy/rspeedy.server.strictport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Server](/api/rspeedy/rspeedy.server.md) > [strictPort](/api/rspeedy/rspeedy.server.strictport.md)

## Server.strictPort property

When a port is occupied, Rspeedy will automatically increment the port number until an available port is found.

**Signature:**

```typescript
strictPort?: boolean | undefined;
```

## Default Value

false

By default, strict port mode is disabled. Set strictPort to true and Rspeedy will throw an exception when the port is occupied.



---
url: /api/rspeedy/rspeedy.source.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md)

## Source interface

The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

**Signature:**

```typescript
export interface Source 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[alias?](/api/rspeedy/rspeedy.source.alias.md)

</td><td>

</td><td>

Record\<string, string | false | string\[]> | undefined

</td><td>

_(Optional)_ Create aliases to `import` or `require` certain modules more easily.

</td></tr>
<tr><td>

[assetsInclude?](/api/rspeedy/rspeedy.source.assetsinclude.md)

</td><td>

</td><td>

Rspack.RuleSetCondition | undefined

</td><td>

_(Optional)_ Include additional files that should be treated as static assets.

</td></tr>
<tr><td>

[decorators?](/api/rspeedy/rspeedy.source.decorators.md)

</td><td>

</td><td>

[Decorators](/api/rspeedy/rspeedy.decorators.md) | undefined

</td><td>

_(Optional)_ Used to configure the decorators syntax.

</td></tr>
<tr><td>

[define?](/api/rspeedy/rspeedy.source.define.md)

</td><td>

</td><td>

Rspack.DefinePluginOptions

</td><td>

_(Optional)_ The `define` options is used to define some values or expressions at compile time.

</td></tr>
<tr><td>

[entry?](/api/rspeedy/rspeedy.source.entry.md)

</td><td>

</td><td>

[Entry](/api/rspeedy/rspeedy.entry.md) | undefined

</td><td>

_(Optional)_ The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

</td></tr>
<tr><td>

[exclude?](/api/rspeedy/rspeedy.source.exclude.md)

</td><td>

</td><td>

Rspack.RuleSetCondition\[] | undefined

</td><td>

_(Optional)_ The `source.exclude` is used to specify JavaScript files that should be excluded from compilation.

</td></tr>
<tr><td>

[include?](/api/rspeedy/rspeedy.source.include.md)

</td><td>

</td><td>

Rspack.RuleSetCondition\[] | undefined

</td><td>

_(Optional)_ The `source.include` is used to specify additional JavaScript files that need to be compiled.

</td></tr>
<tr><td>

[preEntry?](/api/rspeedy/rspeedy.source.preentry.md)

</td><td>

</td><td>

string | string\[] | undefined

</td><td>

_(Optional)_ Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.

</td></tr>
<tr><td>

[transformImport?](/api/rspeedy/rspeedy.source.transformimport.md)

</td><td>

</td><td>

[TransformImport](/api/rspeedy/rspeedy.transformimport.md)<!-- -->\[] | undefined

</td><td>

_(Optional)_ The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

</td></tr>
<tr><td>

[tsconfigPath?](/api/rspeedy/rspeedy.source.tsconfigpath.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.source.alias.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [alias](/api/rspeedy/rspeedy.source.alias.md)

## Source.alias property

> Warning: This API is now obsolete.
>
> - Use [Resolve.alias](/api/rspeedy/rspeedy.resolve.alias.md) instead.

Create aliases to `import` or `require` certain modules more easily.

**Signature:**

```typescript
alias?: Record<string, string | false | string[]> | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.source.assetsinclude.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [assetsInclude](/api/rspeedy/rspeedy.source.assetsinclude.md)

## Source.assetsInclude property

Include additional files that should be treated as static assets.

**Signature:**

```typescript
assetsInclude?: Rspack.RuleSetCondition | undefined;
```

## Default Value

undefined

## Remarks

By default, Rsbuild treats common image, font, audio, and video files as static assets. Through the source.assetsInclude config, you can specify additional file types that should be treated as static assets. These added static assets are processed using the same rules as the built-in supported static assets。

The usage of `source.assetsInclude` is consistent with [Condition](https://rspack.rs/config/module#condition) in Rspack, which supports passing in strings, regular expressions, arrays of conditions, or logical conditions to match the module path or assets.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    assetsInclude: /\.json5$/,
  },
})
```



---
url: /api/rspeedy/rspeedy.source.decorators.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [decorators](/api/rspeedy/rspeedy.source.decorators.md)

## Source.decorators property

Used to configure the decorators syntax.

**Signature:**

```typescript
decorators?: Decorators | undefined;
```

## Default Value

undefined

## Remarks

See [Decorators.version](/api/rspeedy/rspeedy.decorators.version.md) for more information.



---
url: /api/rspeedy/rspeedy.decorators.version.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Decorators](/api/rspeedy/rspeedy.decorators.md) > [version](/api/rspeedy/rspeedy.decorators.version.md)

## Decorators.version property

Specify the decorator syntax version to be used.

**Signature:**

```typescript
version?: 'legacy' | '2022-03';
```

## Default Value

`'2022-03'`

## Remarks

If you want to know the differences between different decorators versions, you can refer to: [How does this proposal compare to other versions of decorators?](https://github.com/tc39/proposal-decorators?tab=readme-ov-file#how-does-this-proposal-compare-to-other-versions-of-decorators)

## Example 1

`'2022-03'` corresponds to the Stage 3 decorator proposal, equivalent to the decorator syntax supported by TypeScript 5.0 by default.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    decorators: { version: '2022-03' },
  },
})
```

## Example 2

`'legacy'` corresponds to TypeScript's `experimentalDecorators: true`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    decorators: { version: 'legacy' },
  },
})
```



---
url: /api/rspeedy/rspeedy.source.define.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [define](/api/rspeedy/rspeedy.source.define.md)

## Source.define property

The `define` options is used to define some values or expressions at compile time.

**Signature:**

```typescript
define?: Rspack.DefinePluginOptions;
```

## Default Value

undefined

## Remarks

- If the value provided is a string, it will be utilized as a code fragment.

- If the value provided is an object, all its keys will be defined in the same manner.

- If the value isn't a string, it will be stringified, with functions included.

- Notably, if a `typeof` prefix is attached to the key, it will be exclusively defined for `typeof` calls."

## Example 1

Using `define` for environment variables.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      BUILD_VERSION: JSON.stringify(process.env.BUILD_VERSION ?? 'unknown_version'),
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    },
  },
})
```

Expressions will be replaced with the corresponding code fragments:

```js
const version = BUILD_VERSION;
if (process.env.NODE_ENV === 'development') {}

// ⬇️ Turn into being...
const version = "unknown_version";
if ("development" === 'development') {}
```

## Example 2

Using `define` for `typeof`<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'typeof window': JSON.stringify("undefined"),
    },
  },
})
```

The `typeof` expressions will be replaced with the corresponding code fragments:

```js
if (typeof window !== 'undefined') {}

// ⬇️ Turn into being...
if ("undefined" !== 'undefined') {}
```

## Example 3

Using `define` with objects.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'import.meta': {
        foo: JSON.stringify('foo'),
        bar: { baz: 0 },
      },
    },
  },
})
```

Expressions will be replaced with the corresponding code fragments:

```js
console.log(import.meta)

// ⬇️ Turn into being...
console.log({ foo: "foo", bar: { baz: 0 } })
```



---
url: /api/rspeedy/rspeedy.source.entry.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [entry](/api/rspeedy/rspeedy.source.entry.md)

## Source.entry property

The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

**Signature:**

```typescript
entry?: Entry | undefined;
```

## Default Value

`'./src/index.js'`

## Example 1

- Use a single entry:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: './src/pages/main/index.js',
  },
})
```

## Example 2

- Use a single entry with multiple entry modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: ['./src/prefetch.js', './src/pages/main/index.js'],
  },
})
```

## Example 3

- Use multiple entries(with multiple entry modules):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: ['./src/pages/bar/index.js', './src/post.js'], // multiple entry modules is allowed
    },
  },
})
```

## Example 4

- Use multiple entries with [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: {
        import: ['./src/prefetch.js', './src/pages/bar'],
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.source.exclude.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [exclude](/api/rspeedy/rspeedy.source.exclude.md)

## Source.exclude property

The `source.exclude` is used to specify JavaScript files that should be excluded from compilation.

**Signature:**

```typescript
exclude?: Rspack.RuleSetCondition[] | undefined;
```

## Default Value

undefined

## Remarks

By default, Rsbuild compiles JavaScript files in the current directory and TypeScript/JSX files in all directories. Through the `source.exclude` config, you can specify files or directories that should be excluded from compilation. The usage of `source.exclude` is consistent with [Rule.exclude](https://rspack.rs/config/module#ruleexclude) in Rspack, which supports passing in strings or regular expressions to match module paths.

## Example 1

- Exclude specific files or directories

You can exclude specific files or directories from compilation to improve build performance or avoid processing certain files:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    exclude: [
      // Exclude all files in the test directory
      /[\\/]test[\\/]/,
      // Exclude specific file
      './src/legacy-file.js',
      // Exclude files matching a pattern
      /\.stories\.(js|ts)x?$/,
    ],
  },
})
```

## Example 2

- Exclude third-party dependencies

You can exclude specific third-party dependencies that don't need compilation:

```js
import { defineConfig } from '@lynx-js/rspeedy'
import path from 'node:path'
import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    exclude: [
      // Exclude specific package
      path.dirname(require.resolve('lodash')),
      // Exclude using regex pattern
      /node_modules[\\/]lodash-es[\\/]/,
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.source.include.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [include](/api/rspeedy/rspeedy.source.include.md)

## Source.include property

The `source.include` is used to specify additional JavaScript files that need to be compiled.

**Signature:**

```typescript
include?: Rspack.RuleSetCondition[] | undefined;
```

## Default Value

When unset, Rsbuild compiles JavaScript files in the current directory and TypeScript or JSX files in all directories, while excluding JavaScript files under `node_modules`<!-- -->.

## Remarks

To avoid redundant compilation, by default, Rsbuild only compiles JavaScript files in the current directory and TypeScript and JSX files in all directories. It does not compile JavaScript files under `node_modules`<!-- -->.

Through the `source.include` config, you can specify directories or modules that need to be compiled by Rsbuild. The usage of `source.include` is consistent with [Rule.include](https://rspack.rs/config/module#ruleinclude) in Rspack, which supports passing in strings or regular expressions to match the module path.

## Example 1

- Compile Npm Packages

A typical usage scenario is to compile npm packages under `node_modules`<!-- -->, because some third-party dependencies have ESNext syntax, which may not be supported in Lynx. You can solve the problem by using this config to specify the dependencies that need to be compiled.

```js
import { createRequire } from 'node:module'
import path from 'node:path'

import { defineConfig } from '@lynx-js/rspeedy'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    include: [
      // Method 1:
      // First get the path of the module by `require.resolve`
      // Then pass path.dirname to point to the corresponding directory
      path.dirname(require.resolve('query-string')),
      // Method 2:
      // Match by regular expression
      // All paths containing `node_modules/query-string/` will be matched
      /node_modules[\\/]query-string[\\/]/,
    ],
  },
})
```

## Example 2

- Compile Libraries in Monorepo

```js
import path from 'node:path'
import { fileURLToPath } from 'node:url'

import { defineConfig } from '@lynx-js/rspeedy'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const packagesDir = path.resolve(__dirname, '../../packages')

export default defineConfig({
  source: {
    include: [
      // Compile all files in Monorepo's package directory
      // It is recommended to exclude the node_modules
      {
        and: [packagesDir, { not: /[\\/]node_modules[\\/]/ }],
      },
    ],
  },
})
```



---
url: /api/rspeedy/rspeedy.source.preentry.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [preEntry](/api/rspeedy/rspeedy.source.preentry.md)

## Source.preEntry property

Add a script before the entry file of each page. This script will be executed before the page code. It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.

**Signature:**

```typescript
preEntry?: string | string[] | undefined;
```

## Default Value

undefined

## Remarks

See [source.preEntry](https://rsbuild.rs/config/source/pre-entry) for more details.

## Example

Relative path will be resolved relative to the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    preEntry: './src/polyfill.ts',
  },
})
```



---
url: /api/rspeedy/rspeedy.source.transformimport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [transformImport](/api/rspeedy/rspeedy.source.transformimport.md)

## Source.transformImport property

The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

**Signature:**

```typescript
transformImport?: TransformImport[] | undefined;
```

## Default Value

undefined

## Example

When using the TUX component library, you can import components on demand with the following config:

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    transformImport: [
      {
        libraryName: 'foo',
        customName: 'foo/src/components/{{ member }}/{{ member }}',
      },
    ],
  },
})
```

This will transform the following source code:

```js
import { Button } from 'foo'
```

to:

```js
import { Button } from 'foo/src/components/Button/Button'
```



---
url: /api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [camelToDashComponentName](/api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md)

## TransformImport.camelToDashComponentName property

Whether to convert camelCase imports to kebab-case.

**Signature:**

```typescript
camelToDashComponentName?: boolean | undefined;
```

## Default Value

Rsbuild defaults this option to `true`<!-- -->.

## Example

- Input:

```js
import { ButtonGroup } from 'foo'
```

- Output:

When set to `true`<!-- -->:

```js
import ButtonGroup from 'foo/button-group'
```

When set to `false`<!-- -->:

```js
import ButtonGroup from 'foo/ButtonGroup'
```



---
url: /api/rspeedy/rspeedy.transformimport.customname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [customName](/api/rspeedy/rspeedy.transformimport.customname.md)

## TransformImport.customName property

Customize the transformed path.

**Signature:**

```typescript
customName?: string | undefined;
```

## Default Value

undefined

## Remarks

You you can specify the format of the transformed path. For example, by setting it to `my-lib/{{ camelCase member }}`<!-- -->, you can convert the member into camelCase.

The following formats are supported:

- `kebabCase`<!-- -->: lowercase letters, words joined by hyphens. For example: `my-variable-name`<!-- -->.

- `snakeCase`<!-- -->: lowercase letters, words joined by underscores. For example: `my_variable_name`<!-- -->.

- `camelCase`<!-- -->: first letter lowercase, the first letter of each following word uppercase. For example: `myVariableName`<!-- -->.

- `upperCase`<!-- -->: uppercase letters, other characters unchanged. For example: `MY-VARIABLE-NAME`<!-- -->.

- `lowerCase`<!-- -->: lowercase letters, other characters unchanged. For example: `my-variable-name`<!-- -->.



---
url: /api/rspeedy/rspeedy.transformimport.librarydirectory.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [libraryDirectory](/api/rspeedy/rspeedy.transformimport.librarydirectory.md)

## TransformImport.libraryDirectory property

Used to splice the transformed path, the splicing rule is `${libraryName}/${libraryDirectory}/${member}`<!-- -->, where member is the imported member.

**Signature:**

```typescript
libraryDirectory?: string | undefined;
```

## Default Value

`'lib'`

## Example

- Input:

```js
import { Button } from 'foo'
```

- Output:

```js
import Button from 'foo/lib/button'
```



---
url: /api/rspeedy/rspeedy.transformimport.libraryname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [libraryName](/api/rspeedy/rspeedy.transformimport.libraryname.md)

## TransformImport.libraryName property

The original import path that needs to be transformed.

**Signature:**

```typescript
libraryName: string;
```

## Remarks

This option is required.



---
url: /api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md) > [transformToDefaultImport](/api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md)

## TransformImport.transformToDefaultImport property

Whether to convert import statements to default imports.

**Signature:**

```typescript
transformToDefaultImport?: boolean | undefined;
```

## Default Value

Rsbuild defaults this option to `true`<!-- -->.

## Example

- Input:

```js
import { Button } from 'foo'
```

- Output:

When set to `true`<!-- -->:

```js
import Button from 'foo/button'
```

When set to `false`<!-- -->:

```js
import { Button } from 'foo/button'
```



---
url: /api/rspeedy/rspeedy.source.tsconfigpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Source](/api/rspeedy/rspeedy.source.md) > [tsconfigPath](/api/rspeedy/rspeedy.source.tsconfigpath.md)

## Source.tsconfigPath property

Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path.

**Signature:**

```typescript
tsconfigPath?: string | undefined;
```

## Default Value

`'./tsconfig.json'`

## Remarks

The `tsconfigPath` configuration affects the following behaviors:

- The `paths` field is used to configure [Path Aliases](/api/rspeedy/rspeedy.source.alias.md)<!-- -->.

- Sets the scope and rules for the [Type Check Plugin](https://rsbuild.rs/guide/basic/typescript#type-checking)<!-- -->.

## Example

Relative path will be resolved relative to the project root directory.

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    tsconfigPath: './tsconfig.build.json',
  },
})
```



---
url: /api/rspeedy/rspeedy.config.splitchunks.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md)

## Config.splitChunks property

Configure chunk splitting.

**Signature:**

```typescript
splitChunks?: RsbuildConfig['splitChunks'] | undefined;
```

## Default Value

Rspeedy defaults this to `false`<!-- -->; if configured, Rsbuild handles it with its top-level `splitChunks` option.

See [Rsbuild - splitChunks](https://rsbuild.rs/config/split-chunks) for details.



---
url: /api/rspeedy/rspeedy.tools.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md)

## Tools interface

The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
export interface Tools 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[bundlerChain?](/api/rspeedy/rspeedy.tools.bundlerchain.md)

</td><td>

</td><td>

ToolsConfig\['bundlerChain'] | undefined

</td><td>

_(Optional)_ The [Tools.bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md) changes the options of [Rspack](https://rspack.rs) using [rspack-chain](https://github.com/rspack-contrib/rspack-chain)<!-- -->.

</td></tr>
<tr><td>

[cssExtract?](/api/rspeedy/rspeedy.tools.cssextract.md)

</td><td>

</td><td>

[CssExtract](/api/rspeedy/rspeedy.cssextract.md) | undefined

</td><td>

_(Optional)_ The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin)

</td></tr>
<tr><td>

[cssLoader?](/api/rspeedy/rspeedy.tools.cssloader.md)

</td><td>

</td><td>

[CssLoader](/api/rspeedy/rspeedy.cssloader.md) | undefined

</td><td>

_(Optional)_ The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

</td></tr>
<tr><td>

[rsdoctor?](/api/rspeedy/rspeedy.tools.rsdoctor.md)

</td><td>

</td><td>

[RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md) | undefined

</td><td>

_(Optional)_ The [Tools.rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md) controls the options of [Rsdoctor](https://rsdoctor.dev/)<!-- -->.

</td></tr>
<tr><td>

[rspack?](/api/rspeedy/rspeedy.tools.rspack.md)

</td><td>

</td><td>

ToolsConfig\['rspack'] | undefined

</td><td>

_(Optional)_ The [Tools.rspack](/api/rspeedy/rspeedy.tools.rspack.md) controls the options of [Rspack](https://rspack.rs/)<!-- -->.

</td></tr>
<tr><td>

[swc?](/api/rspeedy/rspeedy.tools.swc.md)

</td><td>

</td><td>

ToolsConfig\['swc'] | undefined

</td><td>

_(Optional)_ The [Tools.swc](/api/rspeedy/rspeedy.tools.swc.md) controls the options of [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader)<!-- -->.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.tools.bundlerchain.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md)

## Tools.bundlerChain property

The [Tools.bundlerChain](/api/rspeedy/rspeedy.tools.bundlerchain.md) changes the options of [Rspack](https://rspack.rs) using [rspack-chain](https://github.com/rspack-contrib/rspack-chain)<!-- -->.

**Signature:**

```typescript
bundlerChain?: ToolsConfig['bundlerChain'] | undefined;
```

## Default Value

undefined

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    bundlerChain(chain) {
      chain.resolve.fullySpecified(true)
    },
  },
})
```

See [rspack-chain](https://github.com/rspack-contrib/rspack-chain) for details.



---
url: /api/rspeedy/rspeedy.tools.cssextract.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [cssExtract](/api/rspeedy/rspeedy.tools.cssextract.md)

## Tools.cssExtract property

The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
cssExtract?: CssExtract | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.cssextract.loaderoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md) > [loaderOptions](/api/rspeedy/rspeedy.cssextract.loaderoptions.md)

## CssExtract.loaderOptions property

**Signature:**

```typescript
loaderOptions?: CssExtractRspackLoaderOptions | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md) > [esModule](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md)

## CssExtractRspackLoaderOptions.esModule property

The same as [https://github.com/webpack-contrib/mini-css-extract-plugin#esModule](https://github.com/webpack-contrib/mini-css-extract-plugin#esModule)<!-- -->. By default, `@lynx-js/css-extract-webpack-plugin` generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.

**Signature:**

```typescript
esModule?: boolean | undefined;
```

## Default Value

true

## Example

You can enable a CommonJS syntax using:

```js
import {CssExtractWebpackPlugin} from "@lynx-js/css-extract-webpack-plugin";
export default {
  plugins: [new CssExtractWebpackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: CssExtractWebpackPlugin.loader,
            options: {
              esModule: false,
            },
          },
          "css-loader",
        ],
      },
    ],
  },
};
```



---
url: /api/rspeedy/rspeedy.cssextract.pluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md) > [pluginOptions](/api/rspeedy/rspeedy.cssextract.pluginoptions.md)

## CssExtract.pluginOptions property

**Signature:**

```typescript
pluginOptions?: CssExtractRspackPluginOptions | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) > [ignoreOrder](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md)

## CssExtractRspackPluginOptions.ignoreOrder property

**Signature:**

```typescript
ignoreOrder?: boolean | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) > [pathinfo](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md)

## CssExtractRspackPluginOptions.pathinfo property

**Signature:**

```typescript
pathinfo?: boolean | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.tools.cssloader.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [cssLoader](/api/rspeedy/rspeedy.tools.cssloader.md)

## Tools.cssLoader property

The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

**Signature:**

```typescript
cssLoader?: CssLoader | undefined;
```

## Default Value

Uses defaults derived from `output.cssModules` and `output.sourceMap`<!-- -->, with `importLoaders` set to `1` for CSS files and `2` for Sass/Less files.

## Remarks

The default option is as follow:

```js
const defaultOptions = {
  modules: {
    auto: true,
    namedExport: false,
    exportLocalsConvention: 'camelCase',
    localIdentName: output.cssModules.localIdentName,
  },
  sourceMap: output.sourceMap,
  // importLoaders is `1` when compiling css files, and is `2` when compiling sass/less files
  importLoaders: 1 || 2,
};
```



---
url: /api/rspeedy/rspeedy.cssloader.importloaders.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md) > [importLoaders](/api/rspeedy/rspeedy.cssloader.importloaders.md)

## CssLoader.importLoaders property

The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@imported` resources and CSS modules imports.

**Signature:**

```typescript
importLoaders?: 0 | 1 | 2 | undefined;
```

## Default Value

`1` when compiling CSS files and `2` when compiling Sass or Less files

## Remarks

See [css-loader#import-loaders](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#importloaders) for details.



---
url: /api/rspeedy/rspeedy.cssloader.modules.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md) > [modules](/api/rspeedy/rspeedy.cssloader.modules.md)

## CssLoader.modules property

The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

**Signature:**

```typescript
modules?: boolean | CssLoaderModules | undefined;
```

## Default Value

Enables CSS Modules with automatic `*.module.*` detection, camelCase exports, `namedExport: false`<!-- -->, and `localIdentName` inherited from `output.cssModules.localIdentName`<!-- -->.

## Example 1

Using `false` value to increase performance because we avoid parsing CSS Modules features, it will be useful for developers who use vanilla css or use other technologies.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: false,
    },
  },
})
```

## Example 2

Using `() => true` value to enable CSS Modules for all files.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: () => true,
    },
  },
})
```

## Example 3

Using object value to enable CSS Modules based-on [CssLoaderModules.auto](/api/rspeedy/rspeedy.cssloadermodules.auto.md) option and setup more configurations about CSS Modules.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    cssLoader: {
      modules: {
        namedExport: true,
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.cssloadermodules.auto.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [auto](/api/rspeedy/rspeedy.cssloadermodules.auto.md)

## CssLoaderModules.auto property

The `auto` option allows CSS modules to be automatically enabled based on their filenames.

**Signature:**

```typescript
auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
```

## Default Value

true

## Remarks

Given the various `auto` values, the behavior is described as follows:

- `true`<!-- -->: enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` RegExp.

- `false`<!-- -->: disable CSS modules.

- `RegExp`<!-- -->: enable CSS modules for all files matching the `auto.test(filename)` RegExp.

- `function`<!-- -->: enable CSS modules based on the filter function.

See [css-loader#auto](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#auto) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [exportLocalsConvention](/api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md)

## CssLoaderModules.exportLocalsConvention property

The style of exported class names.

**Signature:**

```typescript
exportLocalsConvention?: CssModuleLocalsConvention | undefined;
```

## Default Value

`'camelCase'`

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.localidentname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [localIdentName](/api/rspeedy/rspeedy.cssloadermodules.localidentname.md)

## CssLoaderModules.localIdentName property

Sets the format of the className generated by CSS Modules after compilation.

**Signature:**

```typescript
localIdentName?: string | undefined;
```

## Default Value

`'[local]-[hash:base64:6]'`

## Remarks

Available placeholders:

- `[local]`<!-- -->: Original class name

- `[hash]`<!-- -->: Hash of the class name

- `[path]`<!-- -->: File path

- `[name]`<!-- -->: File name

- `[ext]`<!-- -->: File extension

See [css-loader#localIdentName](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName) for details.



---
url: /api/rspeedy/rspeedy.cssloadermodules.namedexport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) > [namedExport](/api/rspeedy/rspeedy.cssloadermodules.namedexport.md)

## CssLoaderModules.namedExport property

Enables/disables ES modules named export for locals.

**Signature:**

```typescript
namedExport?: boolean | undefined;
```

## Default Value

false

## Example

- `style.css`

```css
.foo-baz {
  color: red;
}
.bar {
  color: blue;
}
.default {
  color: green;
}
```

- `index.js`

```js
import * as styles from "./styles.css";

// If using `exportLocalsConvention: "as-is"` (default value):
console.log(styles["foo-baz"], styles.bar);

// If using `exportLocalsConvention: "camel-case-only"`:
console.log(styles.fooBaz, styles.bar);

// For the `default` class name
console.log(styles["_default"]);
```



---
url: /api/rspeedy/rspeedy.tools.rsdoctor.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md)

## Tools.rsdoctor property

The [Tools.rsdoctor](/api/rspeedy/rspeedy.tools.rsdoctor.md) controls the options of [Rsdoctor](https://rsdoctor.dev/)<!-- -->.

**Signature:**

```typescript
rsdoctor?: RsdoctorRspackPluginOptions | undefined;
```

## Default Value

undefined

## Remarks

Setting `RSDOCTOR=true` enables Rsdoctor. When it is enabled, Rspeedy merges additional plugin defaults during config normalization.

## Example

- Use the built-in Rsdoctor.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rsdoctor: {
      disableClientServer: true,
    },
  },
})
```

See [Rsdoctor - Configuration](https://rsdoctor.dev/config/options/options) for details.



---
url: /api/rspeedy/rspeedy.tools.rspack.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [rspack](/api/rspeedy/rspeedy.tools.rspack.md)

## Tools.rspack property

The [Tools.rspack](/api/rspeedy/rspeedy.tools.rspack.md) controls the options of [Rspack](https://rspack.rs/)<!-- -->.

**Signature:**

```typescript
rspack?: ToolsConfig['rspack'] | undefined;
```

## Default Value

undefined

## Example 1

- Use object config

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack: {
      resolve: {
        fullySpecified: true,
      },
    },
  },
})
```

See [Rspack - Configuration](https://rspack.rs/config/index) for details.

## Example 2

- Use function with `env` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { env }) {
      if (env === 'development') {
        config.devtool = 'cheap-source-map'
      }
      return config
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.rs/config/tools/rspack#env) for details.

## Example 3

- Use function with `mergeConfig` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { mergeConfig }) {
      return mergeConfig(config, {
        resolve: {
          fullySpecified: true,
        },
      })
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.rs/config/tools/rspack#mergeconfig) for details.

## Example 4

- Use function with `appendPlugins` utils

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  tools: {
    rspack(config, { appendPlugins, rspack }) {
      appendPlugins(new rspack.BannerPlugin({ banner: 'Hello, World!' }))
      return config
    },
  },
})
```

See [Rsbuild - tools.rspack](https://rsbuild.rs/config/tools/rspack#appendplugins) for details.



---
url: /api/rspeedy/rspeedy.tools.swc.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Tools](/api/rspeedy/rspeedy.tools.md) > [swc](/api/rspeedy/rspeedy.tools.swc.md)

## Tools.swc property

The [Tools.swc](/api/rspeedy/rspeedy.tools.swc.md) controls the options of [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader)<!-- -->.

**Signature:**

```typescript
swc?: ToolsConfig['swc'] | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [pluginReactLynx](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

## pluginReactLynx() function

Create a rsbuild plugin for ReactLynx.

**Signature:**

```typescript
export declare function pluginReactLynx(userOptions?: PluginReactLynxOptions): RsbuildPlugin[];
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

userOptions

</td><td>

[PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md)

</td><td>

_(Optional)_

</td></tr>
</tbody></table>

**Returns:**

RsbuildPlugin\[]

## Example

```ts
// rsbuild.config.ts
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'
export default {
  plugins: [pluginReactLynx()]
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [compat](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md)

## PluginReactLynxOptions.compat property

The `compat` option controls compatibilities with ReactLynx2.0.

**Signature:**

```typescript
compat?: Partial<CompatVisitorConfig> & {
        disableCreateSelectorQueryIncompatibleWarning?: boolean;
    } | undefined;
```

## Default Value

`undefined`

## Remarks

These options should only be used for migrating from ReactLynx2.0.



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md)

## CompatVisitorConfig.addComponentElement property

Controls whether to add wrapper elements for components

**Signature:**

```typescript
addComponentElement: boolean | AddComponentElementConfig
```

## Remarks

Default value: `false`

## Example 1

Add a `<view>` wrapper element for all components during runtime.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: true
      },
    })
  ],
})
```

## Example 2

Only add component element during compilation. Note that this only take effects on `Component` imported from [CompatVisitorConfig.oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: { compilerOnly: true }
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md) > [compilerOnly](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md)

## AddComponentElementConfig.compilerOnly property

Whether to only add component element during compilation

**Signature:**

```typescript
compilerOnly: boolean
```

## Example

Note that this only take effects on `Component` imported from [CompatVisitorConfig.oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)<!-- -->.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        addComponentElement: { compilerOnly: true }
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [additionalComponentAttributes](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md)

## CompatVisitorConfig.additionalComponentAttributes property

Specifies additional component attributes list, these attributes will be passed to the wrapped `<view>` instead of the component.

**Signature:**

```typescript
additionalComponentAttributes: Array<string>
```

## Remarks

This only takes effect when [CompatVisitorConfig.addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md) is enabled.

Default value: `[]`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        additionalComponentAttributes: ['custom-attr', 'data-special']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [componentsPkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md)

## CompatVisitorConfig.componentsPkg property

Specifies the list of component package names that need compatibility processing

**Signature:**

```typescript
componentsPkg: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-components']`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        componentsPkg: ['@my-org/components', '@legacy/ui-kit']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [darkMode](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md)

## CompatVisitorConfig.darkMode property

> Warning: This API is now obsolete.
>
> Dark mode configuration

**Signature:**

```typescript
darkMode?: boolean | DarkModeConfig
```

## Remarks

Default value: `None`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        darkMode: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [disableDeprecatedWarning](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md)

## CompatVisitorConfig.disableDeprecatedWarning property

Whether to disable deprecated warnings

**Signature:**

```typescript
disableDeprecatedWarning: boolean
```

## Remarks

Default value: `false`

## Example

Disable all the `DEPRECATED:` warnings.

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        disableDeprecatedWarning: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [newRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md)

## CompatVisitorConfig.newRuntimePkg property

Specifies the new runtime package name

**Signature:**

```typescript
newRuntimePkg: string
```

## Remarks

Default value: `'@lynx-js/react'`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        newRuntimePkg: '@my-org/react'
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)

## CompatVisitorConfig.oldRuntimePkg property

Specifies the list of old runtime package names that need compatibility processing

**Signature:**

```typescript
oldRuntimePkg: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-runtime']`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        oldRuntimePkg: ['@my-org/runtime', '@legacy/runtime']
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [removeComponentAttrRegex](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md)

## CompatVisitorConfig.removeComponentAttrRegex property

> Warning: This API is now obsolete.
>
> It's recommended to use `background-only`<!-- -->.
>
> If your code depends on this switch, when distributing it to other projects through npm packages or other means, you'll also need to enable this switch. This will lead to the proliferation of switches, which is not conducive to code reuse between different projects.

Regular expression used to remove component attributes

**Signature:**

```typescript
removeComponentAttrRegex?: string
```

## Remarks

Default value: `None`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        removeComponentAttrRegex: '^data-test-'
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md) > [simplifyCtorLikeReactLynx2](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md)

## CompatVisitorConfig.simplifyCtorLikeReactLynx2 property

> Warning: This API is now obsolete.
>
> Using `simplifyCtorLikeReactLynx2` is not recommended as it introduces implicit behaviors that can:
>
> - Make code harder to understand and maintain
>
> - Create hidden dependencies between components
>
> - Complicate debugging and testing processes
>
> Instead, use `background-only` on class methods for explicit and maintainable behavior

Whether to simplify constructor calls like ReactLynx 2

**Signature:**

```typescript
simplifyCtorLikeReactLynx2: boolean
```

## Remarks

Default value: `false`

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      compat: {
        simplifyCtorLikeReactLynx2: true
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [customCSSInheritanceList](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)

## PluginReactLynxOptions.customCSSInheritanceList property

When [PluginReactLynxOptions.enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) is enabled, `customCSSInheritanceList` can control which properties are inheritable, not just the default ones.

**Signature:**

```typescript
customCSSInheritanceList?: string[] | undefined;
```

## Default Value

`undefined`

## Example

By setting `customCSSInheritanceList: ['direction', 'overflow']`<!-- -->, only the `direction` and `overflow` properties are inheritable.

```js
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
 plugins: [
   pluginReactLynx({
     enableCSSInheritance: true,
     customCSSInheritanceList: ['direction', 'overflow']
   }),
 ],
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [debugInfoOutside](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md)

## PluginReactLynxOptions.debugInfoOutside property

debugInfoOutside controls whether the debug info is placed outside the template.

**Signature:**

```typescript
debugInfoOutside?: boolean;
```

## Default Value

`true`

## Remarks

This is recommended to be set to true to reduce template size.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [defaultDisplayLinear](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md)

## PluginReactLynxOptions.defaultDisplayLinear property

defaultDisplayLinear controls whether the default value of `display` in CSS is `linear`<!-- -->.

If `defaultDisplayLinear === false`<!-- -->, the default `display` would be `flex` instead of `linear`<!-- -->.

**Signature:**

```typescript
defaultDisplayLinear?: boolean;
```

## Default Value

`true`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [defineDCE](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md)

## PluginReactLynxOptions.defineDCE property

Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

**Signature:**

```typescript
defineDCE?: Partial<DefineDceVisitorConfig> | undefined;
```

## Default Value

`undefined`



---
url: /api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md) > [define](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md)

## DefineDceVisitorConfig.define property

Replaces variables in your code with other values or expressions at compile time.

**Signature:**

```typescript
define: Record<string, string>
```

## Remarks

Caveat: differences between `source.define`

`defineDCE` happens before transforming `background-only` directives. So it's useful for eliminating code that is only used in the background from main-thread.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      defineDCE: {
        define: {
          __FOO__: 'false',
          'process.env.PLATFORM': '"lynx"',
        },
      },
    })
  ],
})
```

Then, `__FOO__` and `process.env.PLATFORM` could be used in source code.

```
if (process.env.PLATFORM === 'lynx') {
  console.log('lynx')
}

function FooOrBar() {
  if (__FOO__) {
    return <text>foo</text>
  } else {
    return <text>bar</text>
  }
}
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableAccessibilityElement](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md)

## PluginReactLynxOptions.enableAccessibilityElement property

enableAccessibilityElement set the default value of `accessibility-element` for all `<view />` elements.

**Signature:**

```typescript
enableAccessibilityElement?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md)

## PluginReactLynxOptions.enableCSSInheritance property

enableCSSInheritance enables the default inheritance properties.

**Signature:**

```typescript
enableCSSInheritance?: boolean;
```

## Default Value

`false`

## Remarks

The following properties are inherited by default:

- `direction`

- `color`

- `font-family`

- `font-size`

- `font-style`

- `font-weight`

- `letter-spacing`

- `line-height`

- `line-spacing`

- `text-align`

- `text-decoration`

- `text-shadow`

It is recommended to use with [PluginReactLynxOptions.customCSSInheritanceList](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md) to avoid performance issues.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSInvalidation](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md)

## PluginReactLynxOptions.enableCSSInvalidation property

CSS Invalidation refers to the process of determining which elements need to have their styles recalculated when the DOM is updated.

**Signature:**

```typescript
enableCSSInvalidation?: boolean;
```

## Default Value

`true`

## Remarks

When using combinator to determine the styles of various elements (including descendants, adjacent siblings, etc.), it is recommended to enable this feature. Otherwise, only the initial class setting can match the corresponding combinator, and subsequent updates will not recalculate the related styles.

We find that collecting invalidation nodes and updating them is a relatively time-consuming process. If there is no such usage and better style matching performance is needed, this feature can be selectively disabled.

## Example

If a descendant selector `.a .b` is defined in a CSS file, then when an element's class changes to `.a`<!-- -->, all nodes in its subtree with the className `.b` need to have their styles recalculated.



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableCSSSelector](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md)

## PluginReactLynxOptions.enableCSSSelector property

enableCSSSelector controls whether enabling the new CSS implementation.

**Signature:**

```typescript
enableCSSSelector?: boolean;
```

## Default Value

`true`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableNewGesture](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md)

## PluginReactLynxOptions.enableNewGesture property

enableNewGesture enables the new gesture system.

**Signature:**

```typescript
enableNewGesture?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableRemoveCSSScope](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md)

## PluginReactLynxOptions.enableRemoveCSSScope property

enableRemoveCSSScope controls whether CSS is restrict to use in the component scope.

`true`<!-- -->: All CSS files are treated as global CSS.

`false`<!-- -->: All CSS files are treated as scoped CSS, and only take effect in the component that explicitly imports it.

`undefined`<!-- -->: Only use scoped CSS for CSS Modules, and treat other CSS files as global CSS. Scoped CSS is faster than global CSS, thus you can use CSS Modules to speedy up your CSS if there are performance issues.

**Signature:**

```typescript
enableRemoveCSSScope?: boolean | undefined;
```

## Default Value

`true`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableSSR](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md)

## PluginReactLynxOptions.enableSSR property

`enableSSR` enable Lynx SSR feature for this build.

**Signature:**

```typescript
enableSSR?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableuisourcemap.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [enableUiSourceMap](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableuisourcemap.md)

## PluginReactLynxOptions.enableUiSourceMap property

Enable UI source map generation and debug-metadata asset emission.

**Signature:**

```typescript
enableUiSourceMap?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)

## PluginReactLynxOptions.engineVersion property

`engineVersion` specifies the minimum Lynx Engine version required for an App bundle to function properly.

**Signature:**

```typescript
engineVersion?: string;
```

## Default Value

`'3.2'`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [experimental\_isLazyBundle](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md)

## PluginReactLynxOptions.experimental\_isLazyBundle property

> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Generate standalone lazy bundle.

**Signature:**

```typescript
experimental_isLazyBundle?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_useelementtemplate.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [experimental\_useElementTemplate](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_useelementtemplate.md)

## PluginReactLynxOptions.experimental\_useElementTemplate property

Enable Element Template compile and runtime entries.

**Signature:**

```typescript
experimental_useElementTemplate?: boolean;
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [extractStr](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md)

## PluginReactLynxOptions.extractStr property

Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

**Signature:**

```typescript
extractStr?: Partial<ExtractStrConfig> | boolean;
```

## Default Value

false



---
url: /api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md) > [strLength](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md)

## ExtractStrConfig.strLength property

The minimum length of string literals to be extracted.

**Signature:**

```typescript
strLength: number
```

## Remarks

Default value: `20`<!-- -->.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      extractStr: {
        strLength: 10,
      },
    })
  ],
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [firstScreenSyncTiming](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md)

## PluginReactLynxOptions.firstScreenSyncTiming property

This flag controls when MainThread (Lepus) transfers control to Background after the first screen

This flag has two options:

`"immediately"`<!-- -->: Transfer immediately

`"jsReady"`<!-- -->: Transfer when background (JS Runtime) is ready

After handing over control, MainThread (Lepus) runtime can no longer respond to data updates, and data updates will be forwarded to background (JS Runtime) and processed \_\_asynchronously\_\_

**Signature:**

```typescript
firstScreenSyncTiming?: 'immediately' | 'jsReady';
```

## Default Value

"immediately"



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [removeDescendantSelectorScope](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md)

## PluginReactLynxOptions.removeDescendantSelectorScope property

removeDescendantSelectorScope is used to remove the scope of descendant selectors.

**Signature:**

```typescript
removeDescendantSelectorScope?: boolean;
```

## Default Value

`true`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [shake](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md)

## PluginReactLynxOptions.shake property

How main-thread code will be shaken.

**Signature:**

```typescript
shake?: Partial<ShakeVisitorConfig> | undefined;
```

## Default Value

`undefined`



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [pkgName](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md)

## ShakeVisitorConfig.pkgName property

Package names to identify runtime imports that need to be processed

**Signature:**

```typescript
pkgName: Array<string>
```

## Remarks

Default value: `['@lynx-js/react-runtime']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        pkgName: ['@lynx-js/react-runtime']
      }
    })
  ]
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [removeCallParams](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md)

## ShakeVisitorConfig.removeCallParams property

Function names whose parameters should be removed during transformation

**Signature:**

```typescript
removeCallParams: Array<string>
```

## Remarks

Default value: `[]` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        removeCallParams: ['useMyCustomEffect']
      }
    })
  ]
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [retainProp](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md)

## ShakeVisitorConfig.retainProp property

Properties that should be retained in the component class

**Signature:**

```typescript
retainProp: Array<string>
```

## Remarks

Default value: `['constructor', 'render', 'getDerivedStateFromProps', 'state', 'defaultDataProcessor', 'dataProcessors', 'contextType', 'defaultProps']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        retainProp: ['myCustomMethod']
      }
    })
  ]
})
```



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [targetSdkVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md)

## PluginReactLynxOptions.targetSdkVersion property

> Warning: This API is now obsolete.
>
> `targetSdkVersion` is now an alias of [PluginReactLynxOptions.engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)<!-- -->. Use [PluginReactLynxOptions.engineVersion](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md) instead.

targetSdkVersion is used to specify the minimal Lynx Engine version that a App bundle can run on.

**Signature:**

```typescript
targetSdkVersion?: string;
```

## Default Value

`'3.2'`



---
url: /api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md)

## CustomizedSchemaFn type

Customize the generated schema.

**Signature:**

```typescript
export type CustomizedSchemaFn = (url: string) => string | Record<string, string>;
```



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [pluginQRCode](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)

## pluginQRCode() function

Create a rsbuild plugin for printing QRCode.

**Signature:**

```typescript
export declare function pluginQRCode(options?: PluginQRCodeOptions): RsbuildPlugin;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

options

</td><td>

[PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md)

</td><td>

_(Optional)_

</td></tr>
</tbody></table>

**Returns:**

RsbuildPlugin

## Example

```ts
// rsbuild.config.ts
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
export default {
  plugins: [pluginQRCode()],
}
```



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md) > [schema](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md)

## PluginQRCodeOptions.schema property

Customize the generated schema.

**Signature:**

```typescript
schema?: CustomizedSchemaFn | undefined;
```

## Example 1

```js
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  plugins: [
    pluginQRCode({
      schema(url) {
        return `lynx://${url}?dev=1`
      },
    }),
  ],
})
```

## Example 2

- Use multiple schemas:

You may press `a` in the terminal to switch between schemas.

```js
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  plugins: [
    pluginQRCode({
      schema(url) {
        return {
          http: url,
          foo: `foo://lynx?url=${encodeURIComponent(url)}&dev=1`,
          bar: `bar://lynx?url=${encodeURIComponent(url)}`,
        }
      },
    }),
  ],
})
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md)

## external-bundle-rsbuild-plugin package

## Functions

<table><thead><tr><th>

Function

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[normalizeBundlePath(bundlePath)](/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md)

</td><td>

Normalize a public bundle path by removing leading slashes.

</td></tr>
<tr><td>

[pluginExternalBundle(options)](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md)

</td><td>

Create a rsbuild plugin for loading external bundles.

This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ExternalsPresetContext](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md)

</td><td>

Context passed to externals preset resolvers.

</td></tr>
<tr><td>

[ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md)

</td><td>

Definition for a named externals preset.

</td></tr>
<tr><td>

[ExternalsPresets](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md)

</td><td>

Presets for external bundle dependencies.

</td></tr>
<tr><td>

[PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md)

</td><td>

Options for the external-bundle-rsbuild-plugin.

</td></tr>
<tr><td>

[PluginExternalValue](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md)

</td><td>

External bundle reference accepted by `pluginExternalBundle`<!-- -->.

</td></tr>
<tr><td>

[ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md)

</td><td>

Options for the built-in `reactlynx` externals preset.

</td></tr>
</tbody></table>

## Variables

<table><thead><tr><th>

Variable

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[builtInExternalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md)

</td><td>

Built-in externals preset definitions.

</td></tr>
</tbody></table>

## Type Aliases

<table><thead><tr><th>

Type Alias

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ExternalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md)

</td><td>

Available externals preset definitions.

</td></tr>
<tr><td>

[PluginExternalConfig](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md)

</td><td>

External bundle shorthand accepted by `pluginExternalBundle`<!-- -->.

When a string is provided, it is treated as `bundlePath` and the plugin will infer: - `libraryName`<!-- -->: the external request key - `background.sectionPath`<!-- -->: the external request key - `mainThread.sectionPath`<!-- -->: `${request}__main-thread`

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [builtInExternalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.builtinexternalspresetdefinitions.md)

## builtInExternalsPresetDefinitions variable

Built-in externals preset definitions.

**Signature:**

```typescript
builtInExternalsPresetDefinitions: ExternalsPresetDefinitions
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetContext](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md)

## ExternalsPresetContext interface

Context passed to externals preset resolvers.

**Signature:**

```typescript
export interface ExternalsPresetContext 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[rootPath](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.rootpath.md)

</td><td>

</td><td>

string

</td><td>

The current Rsbuild project root path.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md)

## ExternalsPresetDefinition interface

Definition for a named externals preset.

**Signature:**

```typescript
export interface ExternalsPresetDefinition 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[extends?](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.extends.md)

</td><td>

</td><td>

string | string\[]

</td><td>

_(Optional)_ Other preset names to apply before the current preset.

</td></tr>
<tr><td>

[resolveExternals?](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolveexternals.md)

</td><td>

</td><td>

(value: boolean | object, context: [ExternalsPresetContext](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md)<!-- -->) => [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md)<!-- -->\['externals']

</td><td>

_(Optional)_ Resolve external request mappings contributed by this preset.

</td></tr>
<tr><td>

[resolveManagedAssets?](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolvemanagedassets.md)

</td><td>

</td><td>

(value: boolean | object, context: [ExternalsPresetContext](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md)<!-- -->) => Map\<string, string> | Record\<string, string>

</td><td>

_(Optional)_ Resolve managed bundle assets contributed by this preset.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md)

## ExternalsPresetDefinitions type

Available externals preset definitions.

**Signature:**

```typescript
export type ExternalsPresetDefinitions = Record<string, ExternalsPresetDefinition>;
```

**References:** [ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md)



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresets](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md)

## ExternalsPresets interface

Presets for external bundle dependencies.

**Signature:**

```typescript
export interface ExternalsPresets 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[reactlynx?](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.reactlynx.md)

</td><td>

</td><td>

boolean | [ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md)

</td><td>

_(Optional)_ Load the ReactLynx runtime bundle and wire its standard module globals.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [normalizeBundlePath](/api/rspeedy/external-bundle-rsbuild-plugin.normalizebundlepath.md)

## normalizeBundlePath() function

Normalize a public bundle path by removing leading slashes.

**Signature:**

```typescript
export declare function normalizeBundlePath(bundlePath: string): string;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

bundlePath

</td><td>

string

</td><td>

</td></tr>
</tbody></table>

**Returns:**

string



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [pluginExternalBundle](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md)

## pluginExternalBundle() function

Create a rsbuild plugin for loading external bundles.

This plugin wraps the externals-loading-webpack-plugin and automatically retrieves layer names from the react-rsbuild-plugin via api.useExposed.

**Signature:**

```typescript
export declare function pluginExternalBundle(options: PluginExternalBundleOptions): RsbuildPlugin;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

options

</td><td>

[PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md)

</td><td>

</td></tr>
</tbody></table>

**Returns:**

RsbuildPlugin

## Example

```ts
// lynx.config.ts
import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default {
  plugins: [
    pluginReactLynx(),
    pluginExternalBundle({
      externals: {
        lodash: {
          bundlePath: 'lodash.lynx.bundle',
          background: { sectionPath: 'background' },
          mainThread: { sectionPath: 'mainThread' },
        },
      },
    }),
  ],
}
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md)

## PluginExternalBundleOptions interface

Options for the external-bundle-rsbuild-plugin.

**Signature:**

```typescript
export interface PluginExternalBundleOptions extends Pick<ExternalsLoadingPluginOptions, 'globalObject' | 'timeout' | 'retries'> 
```

**Extends:** Pick\<[ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md)<!-- -->, 'globalObject' | 'timeout' | 'retries'>

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[externalBundleRoot?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalbundleroot.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Root directory that stores project-owned external bundles referenced by `bundlePath`<!-- -->.

`pluginExternalBundle` uses this directory for both development serving and build-time asset emission. Prefer setting this explicitly when external bundles are built into a separate output folder, such as `dist-external-bundle`<!-- -->.

</td></tr>
<tr><td>

[externals?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externals.md)

</td><td>

</td><td>

Record\<string, [PluginExternalConfig](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md)<!-- -->>

</td><td>

_(Optional)_ Additional explicit externals to load.

</td></tr>
<tr><td>

[externalsPresetDefinitions?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresetdefinitions.md)

</td><td>

</td><td>

[ExternalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinitions.md)

</td><td>

_(Optional)_ Definitions for custom externals presets enabled by `externalsPresets`<!-- -->.

Use this to add business-specific presets such as `lynxUi`<!-- -->, or to extend a built-in preset through `extends`<!-- -->.

</td></tr>
<tr><td>

[externalsPresets?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresets.md)

</td><td>

</td><td>

[ExternalsPresets](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md)

</td><td>

_(Optional)_ Presets for external libraries.

Same as [https://rspack.rs/config/externals\\#externalspresets](https://rspack.rs/config/externals\\#externalspresets) but for Lynx.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalConfig](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalconfig.md)

## PluginExternalConfig type

External bundle shorthand accepted by `pluginExternalBundle`<!-- -->.

When a string is provided, it is treated as `bundlePath` and the plugin will infer: - `libraryName`<!-- -->: the external request key - `background.sectionPath`<!-- -->: the external request key - `mainThread.sectionPath`<!-- -->: `${request}__main-thread`

**Signature:**

```typescript
export type PluginExternalConfig = PluginExternalValue | string;
```

**References:** [PluginExternalValue](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md)



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalValue](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md)

## PluginExternalValue interface

External bundle reference accepted by `pluginExternalBundle`<!-- -->.

**Signature:**

```typescript
export interface PluginExternalValue extends Omit<ExternalValue, 'url'> 
```

**Extends:** Omit\<[ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md)<!-- -->, 'url'>

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[bundlePath?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.bundlepath.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Bundle path resolved against the runtime public path.

Prefer this over `url` when the external bundle should be emitted or served as part of the current project. `pluginExternalBundle` can use this information to manage local bundle files, while the runtime keeps the final URL aligned with the active `publicPath`<!-- -->.

</td></tr>
<tr><td>

[url?](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.url.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Bundle URL.

Use this only when the external bundle lives outside the current build output and should not be emitted or served by `pluginExternalBundle`<!-- -->.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md)

## ReactLynxExternalsPresetOptions interface

Options for the built-in `reactlynx` externals preset.

**Signature:**

```typescript
export interface ReactLynxExternalsPresetOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[bundlePath?](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.bundlepath.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Emit the ReactLynx runtime bundle into the current build output and load it through the generated runtime public path.

Prefer this over `url` for normal Rspeedy projects. In addition to letting the runtime resolve the final URL from `publicPath`<!-- -->, the plugin will also copy the corresponding `@lynx-js/react-umd` bundle into the emitted assets, so application bundles can reference it without requiring an extra manual copy step when publishing.

</td></tr>
<tr><td>

[reactUmdPackageName?](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.reactumdpackagename.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Package name that provides the ReactLynx runtime bundle.

Override this when wrapping the plugin for another distribution, such as `@byted-lynx/react-umd`<!-- -->.

</td></tr>
<tr><td>

[url?](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.url.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Override the runtime bundle URL directly.

Use this only when the ReactLynx runtime is hosted outside the current build output, for example on a CDN. Unlike `bundlePath`<!-- -->, this does not emit any extra asset into the current compilation.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md)

## lynx-bundle-rslib-config package

`@lynx-js/lynx-bundle-rslib-config` is the package that provides the configurations for bundling Lynx bundle with [Rslib](https://rslib.rs/)<!-- -->.

## Classes

<table><thead><tr><th>

Class

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md)

</td><td>

The webpack plugin to build and emit the external bundle.

</td></tr>
<tr><td>

[MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md)

</td><td>

The main-thread runtime wrapper for external bundle.

</td></tr>
</tbody></table>

## Functions

<table><thead><tr><th>

Function

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[defineExternalBundleRslibConfig(userLibConfig, encodeOptions)](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md)

</td><td>

Get the rslib config for building Lynx external bundles.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[EncodeOptions](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md)

</td><td>

The options for encoding the external bundle.

</td></tr>
<tr><td>

[ExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md)

</td><td>

Rslib config shape accepted by `defineExternalBundleRslibConfig`<!-- -->.

</td></tr>
<tr><td>

[ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md)

</td><td>

The options for [ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md)<!-- -->.

</td></tr>
<tr><td>

[ExternalsPresetDefinition](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md)

</td><td>

Definition for a named externals preset.

</td></tr>
<tr><td>

[MainThreadRuntimeWrapperWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md)

</td><td>

The options of [MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md)<!-- -->.

</td></tr>
</tbody></table>

## Variables

<table><thead><tr><th>

Variable

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[builtInExternalsPresetDefinitions](/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md)

</td><td>

Built-in externals preset definitions.

</td></tr>
<tr><td>

[defaultExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md)

</td><td>

The default lib config for external bundle.

</td></tr>
<tr><td>

[reactLynxExternalsPreset](/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md)

</td><td>

Standard ReactLynx external mappings used by the built-in `reactlynx` preset.

</td></tr>
</tbody></table>

## Type Aliases

<table><thead><tr><th>

Type Alias

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[Externals](/api/rspeedy/lynx-bundle-rslib-config.externals.md)

</td><td>

External module to global-name mappings used when building Lynx external bundles.

</td></tr>
<tr><td>

[ExternalsPresetDefinitions](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md)

</td><td>

Available externals preset definitions.

</td></tr>
<tr><td>

[ExternalsPresets](/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md)

</td><td>

Enabled externals presets.

Preset names are resolved from the built-in preset definitions plus any custom definitions passed to [defineExternalBundleRslibConfig()](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md)<!-- -->.

</td></tr>
<tr><td>

[OutputConfig](/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md)

</td><td>

Output config accepted by Lynx external bundle builds.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [builtInExternalsPresetDefinitions](/api/rspeedy/lynx-bundle-rslib-config.builtinexternalspresetdefinitions.md)

## builtInExternalsPresetDefinitions variable

Built-in externals preset definitions.

**Signature:**

```typescript
builtInExternalsPresetDefinitions: ExternalsPresetDefinitions
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [defaultExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.defaultexternalbundlelibconfig.md)

## defaultExternalBundleLibConfig variable

The default lib config for external bundle.

**Signature:**

```typescript
DEFAULT_EXTERNAL_BUNDLE_LIB_CONFIG: LibConfig
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [defineExternalBundleRslibConfig](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md)

## defineExternalBundleRslibConfig() function

Get the rslib config for building Lynx external bundles.

**Signature:**

```typescript
export declare function defineExternalBundleRslibConfig(userLibConfig: ExternalBundleLibConfig, encodeOptions?: EncodeOptions): RslibConfig;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

userLibConfig

</td><td>

[ExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md)

</td><td>

</td></tr>
<tr><td>

encodeOptions

</td><td>

[EncodeOptions](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md)

</td><td>

_(Optional)_

</td></tr>
</tbody></table>

**Returns:**

RslibConfig

## Example 1

If you want to build an external bundle which use in Lynx background thread, you can use the following code:

```js
// rslib.config.js
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'

export default defineExternalBundleRslibConfig({
  id: 'utils-lib',
  source: {
    entry: {
      utils: {
        import: './src/utils.ts',
        layer: 'background',
      }
    }
  }
})
```

Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread.

## Example 2

If you want to build an external bundle which use in Lynx main thread, you can use the following code:

```js
// rslib.config.js
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'

export default defineExternalBundleRslibConfig({
  id: 'utils-lib',
  source: {
    entry: {
      utils: {
        import: './src/utils.ts',
        layer: 'main-thread',
      }
    }
  }
})
```

Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in main-thread.

## Example 3

If you want to build an external bundle which use both in Lynx main thread and background thread. You don't need to set the layer.

```js
// rslib.config.js
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config'

export default defineExternalBundleRslibConfig({
  id: 'utils-lib',
  source: {
    entry: {
      utils: './src/utils.ts',
    },
  }
})
```

Then you can use `lynx.loadScript('utils', { bundleName: 'utils-lib-bundle-url' })` in background thread and `lynx.loadScript('utils__main-thread', { bundleName: 'utils-lib-bundle-url' })` in main-thread.



---
url: /api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [EncodeOptions](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md)

## EncodeOptions interface

The options for encoding the external bundle.

**Signature:**

```typescript
export interface EncodeOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[engineVersion?](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.engineversion.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ The engine version of the external bundle.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md)

## ExternalBundleWebpackPlugin class

The webpack plugin to build and emit the external bundle.

**Signature:**

```typescript
export declare class ExternalBundleWebpackPlugin 
```

## Constructors

<table><thead><tr><th>

Constructor

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[(constructor)(options)](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_.md)

</td><td>

</td><td>

Constructs a new instance of the `ExternalBundleWebpackPlugin` class

</td></tr>
</tbody></table>

## Methods

<table><thead><tr><th>

Method

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[apply(compiler)](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.apply.md)

</td><td>

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md)

## ExternalBundleLibConfig interface

Rslib config shape accepted by `defineExternalBundleRslibConfig`<!-- -->.

**Signature:**

```typescript
export interface ExternalBundleLibConfig extends LibConfig 
```

**Extends:** LibConfig

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[output?](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.output.md)

</td><td>

</td><td>

[OutputConfig](/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md)

</td><td>

_(Optional)_

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md)

## ExternalBundleWebpackPluginOptions interface

The options for [ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md)<!-- -->.

**Signature:**

```typescript
export interface ExternalBundleWebpackPluginOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[bundleFileName](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename.md)

</td><td>

</td><td>

string

</td><td>

The external bundle filename.

</td></tr>
<tr><td>

[encode](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode.md)

</td><td>

</td><td>

(opts: unknown) => Promise\<\{ buffer: Buffer; }>

</td><td>

The encode method which is exported from lynx-tasm package.

</td></tr>
<tr><td>

[engineVersion?](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.engineversion.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The engine version of the external bundle.

</td></tr>
<tr><td>

[mainThreadChunks?](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.mainthreadchunks.md)

</td><td>

</td><td>

string\[] | undefined

</td><td>

_(Optional)_ The main thread chunks of the external bundle.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [Externals](/api/rspeedy/lynx-bundle-rslib-config.externals.md)

## Externals type

External module to global-name mappings used when building Lynx external bundles.

**Signature:**

```typescript
export type Externals = Record<string, string | string[]>;
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalsPresetDefinition](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md)

## ExternalsPresetDefinition interface

Definition for a named externals preset.

**Signature:**

```typescript
export interface ExternalsPresetDefinition 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[extends?](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.extends.md)

</td><td>

</td><td>

string | string\[]

</td><td>

_(Optional)_ Other preset names to include before applying the current preset.

</td></tr>
<tr><td>

[externals?](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.externals.md)

</td><td>

</td><td>

[Externals](/api/rspeedy/lynx-bundle-rslib-config.externals.md)

</td><td>

_(Optional)_ Externals contributed by this preset.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalsPresetDefinitions](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md)

## ExternalsPresetDefinitions type

Available externals preset definitions.

**Signature:**

```typescript
export type ExternalsPresetDefinitions = Record<string, ExternalsPresetDefinition>;
```

**References:** [ExternalsPresetDefinition](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md)



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalspresets.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalsPresets](/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md)

## ExternalsPresets type

Enabled externals presets.

Preset names are resolved from the built-in preset definitions plus any custom definitions passed to [defineExternalBundleRslibConfig()](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md)<!-- -->.

**Signature:**

```typescript
export type ExternalsPresets = {
    reactlynx?: boolean;
} & Record<string, boolean>;
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md)

## MainThreadRuntimeWrapperWebpackPlugin class

The main-thread runtime wrapper for external bundle.

**Signature:**

```typescript
export declare class MainThreadRuntimeWrapperWebpackPlugin 
```

## Constructors

<table><thead><tr><th>

Constructor

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[(constructor)(options)](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_.md)

</td><td>

</td><td>

Constructs a new instance of the `MainThreadRuntimeWrapperWebpackPlugin` class

</td></tr>
</tbody></table>

## Methods

<table><thead><tr><th>

Method

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[apply(compiler)](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply.md)

</td><td>

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [MainThreadRuntimeWrapperWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md)

## MainThreadRuntimeWrapperWebpackPluginOptions interface

The options of [MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md)<!-- -->.

**Signature:**

```typescript
export interface MainThreadRuntimeWrapperWebpackPluginOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[test](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test.md)

</td><td>

</td><td>

BannerPlugin\['options']\['test']

</td><td>

Include all modules that pass test assertion.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.outputconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [OutputConfig](/api/rspeedy/lynx-bundle-rslib-config.outputconfig.md)

## OutputConfig type

Output config accepted by Lynx external bundle builds.

**Signature:**

```typescript
export type OutputConfig = Required<LibConfig>['output'] & {
    externalsPresets?: ExternalsPresets;
    externalsPresetDefinitions?: ExternalsPresetDefinitions;
    externals?: Externals;
    globalObject?: 'lynx' | 'globalThis';
};
```

**References:** [ExternalsPresets](/api/rspeedy/lynx-bundle-rslib-config.externalspresets.md)<!-- -->, [ExternalsPresetDefinitions](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinitions.md)<!-- -->, [Externals](/api/rspeedy/lynx-bundle-rslib-config.externals.md)



---
url: /api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [reactLynxExternalsPreset](/api/rspeedy/lynx-bundle-rslib-config.reactlynxexternalspreset.md)

## reactLynxExternalsPreset variable

Standard ReactLynx external mappings used by the built-in `reactlynx` preset.

**Signature:**

```typescript
reactLynxExternalsPreset: Externals
```



---
url: /api/elements/built-in/view.md
---

# `<view>`

APISummary
A container element similar to HTML's `<div>`. Like `<div>`, `<view>` is a versatile container element that can hold other elements and serves as the foundation for building layouts. All attributes, events, and methods available on `<view>` can be used by other elements.

## Usage

### As a Drawing Container

**This is an example below: view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {7-22}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



### As a Layout Container

**This is an example below: view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {24-56}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



## Attribute

Attributes and their values are used to describe the behavior and appearance of elements.

### `name`

```ts
// DefaultValue undefined
name?: string
```

Used to specify the name of the element, generally for native to operate the corresponding node from the native side through `findViewByName`.

### `id`

```ts
// DefaultValue undefined
id?: string;
```

Used to specify the unique identity of the element, which can be used by the front-end API to find and operate the corresponding node, such as [`invoke`](/api/lynx-api/nodes-ref/nodes-ref-invoke.md).

```ts
id?: string;
```

### `style`

```ts
style?: string;
```

Used to apply inline styles to elements.

### `class`

```ts
class?: string;
```

Used to specify one or more class names for an element, which can be used in CSS to apply styles.

### `className`
 ReactLynx
```ts
className?: string;
```

In ReactLynx, use `className` to set CSS class names, equivalent to [`class`](#class).

### `data-*`

```ts
data-*?: any;
```

Used to specify additional information for the element, which can be obtained in [Event](/api/lynx-api/event/event.md#target).

### `flatten`
 Android
```ts
flatten?: boolean;
```

Only available on Android platform, used to force specific nodes to create corresponding Android Views.

### `exposure-id`

```ts
// DefaultValue: undefined
exposure-id?: string
```

Specify whether the target node needs to listen to [exposure/disexposure events](/guide/interaction/visibility-detection/exposure-ability.md#monitor-exposure-of-the-entire-page).

### `exposure-scene`

```ts
// DefaultValue: undefined
exposure-scene?: string
```

Specify the exposure scene of the target node, and use it together with [`exposure-id`](#exposure-id) to uniquely identify the node that needs to monitor exposure.

### `exposure-ui-margin-*`

```ts
// DefaultValue: '0px'
exposure-ui-margin-top?: string;
exposure-ui-margin-right?: string;
exposure-ui-margin-bottom?: string;
exposure-ui-margin-left?: string;
```

Specify the boundary scaling value of the target node itself in the exposure detection, which affects the viewport intersection judgment of the target node. Each node can have its own boundary scaling value.

:::tip
On both Android and iOS platforms, you need to set [`enable-exposure-ui-margin`](#enable-exposure-ui-margin) for the current node; otherwise, it won't take effect. On the HarmonyOS platform, setting [`enable-exposure-ui-margin`](#enable-exposure-ui-margin) is not required for it to take effect.
:::

### `exposure-screen-margin-*`

```ts
// DefaultValue: '0px'
exposure-screen-margin-top?: string;
exposure-screen-margin-right?: string;
exposure-screen-margin-bottom?: string;
exposure-screen-margin-left?: string;
```

Specify the screen boundary scaling value referenced by the target node in the exposure detection task, which affects the viewport intersection judgment of the target node. Each node can have its own screen boundary scaling value.

:::tip
On both Android and iOS platforms, you need to set [`enable-exposure-ui-margin`](#enable-exposure-ui-margin) for the current node; otherwise, a positive value represents the scaling value of the target node's own boundaries, and a negative value represents the scaling value of the screen boundaries. On the HarmonyOS platform, setting [`enable-exposure-ui-margin`](#enable-exposure-ui-margin) is not required for it to take effect.
:::

### `exposure-area`

```ts
// DefaultValue: '0%'
exposure-area?: string
```

Specify the viewport intersection ratio of the target node that can trigger the exposure event. When it is greater than this ratio, the exposure event is triggered. When it is less than this ratio, the reverse exposure event is triggered. By default, the exposure event is triggered when the target node is exposed.

### `enable-exposure-ui-margin`

```ts
// DefaultValue: false
enable-exposure-ui-margin?: boolean
```

Specify whether the target node supports the [`exposure-ui-margin-*`](#exposure-ui-margin-) properties.

:::tip
Setting this to `true` will change the behavior of `exposure-screen-margin-*` on Android and iOS platforms, potentially causing lazy loading of scrollable containers to fail.
:::

### `enable-exposure-ui-clip`

```ts
// DefaultValue: false
enable-exposure-ui-clip?: boolean
```

Specify whether the exposure detection task takes into account the viewport clipping of the parent node. When set to `true`, nodes outside the parent node viewport cannot trigger exposure, and when set to `false`, nodes outside the parent node viewport can trigger exposure.

:::tip
By default, exposure detection only considers the viewport clipping of scrollable parent nodes. The viewport clipping of other parent nodes with width and height and `overflow: visible` has no effect on exposure detection. Setting `enable-exposure-ui-clip` for these parent nodes allows for more accurate viewport clipping determination.
:::

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/enable-exposure-ui-clip-en.png)
### `accessibility-element`

```ts
// DefaultValue: image and text nodes are true by default, and other nodes are false by default
accessibility-element?: boolean
```

Set whether the node supports accessibility.

### `accessibility-label`

```ts
// DefaultValue: undefined
accessibility-label?: string
```

Set the content of the node voice broadcast.

If the `<text/>` node does not set this attribute, the `<text/>` node defaults to the `<text/>` content.

When a node turns on the `accessibility-element` attribute, it is recommended to set the `accessibility-label` at the same time, so that the meaning of the current node can be more clearly expressed.

### `accessibility-trait`

```ts
// DefaultValue: "none"
accessibility-traits?: "none" | "button" | "image" | "text"
```

Set the type characteristics of the node. The system will have specific supplements to the playback content for different types of nodes.

### `accessibility-elements`

```ts
// DefaultValue: undefined
accessibility-elements?: string
```

Customize the focus order of child nodes. This property is set on the parent node, and the focus order of its child nodes will be focused according to the order of the child node `id` specified by the `accessibility-elements` property.

If the parent node is set with the `accessibility-elements` property, only the child node with the `id` specified by the `accessibility-elements` property can be accessed, and other child nodes cannot be focused.

```tsx
<view
  style={{
    width: '100%',
    height: '250px',
    marginTop: '20px',
    display: 'linear',
    backgroundColor: 'grey',
  }}
  accessibility-elements="view-3,view-2,view-5,view-1,view-4"
>
  {[1, 2, 3, 4, 5].map((value) => {
    return (
      <view
        style={`height: 40px; margin: 5px; background-color: white;`}
        id={`view-${value}`}
        accessibility-element="true"
        accessibility-label={`view-${value}`}
      >
        <text>text-{value}</text>
      </view>
    );
  })}
</view>
```

### `accessibility-elements-a11y`

```ts
// DefaultValue: undefined
accessibility-elements-a11y?: string
```

The same as `accessibility-elements`, but the corresponding `id` is `a11y-id`.

### `accessibility-elements-hidden`

```ts
// DefaultValue: false
accessibility-elements-hidden?: boolean
```

Marks the current node and all its child nodes as non-accessible nodes.

### `accessibility-exclusive-focus`

```ts
// DefaultValue: false
accessibility-exclusive-focus?: boolean
```

This property can be set for any node. In accessibility mode, sequential navigation will only focus on the child nodes under these nodes.

:::tip
Usage scenario: Solve the problem of focus penetration in the pop-up mask: You can set this property to true for the mask node, so that the focus circulates inside the mask node and does not penetrate to other nodes under the mask.

```tsx
<view
  accessibility-element={false}
  style={{
    flexDirection: 'column',
    backgroundColor: backgroundColor,
    opacity: opacity,
    height: '200px',
  }}
>
  <view
    accessibility-element={false}
    accessibility-exclusive-focus={true}
    style={{
      flexDirection: 'column',
      backgroundColor: 'grey',
      opacity: 0.6,
      position: 'absolute',
      alignItems: 'center',
      width: '100%',
      top: '20px',
    }}
  >
    This node has accessibility-exclusive-focus set to true, so only the three
    text nodes inside it will be focused.
    <text style={{ fontSize: '20px' }}>overlap text 1</text>
    <text style={{ fontSize: '20px' }}>overlap text 2</text>
    <text style={{ fontSize: '20px' }}>overlap text 3</text>
  </view>
  <text style={{ fontSize: '20px', width: '30%' }}>bottom text 1</text>
  <text style={{ fontSize: '20px', width: '30%' }}>bottom text 2</text>
  <text style={{ fontSize: '20px', width: '30%' }}>bottom text 3</text>
</view>
```

:::

### `a11y-id`

```ts
// DefaultValue: undefined
a11y-id?: string
```

Different from `id`, it is used to identify barrier-free nodes separately.

### `ios-platform-accessibility-id`
 iOS
```ts
// DefaultValue: undefined
ios-platform-accessibility-id?: string
```

Used to specify the accessibility identifier of a `UIView` in iOS. It is only used when the platform-level accessibility framework is accessed.

### `user-interaction-enabled`

```ts
// DefaultValue: true
user-interaction-enabled?: boolean
```

Specify whether the target node and its child nodes can respond to Lynx touch events. This property does not affect platform-level gestures (such as scrolling of `scroll-view`).

:::tip
It is recommended to use [`pointer-events`](/api/css/properties/pointer-events.md) instead of `user-interaction-enabled`.
:::

### `native-interaction-enabled`

```ts
// DefaultValue: true for iOS and Harmony, false for Android
native-interaction-enabled?: boolean
```

Specify whether the target node consumes platform-layer touch events, affects platform-layer gestures (such as scrolling of `scroll-view`), does not affect Lynx touch events, and can achieve similar platform-layer gesture penetration/interception effects.

:::tip
On the Android platform, this setting only applies to `view` elements, and the corresponding Android View needs to be created for the node to take effect. It may also require setting [`flatten`](#flatten) to `false` for it to work.

Gesture interception effects only apply to sibling nodes, not parent-child nodes.
:::

### `pan-intercept-direction`

```ts
// DefaultValue: 2 /* none */
pan-intercept-direction?:
[ 0 /* horizontal */
| 1 /* vertical */
| 2 /* none */ ]
```

Specify which direction to block platform-layer swipe gestures, you need to use [`pan-intercept-scope`](#pan-intercept-scope). When the swipe direction matches `pan-intercept-direction`, [`pan-intercept-scope`](#pan-intercept-scope) will be used to determine whether to block platform-layer swipe gestures on the corresponding node.

For example, when `pan-intercept-direction` is set to `0`, indicating a horizontal swipe direction, the [`pan-intercept-scope`](#pan-intercept-scope) of the node closest to the user in the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain) will be used to determine whether to block platform-layer swipe gestures on the corresponding node.

:::tip
On the Android platform, this setting only applies to `view`, `scroll-view`, and `list` elements, and the corresponding Android View needs to be created for the node to take effect. It may also require setting [`flatten`](#flatten) to `false` for it to work.
:::

### `pan-intercept-scope`

```ts
// DefaultValue: 6 /* none */
pan-intercept-scope?:
[ 0 /* self */
| 1 /* ancestors */
| 2 /* descendants */
| 3 /* self-and-ancestors */
| 4 /* self-and-descendants */
| 5 /* all */
| 6 /* none */ ]
```

Specify the scope within which platform-layer swipe gestures in a particular direction will be blocked. It must be used in conjunction with [`pan-intercept-direction`](#pan-intercept-direction). For example, setting `pan-intercept-scope` to `0` means that platform-layer swipe gestures will only be blocked on the target node, while setting it to `1` means that platform-layer swipe gestures will be blocked on all ancestor nodes of the target node.

### `block-native-event`

```ts
// DefaultValue: false
block-native-event?: boolean
```

Specify whether to block platform layer gestures outside Lynx when the target node is on the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain), which can achieve an effect similar to blocking the platform layer side sliding back.

### `block-native-event-areas`

```ts
// DefaultValue: []
block-native-event-areas?: [string, string, string, string][]
```

Specify a touch area that blocks platform-layer gestures outside of Lynx. When the target node is in the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain) and a touch is placed in the specified area of ​​the target node, platform-layer gestures will be blocked, achieving an effect similar to preventing platform-layer side-swipe back.

This two-dimensional array contains arrays containing 4 elements. The 4 elements are `x`, `y`, `width`, and `height`, in units of `px` or `%`, representing the position, width, and height of the touch area within the target node.

For example, `[['0px', '0px', '50%', '50%'], ['50%', '50%', '50%', '50%']]` indicates that platform-layer gestures outside of Lynx will be blocked when touches are placed in the upper left and lower right areas of the node.

### `consume-slide-event`

```ts
// DefaultValue: []
consume-slide-event?: [number, number][]
```

Specify the angle range within which all platform-level swipe gestures are blocked. When the target node is in the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain) and the swipe angle is within this range, all platform-level swipe gestures are blocked. However, Lynx touch events continue to function, allowing front-end scrolling containers that consume swipes in the specified direction. However, native scrolling based on platform-level gestures is blocked.

This two-dimensional array contains several 2-element arrays, where the 2 elements are `start` and `end`, representing the start and end angles, respectively. The swipe angle is determined by the finger's press position and the finger's movement position.

For example, `[[-180, -135], [-45, 45], [135, 180]]` indicates that all platform-level swipe gestures are blocked when the swipe direction is horizontal, but they are enabled when the swipe direction is vertical.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/consume_slide_event.jpg)
### `event-through`

```ts
// DefaultValue: false
event-through?: boolean
```

Specify whether Lynx consumes touch events from the platform layer when a touch is on the target node, allowing for effects similar to display-only, non-interactive displays.

This property supports inheritance; that is, if `event-through` is not set for a child node, it inherits the `event-through` value from its parent node. Its active region is affected by [`event-through-active-regions`](#event-through-active-regions). If not set, it defaults to the entire region of the target node.

:::tip
Setting this property to `true` only ensures that Lynx does not consume touch events from the platform layer. However, Lynx's parent node may consume touch events, causing touch-through to fail.
:::

### `event-through-active-regions`

```ts
// DefaultValue: []
event-through-active-regions?: [string, string, string, string][]
```

Specify the effective area for [`event-through`](#event-through).

This two-dimensional array contains several arrays containing `4` elements, where the `4` elements are `x`, `y`, `width`, and `height`, in units of `px` or `%`, representing the position, width, and height of the touch area within the target node.

For example, `[['0px', '0px', '50%', '50%']]` indicates that if the touch is in the upper left area of ​​the node, Lynx will not consume touch events from the platform layer.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/event-through-active-regions.png)
### `enable-touch-pseudo-propagation`

```ts
// DefaultValue: true
enable-touch-pseudo-propagation?: boolean
```

Specify whether the target node supports the `:active` pseudo-class to continue bubbling up on the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain).

### `hit-slop`

```ts
// DefaultValue: '0px' or {top: '0px', left: '0px', right: '0px', bottom: '0px'}
hit-slop?: object | string
```

Specify the touch event response hotspot of the target node, without affecting the platform layer gesture.

For example, `{top: '10px', left: '10px', right: '10px', bottom: '10px'}` or `10px` means the touch hotspot of the node is expanded by `10px`.

:::tip
Other factors with higher priority may cause the hot zone modification to fail, such as the node's view hierarchy ([`z-index`](/api/css/properties/z-index.md), [`translateZ`](/api/css/properties/transform.md), [`fixed`](/api/css/properties/position.md#fixed)) is relatively high, the parent node's [`overflow`](/api/css/properties/overflow.md) is `hidden`, etc.
:::

### `ignore-focus`

```ts
// DefaultValue: false
ignore-focus?: boolean
```

Specify whether to not grab focus when touching the target node. By default, the node grabs focus when clicking on it, which can achieve a similar effect of not closing the keyboard when clicking other areas.

This property supports inheritance, that is, when `ignore-focus` is not set on a child node, it will inherit the `ignore-focus` value of the parent node.

### `ios-enable-simultaneous-touch`
 iOS
```ts
// DefaultValue: false
ios-enable-simultaneous-touch?: boolean
```

Specify whether to force trigger the [`touchend`](#touchend) event when the target node is on the [event response chain](/guide/interaction/event-handling/event-propagation.md#event-response-chain), which can solve the problem that the iOS end does not trigger the [`touchend`](#touchend) event but triggers the [`touchcancel`](#touchcancel) event (the [`touchmove`](#touchmove) event is also not continuous) in some scenarios.

### `__lynx_timing_flag`

```ts
__lynx_timing_flag?: string;
```

Add this flag to the current element to monitor the performance of the [lynx pipeline](/guide/spec.md#lynx-pipeline) it participates in.
When flagged, the lynx engine generates a [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) event once the element completes its final painting phase.
This event can be observed and analyzed by registering a [`PerformanceObserver()`](/api/lynx-api/performance-api/performance-observer/observe.md).For more detailed usage, see the [Marking Lynx Pipeline](/guide/performance/monitor-performance/timing-flag.md).

## Events

The front end can set [event handler property](/guide/interaction/event-handling/event-propagation.md#event-handler-property) on the element to monitor the runtime behavior of the element.

### `touchstart`

```ts
touchstart: TouchEvent;
```

It belongs to [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the finger starts to touch the touch surface.

### `touchmove`

```ts
touchmove: TouchEvent;
```

It belongs to [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the finger moves on the touch surface.

### `touchend`

```ts
touchend: TouchEvent;
```

It belongs to [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the finger leaves the touch surface.

### `touchcancel`

```ts
touchcancel: TouchEvent;
```

It belongs to [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the touch event is interrupted by the system or Lynx external gesture.

### `tap`

```ts
tap: TouchEvent;
```

It belongs to [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the finger clicks on the touch surface.

:::tip
This event and the [`longpress`](#longpress) event are mutually exclusive in event monitoring, that is, if the front-end monitors both events at the same time, the two events will not be triggered at the same time, and [`longpress`](#longpress) takes precedence.
:::

### `longpress`

```ts
longpress: TouchEvent;
```

It belongs to the [touch event](/api/lynx-api/event/touch-event.md), which is triggered when the finger is long pressed on the touch surface, and the time interval between long press triggers is `500 ms`.

### `click`

```ts
click: TouchEvent;
```

This belongs to the [touch event](/api/lynx-api/event/touch-event.md), triggered when a finger clicks on the touch surface.

:::tip
This event differs slightly from the [`tap`](#tap) event, mainly in that the blocking distance threshold for the event is different from that of [target](/api/lynx-api/event/event.md#target). For details, please refer to [click](/api/lynx-api/event/touch-event.md#click).
:::

### `layoutchange`

```ts
layoutchange: LayoutChangeDetailEvent;
```

It belongs to [custom event](/api/lynx-api/event/custom-event.md), which is triggered when the target node layout is completed, and returns the position information of the target node relative to the LynxView viewport coordinate system.

### `uiappear`

```ts
uiappear: UIAppearanceDetailEvent;
```

It belongs to [custom event](/api/lynx-api/event/custom-event.md), which is triggered when the target node appears on the screen.

### `uidisappear`

```ts
uidisappear: UIAppearanceDetailEvent;
```

It belongs to [custom event](/api/lynx-api/event/custom-event.md), which is triggered when the target node disappears from the screen.

### `animationstart`

```ts
animationstart: AnimationEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Animation animation starts.

### `animationend`

```ts
animationend: AnimationEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Animation animation ends.

### `animationcancel`

```ts
animationcancel: AnimationEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Animation animation is canceled.

### `animationiteration`

```ts
animationiteration: AnimationEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered every time the Animation animation is executed in a loop.

### `transitionstart`

```ts
transitionstart: TransitionEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Transition animation starts.

### `transitionend`

```ts
transitionend: TransitionEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Transition animation ends.

### `transitioncancel`

```ts
transitioncancel: TransitionEvent;
```

It belongs to [animation event](/api/lynx-api/event/animation-event.md), which is triggered when the Transition animation is canceled.

## Method

The front end can execute the element method through the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `boundingClientRect`

```tsx
lynx
  .createSelectorQuery()
  .select('#box')
  .invoke({
    method: 'boundingClientRect',
    params: {
      iOSEnableAnimationProps: false, // Specify whether to consider animation properties when calculating position on iOS; the default is false.
      androidEnableTransformProps: true, // Specify whether to consider the transform attribute when calculating the position on Android. The default value is false.
      relativeTo: null, // Specify the reference node (select the node via idSelector), which is relative to LynxView by default, but can also be set to "screen" to indicate that it is relative to the screen coordinate system.
    },
    success: function (res) {
      console.log(res);
    },
    fail: function (error) {
      console.log(error);
    },
  })
  .exec();
```

The front end can call this method to obtain the width, height and position information of the target node.

### `takeScreenshot`

```tsx
lynx
  .createSelectorQuery()
  .select('#my-view')
  .invoke({
    method: 'takeScreenshot',
    params: {
      format: 'jpeg', // Specify the image format, supports jpeg and png, the default is jpeg.
      scale: 0.5, // Specify the image quality, 0 < scale <= 1, the default is 1, the smaller the value, the blurrier and smaller the size.
      androidEnablePixelCopy: false, // Specify whether to use PixelCopy to take screenshots on Android, the default is false.
    },
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res.code, res.data);
    },
  })
  .exec();
```

The front end can call this method to obtain the base64 image of the target node.

:::tip
This operation will take up time in the main thread, so you need to pay attention to the calling frequency.

On Android, you must set [`flatten`](#flatten) to `false` on the target node. For SDK versions 3.5 and newer, you can enable screenshots via [PixelCopy](https://developer.android.com/reference/android/view/PixelCopy) by setting the `androidEnablePixelCopy` parameter, which solves the issue of inability to take screenshots in Video/Surface nodes.
:::

### `requestAccessibilityFocus`

```ts
lynx
  .createSelectorQuery()
  .select('#customId')
  .invoke({
    method: 'requestAccessibilityFocus',
    params: {},
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res);
    },
  })
  .exec();
```

The front end can call this method to focus the accessibility focus on a barrier-free element.

## Compatibility

**Compatibility Table**
**Query:** `elements.view`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** view




---
url: /api/elements/built-in/text.md
---

# `<text>`

APISummary
`<text>` is a built-in element in Lynx used to display text content. It supports specifying text style, binding click event callbacks, and can nest `<text>`, [`<image>`](/api/elements/built-in/image.md), and [`<view>`](/api/elements/built-in/view.md) elements to achieve relatively complex text and image content presentation.

## Usage

The `<text>` element has its own layout context similar to the Web's [inline formatting context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_inline_layout/Inline_formatting_context). It does not support `display` properties like `<view>`. For advanced text styling with `<text>` element, see the [Text and Typography guide](/guide/styling/text-and-typography.md).

### Nested `<text>`

Nested `<text>` refers to `<text>` subelements within a `<text>` element.

**This is an example below: text**

**Entry:** `src/inline_text`
**Bundle:** `dist/inline_text.lynx.bundle` | Web: `dist/inline_text.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MyComponent = () => {
  return (
    <view className="fixed_area" data-test-tag="container">
      <view className="test-item">
        <text className="text">Case 1：inline-text Concatenate:</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text>[inline-text 1]</text>
          <text>[inline-text 2]</text>
        </text>
      </view>

      <view className="test-item" style={{ marginTop: "40px" }}>
        <text className="text">Case 2：inline-text: different color</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text style={{ color: "blue" }}>[inline-text 1]</text>
          <text style={{ color: "#62efff" }}>[inline-text 2]</text>
        </text>
        <text className="expection">
          <text>inline-text gradient-color:</text>
          <text style={{ color: "blue" }}>[inline-text 1]</text>
          <text
            style={{
              color: "linear-gradient(to right, red, #65499c, #62efff)",
            }}
          >
            [inline-text 2]
          </text>
        </text>
      </view>

      <view className="test-item" style={{ marginTop: "40px" }}>
        <text className="text">Case 3：inline-text: different style</text>
        <text className="expection">
          <text>simple text scenario:</text>
          <text style={{ fontStyle: "italic" }}>[inline-text 1]</text>
          <text style={{ textDecoration: "line-through" }}>
            [inline-text 2]
          </text>
        </text>
        <text className="expection">simple text scenario</text>
      </view>
    </view>
  );
};
export default MyComponent;
root.render(<MyComponent />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Since the [CSS inheritance is not enabled](/guide/styling/custom-theming.md#leveraging-css-inheritance-as-needed) by default in Lynx, it's recommended to explicitly declare the required styles for `<text>`, as it will not inherit the text-related properties from its parent node.

```tsx
// When CSS inheritance is not enabled, the font-size of the parent node will not be applied to the child <text> node.
<view style={{ fontSize: '20px' }}>
  <text>hello world</text>
</view>
```

However, nested `<text>` is special. Even when CSS inheritance is not enabled, it will still apply `<color>` and `<font-family>` properties of the parent `<text>`. To maintain consistency, it is recommended to explicitly override the properties of the parent `<text>` in the inline `<text>`.

```tsx
<text style={{ color: 'red' }}>
  red
  <text>red</text>
  <text style={{ color: 'blue' }}>blue</text>
</text>
```

### Nested `<image>`

Nested `<image>` refers to `<image>` subelements within a `<text>` element. It can be used for mixed text and image layout.

**This is an example below: text**

**Entry:** `src/inline_image`
**Bundle:** `dist/inline_image.lynx.bundle` | Web: `dist/inline_image.web.bundle`

```tsx
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
export default class Index extends Component {
  render() {
    return (
      <view style={{ width: "200px" }}>
        <text style={{ fontSize: "20px", textAlign: "center" }}>
          <image
            style={{
              width: "20px",
              height: "20px",
              border: "1px solid red",
              borderRadius: "50%",
              verticalAlign: "middle",
            }}
            src={ExclamationCircle}
          />
          <text style={{}}>
            This is a warning message.This is a warning message.This is a warning message.
          </text>
        </text>
      </view>
    );
  }
}
root.render(<Index />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Nested `<view>`

A `<view>` written inside a text element will have inline characteristics and participate in text layout. It also supports all functionalities of the `<view>` tag, including adding borders, rounded corners, and any other element content inside it.

**This is an example below: text**

**Entry:** `src/inline_view`
**Bundle:** `dist/inline_view.lynx.bundle` | Web: `dist/inline_view.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";
import "./index.scss";

const InlineView = () => {
  return (
    <view
      style="flex-direction:column;align-items:center;border:1px red solid;"
      lynx-test-tag="container"
    >
      <text
        style="text-align:center;font-size:25px;text-overflow:ellipsis;"
        text-maxline="2"
      >
        <view
          style={{ flexDirection: "column", verticalAlign: "center" }}
          className="container"
          clip-radius="true"
        >
          <view className="title-name-wrapper-border">
            <view className="title-name-wrapper-border-before"></view>
            <view className="title-name-wrapper-border-after"></view>
          </view>
        </view>
        This is a paragraph containing animation.This is a paragraph containing animation.
      </text>
    </view>
  );
};

export default InlineView;
root.render(<InlineView />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### `<inline-truncation>`

`<inline-truncation>` tag is used to customize the content that needs to be displayed at the end of the text when truncation occurs.

**This is an example below: text**

**Entry:** `src/inline_truncation`
**Bundle:** `dist/inline_truncation.lynx.bundle` | Web: `dist/inline_truncation.web.bundle`

```tsx
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";
import RightArrow from "@assets/image/rightarrow.png?inline";
import { root } from "@lynx-js/react";

const InlineTruncation = () => {
  return (
    <view style={{ width: "200px" }}>
      <text style={{ height: "30px", lineHeight: "20px" }} text-maxline="1">
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text>...See More</text>
          <image src={RightArrow} style={{ width: "10px", height: "10px" }} />
        </inline-truncation>
      </text>

      <text
        style={{ lineHeight: "20px", marginTop: "30px" }}
        text-maxline={"2"}
      >
        this is a test text. this is a test text. this is a test text.this is a test text. this is a test text. this is
        a test text.
        <inline-truncation>
          <text style={{ color: "grey" }}>...See More</text>
          <view style={{ verticalAlign: "center" }} flatten={false}>
            <image
              src={ExclamationCircle}
              style={{ width: "15px", height: "15px" }}
            />
          </view>
        </inline-truncation>
      </text>
    </view>
  );
};

export default InlineTruncation;
root.render(<InlineTruncation />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### RTL

The `text` element supports RTL (Right-To-Left) language layout display. By default, the `text` element will determine the text language based on the content and use the corresponding layout method. Developers can also specify the use of RTL layout by setting the `direction` style.

:::tip

When `direction` is set to `rtl` or `lynx-rtl`, `text-align:start` will be converted to `text-align:right`, and similarly, `text-align:end` will be converted to `text-align:left`.
When `direction` is set to `lynx-rtl`, `text-align:left` will be converted to `text-align:right`, and similarly, `text-align:right` will be converted to `text-align:left`.

:::

**This is an example below: text**

**Entry:** `src/text_style`
**Bundle:** `dist/text_style.lynx.bundle` | Web: `dist/text_style.web.bundle`

```tsx {303-356}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import "./index.scss";
import ExclamationCircle from "@assets/image/exclamationcircle.png?inline";

const AlignContent = () => {
  const examples = [
    { type: "text-overflow" },
    { type: "text-vertical-align" },
    { type: "text-decoration" },
    { type: "text-shadow" },
    { type: "text-direction-rtl" },
  ];

  const TextOverflowExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            fontSize: "20px",
          }}
        >
          text overflow:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text className="item clip" text-maxline="1">
            Hello World Hello World Hello World
          </text>
          <text className="item ellipsis" text-maxline="1">
            Hello World Hello World Hello World
          </text>
        </view>
      </view>
    );
  };

  const TextVerticalAlignExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text vertical align:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "tomato",
              lineHeight: "50px",
            }}
            text-maxline="1"
          >
            <text
              style={{
                verticalAlign: "middle" as const,
              }}
            >
              middle
            </text>
            <text
              style={{
                verticalAlign: "center" as const,
              }}
            >
              center
            </text>
            <text
              style={{
                verticalAlign: "top" as const,
              }}
            >
              top
            </text>
            <text
              style={{
                verticalAlign: "bottom" as const,
              }}
            >
              bottom
            </text>
            <text
              style={{
                verticalAlign: "text-top" as const,
              }}
            >
              text-top
            </text>
            <text
              style={{
                verticalAlign: "baseline" as const,
              }}
            >
              baseline
            </text>
          </text>
          <text
            style={{
              marginTop: "10px",
              backgroundColor: "orange",
              lineHeight: "50px",
            }}
            text-maxline="1"
          >
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "middle" as const,
              }}
            >
              <text>middle</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "center" as const,
              }}
            >
              <text>center</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "top" as const,
              }}
            >
              <text>top</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "bottom" as const,
              }}
            >
              <text>bottom</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "texttop" as const,
              }}
            >
              <text>text-top</text>
            </view>
            <view
              className="bg-yellow"
              style={{
                verticalAlign: "baseline" as const,
              }}
            >
              <text>baseline</text>
            </view>
          </text>
        </view>
      </view>
    );
  };

  const TextDecorationExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text decoration:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "#ccc",
              marginTop: "10px",
            }}
          >
            text-decoration
          </text>
          <text
            style={{
              textDecoration: "none" as const,
            }}
          >
            none
          </text>
          <text
            style={{
              textDecoration: "underline" as const,
            }}
          >
            underline
          </text>
          <text
            style={{
              textDecoration: "line-through" as const,
            }}
          >
            line-through
          </text>
          <text
            style={{
              textDecoration: "underline line-through red solid" as const,
            }}
          >
            red solid
          </text>
          <text
            style={{
              textDecoration: "underline line-through green dotted" as const,
            }}
          >
            green dotted
          </text>
          <text
            style={{
              textDecoration: "underline line-through blue dashed" as const,
            }}
          >
            blue dashed
          </text>
        </view>
      </view>
    );
  };

  const TextShadowExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text shadow:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              backgroundColor: "#ccc",
              marginTop: "10px",
            }}
          >
            Text Shadow Properties
          </text>
          <text
            style={{
              textShadow: "none" as const,
            }}
          >
            text-shadow: none;
          </text>
          <text
            style={{
              textShadow: "1px 1px 2px #558abb" as const,
            }}
          >
            text-shadow: 1px 1px 2px #558abb;
          </text>
          <text
            style={{
              textShadow: "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue" as const,
            }}
          >
            text-shadow: 1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue;
          </text>
          <text
            style={{
              textShadow: "0 .005px .01rem rgba(70, 70, 70, .3)" as const,
            }}
          >
            text-shadow: 0 .005px .01rem rgba(70, 70, 70, .3);
          </text>
        </view>
      </view>
    );
  };

  const TextDirectionRtlExample = () => {
    return (
      <view className="fixed_area">
        <text
          style={{
            marginTop: "20px",
            fontSize: "20px",
          }}
        >
          text direction rtl:
        </text>
        <view
          style={{
            width: "100%",
            flexDirection: "column" as const,
          }}
        >
          <text
            style={{
              direction: "rtl" as const,
            }}
          >
            لإعادة الشحن على دون دفع رسوم الخدمة داخل
            <image
              src={ExclamationCircle}
              style={{
                width: "22px",
                height: "22px",
              }}
            />
            رسوم الخدمة داخل
            <view
              style={{
                padding: "10px",
                border: "1px solid red",
                borderRadius: "20px",
              }}
            >
              <text
                style={{
                  fontSize: "30px",
                  color: "linear-gradient(green, yellow)",
                }}
              >
                {" "}
                sub text{" "}
              </text>
            </view>
            الشحن على دون دفع
          </text>
        </view>
      </view>
    );
  };

  const renderExample = (type: string) => {
    switch (type) {
      case "text-overflow":
        return <TextOverflowExample />;
      case "text-vertical-align":
        return <TextVerticalAlignExample />;
      case "text-decoration":
        return <TextDecorationExample />;
      case "text-shadow":
        return <TextShadowExample />;
      case "text-direction-rtl":
        return <TextDirectionRtlExample />;
      default:
        return null;
    }
  };

  return (
    <scroll-view
      scroll-orientation="vertical"
      style={{
        padding: "5px",
        width: "100%",
        height: "100%",
      }}
    >
      {examples.map((example, index) => renderExample(example.type))}
    </scroll-view>
  );
};

export default AlignContent;

root.render(<AlignContent />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

Attribute names and values are used to describe the behavior and appearance of elements.

### `text-maxline`

```tsx
// DefaultValue: '-1'
text-maxline?: number;
```

Limits the maximum number of lines displayed for the text content, `overflow:hidden` should be set simultaneously.

### `include-font-padding`
 Android
```tsx
// DefaultValue: false
include-font-padding?: boolean;
```

Add additional padding for Android text on top and bottom. Enabling this may cause inconsistencies between platforms.

### `tail-color-convert`

```tsx
// DefaultValue: false
tail-color-convert?: boolean;
```

By default, if the text is truncated, the inserted `...` will be displayed with the color specified by the closest inline-text's style. If this attribute is enabled, the color of `...` will be specified by the outermost `text` tag's style.

### `text-single-line-vertical-align`

```tsx
// DefaultValue: 'normal'
text-single-line-vertical-align?: 'normal' | 'top' | 'center' | 'bottom';
```

Used to set vertical alignment for single-line plain text. It can be changed by setting 'top' | 'center' | 'bottom'. It is recommended to use this only when the default font does not meet the center alignment requirements, as it increases text measurement time.

### `text-selection`

```tsx

// DefaultValue: false
text-selection?: boolean;

```

Sets whether to enable text selection. When enabled, `flatten={false}` should be set simultaneously.

### `custom-context-menu`

```tsx

// DefaultValue: false
custom-context-menu?: boolean;

```

Used to set whether to turn on the custom pop-up context menu after selection and copying. It takes effect after enabling `text-selection`.

### `custom-text-selection`

```tsx

// DefaultValue: false
custom-text-selection?: boolean;

```

Used to set whether to enable the custom text selection function. When it is enabled, the element will no longer handle the gesture logic related to selection and copying. Developers need to control it through APIs such as `setTextSelection`. It takes effect after enabling `text-selection`.

## Events

Frontend can bind corresponding event callbacks to elements to listen to runtime behaviors. All [basic events](/api/elements/built-in/view.md#events) are supported.

### `layout`

```ts
bindlayout = (e: layoutEvent) => {};

interface LineInfo {
  /**
   * The starting character offset of this line relative to the entire text
   */
  start: number;
  /**
   * The ending character offset of this line relative to the entire text
   */
  end: number;
  /**
   * The number of characters truncated in this line. A non-zero value indicates truncation occurred on this line.
   */
  ellipsisCount: number;
}

interface layoutEvent extends CustomEvent {
  detail: {
    /**
     * Number of visible text lines after layout.
     */
    lineCount: number;
    /**
     * Detailed information of each line after layout.
     */
    lines: LineInfo[];
    /**
     * Dimensions of the text element.
     */
    size: { width: number; height: number };
  };
}
```

The layout event returns the result information after text layout, including the number of lines of the current text, and the start and end positions of the text in each line relative to the entire text.

### `selectionchange`

```ts
bindselectionchange = (e: selectionChangeEvent) => {};

interface selectionChangeEvent extends CustomEvent {
  detail: {
    /**
     * The start index of the selected text. Value is -1 when no text is selected.
     */
    start;
    /**
     * The end index of the selected text. Value is -1 when no text is selected.
     */
    end;
    /**
     * Selection direction: `forward` or `backward`
     */
    direction;
  };
}
```

This event is triggered whenever the selected text range changes.

## Methods

You can invoke element methods from the frontend using the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `setTextSelection`

```ts
<text id="test" text-selection={true} flatten={false}></text>

lynx.createSelectorQuery()
  .select('#test')
  .invoke({
    method: "setTextSelection",
    params: {
      startX,  // X-coordinate of the selection start relative to the element
      startY,  // Y-coordinate of the selection start
      endX,    // X-coordinate of the selection end
      endY,    // Y-coordinate of the selection end
      showStartHandle, // Whether to show the start selection handle
      showEndHandle,   // Whether to show the end selection handle
    },
    success: function (res) {
      console.log(res);
    },
    fail: function (error) {
      console.log(error);
    },
}).exec();
```

This method sets the selected text based on start and end positions and controls the visibility of selection handles. The response `res` contains:

```ts
interface Rect {
  left: number;    // Left boundary
  right: number;   // Right boundary
  top: number;     // Top boundary
  bottom: number;  // Bottom boundary
  width: number;   // Width
  height: number;  // Height
}

interface Handle {
  x: number;       // Center X of handle
  y: number;       // Center Y of handle
  radius: number;  // Touch radius of the handle
}

{
  /**
   * Bounding box of the selected text
   */
  boundingRect: Rect;
  /**
   * Bounding boxes for each line within the selection
   */
  boxes: Rect[];
  /**
   * Position and touch radius for each handle
   */
  handles: Handle[];
}
```

### `getTextBoundingRect`

```ts
<text id="test"></text>

lynx.createSelectorQuery()
  .select('#test')
  .invoke({
    method: "getTextBoundingRect",
    params: {
      start,
      end,
    },
    success: function (res) {
      console.log(res);
    },
    fail: function (error) {
      console.log(error);
    },
}).exec();
```

This method retrieves the bounding box of a specific range of text. The response `res` includes:

```ts
{
  /**
   * Bounding box of the selected text
   */
  boundingRect: Rect;
  /**
   * Bounding boxes for each line in the selected range
   */
  boxes: Rect[];
}
```

### `getSelectedText`

```ts
<text id="test" text-selection={true} flatten={false}></text>

lynx.createSelectorQuery()
  .select('#test')
  .invoke({
    method: "getSelectedText",
    params: {},
    success: function (res) {
      console.log(res);
    },
    fail: function (error) {
      console.log(error);
    },
}).exec();
```

This method retrieves the string content of the currently selected text.

## Loading Custom Fonts

You can specify custom font resources using [`@font-face`](/api/css/at-rule/font-face.md) and utilize them with the [`font-family`](/api/css/properties/font-family.md) property.
The client needs to implement the corresponding font resource loader using [`GenericResourceFetcher`](/api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md) to download web font resources.

iOSAndroidHarmonyOS```objective-c
@interface ExampleGenericResourceFetcher : NSObject <LynxGenericResourceFetcher>

- (void)fetchResource:(LynxResourceRequest *)request
           onComplete:(LynxGenericResourceCompletionBlock)callback;

@end
```
```objective-c
@implementation ExampleGenericResourceFetcher

NSURL *url = [NSURL URLWithString:request.url];
NSURLRequest *urlRequest = [NSURLRequest requestWithURL:url
                                             cachePolicy:NSURLRequestReloadIgnoringCacheData
                                         timeoutInterval:5];

[NSURLConnection sendAsynchronousRequest:urlRequest
                                   queue:[NSOperationQueue mainQueue]
                       completionHandler:^(NSURLResponse * _Nullable response,
                                           NSData * _Nullable data,
                                           NSError * _Nullable connectionError) {
    if (!connectionError) {
        // Notify font data
        callback(data, nil);
    } else {
        callback(data, connectionError);
    }
}];
@end

// Register when constructing LynxView.
LynxViewBuilder.genericResourceFetcher = [[ExampleGenericResourceFetcher alloc] init];
```
```java
public class ExampleGenericResourceFetcher extends LynxGenericResourceFetcher {
  @Override
  public void fetchResource(LynxResourceRequest request, LynxResourceCallback<byte[]> callback) {
    ...
      // download font file through http
      byte[] data = new byte[(int) file.length()];

      // notify the font data if success
      callback.onResponse(LynxResourceResponse.onSuccess(data));

    ...
  }
}

// Register when constructing LynxView.
LynxViewBuilder.setGenericResourceFetcher(new ExampleGenericResourceFetcher(context));
```
```typescript
import {
  LynxError,
  LynxSubErrorCode,
  LynxGenericResourceFetcher,
  LynxResourceRequest,
  LynxResourceType,
} from '@lynx/lynx';

export class ExampleGenericResourceFetcher extends LynxGenericResourceFetcher {
  fetchResource(
    request: LynxResourceRequest,
    callback: AsyncCallback<ArrayBuffer, void>,
  ): void {
    // download font file through http
    let data: http.HttpResponse;
    // notify the font data if success
    callback.onResponse(LynxResourceResponse.onSuccess(data));
  }
}
```
## 


## Big Font

Clients can use font scaling related APIs to modify the font scaling ratio after users change the system or application font size. This will also trigger the `onFontScaleChanged` event.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/big-font-flow.png)
### Usage

1. Client-side: Use `LynxViewBuilder.setFontScale()` to set the font scale when creating the LynxView\.Update the font scale with `LynxView.updateFontScale()`.

2. Front-end: `font-size` and `line-height` will zoom in and out according to the font scale.
   The front-end can obtain the updated `fontScale` from the client by listening to the `onFontScaleChanged` event.

The front-end to listen to `onFontScaleChanged`:

```jsx
const YourComponent = () => {
  const [touchCount, setTouchCount] = useState(0);

  useEffect(() => {
    const eventEmitter = getJSModule('GlobalEventEmitter');
    const listener = (msg) => {
      console.log('onFontScaleChanged testGlobalEvent:', msg);
      setTouchCount((prevCount) => prevCount + 1);
    };

    eventEmitter.addListener('onFontScaleChanged', listener);

    return () => {
      eventEmitter.removeListener('onFontScaleChanged', listener);
    };
  }, []);

  return (
    <view>
      <text>touch: {touchCount}</text>
    </view>
  );
};
```

## More Features

### `<text>` selection and copying

The `<text>` element supports text selection and copying. You can enable this feature by setting the `text-selection` attribute on the `<text>` element, and make sure to set `flatten={false}` as well:

```tsx
<text text-selection={true} flatten={false}>
  hello world
</text>
```

Long-pressing the text will highlight the selected area and trigger the default context menu, which includes options like "Select All" and "Copy".

::: note
Text selection is currently not supported for RTL (Right-to-Left) mode.
:::

If you want to implement a **custom context menu**, you need to set the `custom-context-menu` attribute and bind the `selectionchange` event along with the `getTextBoundingRect` method to determine the position for rendering your custom menu.

**This is an example below: text**

**Entry:** `src/text_selection`
**Bundle:** `dist/cross_text_selection.lynx.bundle` | Web: `dist/cross_text_selection.web.bundle`

```tsx {26-48,128}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

import "./index.scss";

// TextSelection component for text selection and context menu handling
const TextSelection = () => {
  // State for selected text element ID
  const [selectedId, setSelectedId] = useState("");
  // State for context menu visibility
  const [showContextMenu, setShowContextMenu] = useState(false);
  // State for context menu left offset
  const [contextMenuLeftOffset, setContextMenuLeftOffset] = useState(0);
  // State for context menu top offset
  const [contextMenuTopOffset, setContextMenuTopOffset] = useState(0);

  // Handle query errors
  const handleQueryError = (res: { code: number; data: unknown }) => {
    console.log(res.code, res.data);
  };

  // Handle text selection change
  // TODO(types): support selection change event in `@lynx-js/types`
  const handleSelectionChange = (e: any) => {
    if (e.detail.start === -1) {
      setSelectedId("");
      hiddenContextMenu();
      return;
    }
    const newSelectedId = "#" + e.target.id;
    setSelectedId(newSelectedId);
    lynx.createSelectorQuery()
      .select(newSelectedId)
      .invoke({
        method: "getTextBoundingRect",
        params: { start: e.detail.start, end: e.detail.end },
        success: (res) => {
          showContextMenuAtPosition(
            res.boundingRect.left + res.boundingRect.width / 2 - 50,
            res.boundingRect.top + res.boundingRect.height + 20,
          );
        },
        fail: handleQueryError,
      })
      .exec();
  };

  // Handle copy action
  const handleCopy = () => {
    copyText();
    clearSelection();
  };

  // Copy selected text
  const copyText = () => {
    if (selectedId === "") return;
    lynx.createSelectorQuery()
      .select(selectedId)
      .invoke({
        method: "getSelectedText",
        params: {},
        success: (res) => {
          console.log("getSelectedText:" + JSON.stringify(res));
        },
        fail: handleQueryError,
      })
      .exec();
  };

  // Clear text selection
  const clearSelection = () => {
    if (selectedId === "") return;
    lynx.createSelectorQuery()
      .select(selectedId)
      .invoke({
        method: "setTextSelection",
        params: { startX: -1, startY: -1, endX: -1, endY: -1, showStartHandle: false, showEndHandle: false },
        success(res) {
          console.log("clearTextSelection", res);
        },
        fail: handleQueryError,
      })
      .exec();
    setSelectedId("");
  };

  // Hide context menu
  const hiddenContextMenu = () => {
    if (!showContextMenu) return;
    setShowContextMenu(false);
  };

  // Show context menu at given position
  const showContextMenuAtPosition = (left: number, top: number) => {
    setShowContextMenu(true);
    setContextMenuLeftOffset(left);
    setContextMenuTopOffset(top);
  };

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view
          style={{
            left: contextMenuLeftOffset + "px",
            top: contextMenuTopOffset + "px",
            visibility: showContextMenu ? "visible" : "hidden",
          }}
          className="ContextMenu"
        >
          <text className="ContextMenuText" bindtap={handleCopy}>
            Copy
          </text>
          <text className="ContextMenuText">
            Search
          </text>
        </view>
        <view id="container" style={{ width: "90vw" }} className="Container">
          <text
            id="1"
            className="NormalText"
            text-selection={true}
            custom-context-menu={true}
            flatten={false}
            bindselectionchange={handleSelectionChange}
          >
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
        </view>
      </view>
    </page>
  );
};

export default TextSelection;

root.render(<TextSelection />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### cross `<text>` selection and copying

For more advanced scenarios, such as supporting **cross-node selection** across multiple `<text>` elements, you need to implement custom selection logic.

Step-by-Step: Implementing Cross-Text Selection

1. Enable Custom Text Selection Mode

Set the `custom-text-selection` attribute on each `<text>` element. This disables the built-in selection and gesture handling, allowing you to define your own.

**This is an example below: text**

**Entry:** `src/cross_text_selection`
**Bundle:** `dist/cross_text_selection.lynx.bundle` | Web: `dist/cross_text_selection.web.bundle`

```tsx {270}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useEffect } from "@lynx-js/react";
import type { CommonEvent, SelectorQuery, TouchEvent } from "@lynx-js/types";

import "./index.scss";

/**
 * Metadata for each <text> node: position, dimensions, and selection bounds.
 */
interface TextNodeInfo {
  id: string; // Unique identifier for the DOM node
  left: number; // X-coordinate of node's left edge
  top: number; // Y-coordinate of node's top edge
  width: number; // Width of the node's bounding box
  height: number; // Height of the node's bounding box
  startX: number; // Selected region's start X
  startY: number; // Selected region's start Y
  endX: number; // Selected region's end X
  endY: number; // Selected region's end Y
}

// Global storage for node info and selection handlers
let textsInfo: TextNodeInfo[] = [];
let handlers: Array<{ x: number; y: number; radius: number; startX: number; startY: number }> = [];
let startPosition = { x: 0, y: 0 }; // Initial touch point for selection
let isSelecting = false; // Flag: currently dragging a selection handle

const CrossTextSelection = () => {
  // useEffect hook to run code when the component mounts and unmounts
  useEffect(() => {
    console.log("component did mount");
    getTextNodeRect();
    return () => {
      console.log("component will unmount");
    };
  }, []);

  // Handle long press event to start text selection
  const handleLongPress = (e: CommonEvent) => {
    isSelecting = true;
    startPosition.x = e.detail.x;
    startPosition.y = e.detail.y;
    setSelection(e.detail.x, e.detail.y, e.detail.x, e.detail.y);
  };

  // Handle touch start event to check if the touch is on a handler
  const handleTouchStart = (e: TouchEvent) => {
    if (handlers.length === 0) {
      return;
    }
    const { x, y } = e.detail;
    for (const [index, handler] of handlers.entries()) {
      if (Math.pow(handler.x - x, 2) + Math.pow(handler.y - y, 2) < Math.pow(handler.radius, 2)) {
        isSelecting = true;
        const another = handlers[(index + 1) % 2];
        startPosition = { x: another.startX, y: another.startY };
        break;
      }
    }
  };

  // Handle touch move event to update the selection area
  const handleTouchMove = (e: TouchEvent) => {
    if (isSelecting) {
      setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
    }
  };

  // Handle touch end event to finalize the selection
  const handleTouchEnd = (e: TouchEvent) => {
    if (isSelecting) {
      setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
    }
    isSelecting = false;
  };

  // Handle tap event to clear the selection
  const handleTap = () => {
    if (handlers.length === 0) {
      return;
    }
    setSelection(-1, -1, -1, -1);
  };

  // Asynchronous function to get the bounding rectangles of text nodes
  async function getTextNodeRect() {
    let resArray = await new Promise<SelectorQuery[]>((resolve) => {
      lynx.createSelectorQuery()
        .selectAll("#container text")
        .fields(
          {
            query: true,
            id: true,
          },
          (result) => resolve(result.map(({ query }) => query)),
        )
        .exec();
    });

    Promise.all(
      resArray.map((selectorQuery) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve, reject) => {
          selectorQuery.selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: resolve,
              fail: reject,
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = values.map(({ top, left, width, height, id }) => ({
        id,
        left,
        top,
        width,
        height,
        startX: -1,
        startY: 0,
        endX: width,
        endY: height,
      }));
    });
  }

  // Function to execute text selection on a specific node
  function execSelection(
    node: TextNodeInfo,
    startX: number,
    startY: number,
    endX: number,
    endY: number,
    showStartHandle = true,
    showEndHandle = true,
  ) {
    lynx
      .createSelectorQuery()
      .select(`#${node.id}`)
      .invoke({
        method: "setTextSelection",
        params: {
          startX,
          startY,
          endX,
          endY,
          showStartHandle,
          showEndHandle,
        },
        success(res) {
          if (!res) {
            return;
          }
          const boxes = res.boxes || [];
          const hs = res.handles || [];
          if (Array.isArray(boxes) && boxes.length > 0) {
            node.startX = boxes[0].left;
            node.startY = boxes[0].top + boxes[0].height / 2;
            node.endX = boxes[boxes.length - 1].left + boxes[boxes.length - 1].width;
            node.endY = boxes[boxes.length - 1].top + boxes[boxes.length - 1].height / 2;
          } else {
            node.startX =
              node.startY =
              node.endX =
              node.endY =
                -1;
          }
          showStartHandle && (handlers[0] = { ...hs[0], startX: node.startX, startY: node.startY });
          showEndHandle && (handlers[1] = { ...hs[1], startX: node.endX, startY: node.endY });
        },
      })
      .exec();
    if (startX === -1) {
      node.startX = -1;
      handlers = [];
    }
  }

  // Function to set the text selection based on the start and end coordinates
  function setSelection(x1: number, y1: number, x2: number, y2: number) {
    const [[startX, startY], [endX, endY]] = [
      [x1, y1],
      [x2, y2],
    ].sort((a, b) => {
      if (a[1] === b[1]) {
        return a[0] - b[0];
      }
      return a[1] - b[1];
    });
    const clear: TextNodeInfo[] = [];
    const update: TextNodeInfo[] = [];
    for (const node of textsInfo) {
      if (
        (startY < node.top && node.top + node.height < endY)
        || (node.left <= startX && startX <= node.left + node.width && node.top <= startY
          && startY <= node.top + node.height)
        || (node.left <= endX && endX <= node.left + node.width && node.top <= endY && endY <= node.top + node.height)
      ) {
        update.push(node);
      } else if (node.startX !== -1) {
        clear.push(node);
      }
    }
    if (clear.length > 0 || update.length > 0) {
      for (const node of clear) {
        execSelection(node, -1, -1, -1, -1, false, false);
      }
      const start = update[0];
      const end = update[update.length - 1];
      if (update.length === 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          Math.min(start.width, endX - start.left),
          Math.min(start.height, endY - start.top),
          true,
          true,
        );
      } else if (update.length > 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          start.width,
          start.height,
          true,
          false,
        );
        for (let i = 1; i < update.length - 1; i++) {
          execSelection(update[i], 0, 0, update[i].width, update[i].height, false, false);
        }
        execSelection(
          end,
          0,
          0,
          Math.min(end.width, endX - end.left),
          Math.min(end.height, endY - end.top),
          false,
          true,
        );
      }
      return true;
    }
    return false;
  }

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view
          id="container"
          style={{ width: "90vw" }}
          className="Container"
          bindlongpress={handleLongPress}
          bindtouchstart={handleTouchStart}
          bindtouchmove={handleTouchMove}
          bindtouchend={handleTouchEnd}
          bindtap={handleTap}
        >
          <text id="0" text-selection={true} custom-text-selection={true} flatten={false} className="Title">
            This is title
          </text>
          <view className="SplitLine" />
          <text id="1" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            1.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="2" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            2.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="3" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            3.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
        </view>
      </view>
    </page>
  );
};

export default CrossTextSelection;

root.render(<CrossTextSelection />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



2. Bind Gesture Events on the Wrapper `<view>`

Bind long-press, tap, and touch events on the outer `<view>` container. These will be used to control your custom selection and gesture logic.

```jsx
<view
  id="container"
  style={{ width: '90vw' }}
  className="Container"
  bindlongpress={handleLongPress}
  bindtouchstart={handleTouchStart}
  bindtouchmove={handleTouchMove}
  bindtouchend={handleTouchEnd}
  bindtap={handleTap}
>
  <text
    id="0"
    text-selection={true}
    custom-text-selection={true}
    flatten={false}
    className="Title"
  >
    This is title
  </text>
  <view className="SplitLine" />
</view>
```

3. Handle Selection and Copying Logic

- On component mount, retrieve metadata for all selectable `<text>` nodes, including their ID, dimensions, and positions:

```jsx
const CrossTextSelection = () => {
  useEffect(() => {
    getTextNodeRect();
}, []);

// Asynchronous function to get the bounding rectangles of text nodes
async function getTextNodeRect() {
  // 1.Use lynx.createSelectorQuery () to get the required text node.
  // 2.Call boundingClientRect method of the text node to get the rect of the node.
}

```

- On Long Press: Start Selection
  `handleLongPress()` is triggered on long press. It initiates the selection state, records the starting point, and performs the first selection update:

```jsx
// Handle long press event to start text selection
const handleLongPress = (e) => {
  isSelecting = true;
  startPosition.x = e.detail.x;
  startPosition.y = e.detail.y;
  setSelection(e.detail.x, e.detail.y, e.detail.x, e.detail.y);
};
```

- On Drag: Update Selection Area in Real Time

As the user drags, `handleTouchMove()` is called. If a selection is in progress, it updates the highlighted area accordingly:

```jsx
// Handle touch move event to update the selection area
const handleTouchMove = (e) => {
  if (isSelecting) {
    setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
  }
};
```

- On Finger Release: Finalize Selection

`handleTouchEnd()` is triggered on finger release. This finalizes the selected region and exits selection mode:

```jsx
// Handle touch end event to finalize the selection
const handleTouchEnd = (e) => {
  if (isSelecting) {
    setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
  }
  isSelecting = false;
};
```

On Tap Blank Area: Clear Selection

Tapping outside the text elements triggers a selection clear:

```jsx
// Handle tap event to clear the selection
const handleTap = (e) => {
  if (handlers.length === 0) {
    return;
  }
  setSelection(-1, -1, -1, -1);
};
```

- On Handle Drag: Adjust Selection Range

In `handleTouchStart()`, determine if the touch point is near one of the draggable handles. If so, allow real-time adjustment of the selection:

```jsx
// Handle touch start event to check if the touch is on a handler
const handleTouchStart = (e) => {
  if (handlers.length === 0) {
    return;
  }
  const { x, y } = e.detail;
  for (const [index, handler] of handlers.entries()) {
    if (
      Math.pow(handler.x - x, 2) + Math.pow(handler.y - y, 2) <
      Math.pow(handler.radius, 2)
    ) {
      isSelecting = true;
      const another = handlers[(index + 1) % 2];
      startPosition = { x: another.startX, y: another.startY };
      break;
    }
  }
};
```

## Compatibility

### `<text>`

**Compatibility Table**
**Query:** `elements.text`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>text</code>


### Nested `<text>`

**Compatibility Table**
**Query:** `elements.nested-text`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** nested <code>text</code>


### nested `<image>`

**Compatibility Table**
**Query:** `elements.nested-image`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** nested <code>image</code>


### `<inline-truncation>`

**Compatibility Table**
**Query:** `elements.inline-truncation`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>inline-truncation</code>




---
url: /api/elements/built-in/image.md
---

# `<image>`

APISummary
Used to display different types of images, including web images, static resources, and locally stored images.

:::tip

This feature depends on the image loading service provided by [Lynx Service](/guide/start/integrate-with-existing-apps.md).

:::

## Usage Guide

`<image>` is an [empty element](/guide/ui/elements-components.md#empty-elements) and no longer supports child nodes.

:::note

To display the image correctly, the non-empty [src](/api/elements/built-in/image.md#required-src) attribute must be set, and at least one of the following must be provided:

- A [width](/api/css/properties/width.md) and [height](/api/css/properties/width.md) greater than 0
- [auto-size](/api/elements/built-in/image.md#auto-size)

:::

The following examples show how the `<image>` element is used in different scenarios.

### Displaying images with different cropping/scaling modes

Supports controlling the image cropping/scaling mode using [mode](/api/elements/built-in/image.md#mode).

**This is an example below: image**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {30-42}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adding borders, rounded corners, and backgrounds to the image

You can set the image's borders, rounded corners, and background colors using CSS styles.

**This is an example below: image**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {44-73}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adding special drawing effects to the image

Supports special drawing effects like Gaussian blur.

**This is an example below: image**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {75-89}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Adapting to the original image aspect ratio

Use [auto-size](/api/elements/built-in/image.md#auto-size) to automatically adjust the `<image>` size to match the original image aspect ratio.

**This is an example below: image**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {18-28}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



### Listening to image load success/failure

You can bind [events](/api/elements/built-in/image.md#events) to listen for the image load state.

**This is an example below: image**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx {91-111}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ErrorEvent, LoadEvent } from "@lynx-js/types";

import LynxIcon from "@assets/image/lynxicon.png?inline";
import DoctorIcon from "@assets/image/rsdoctor.png?inline";
import LibIcon from "@assets/image/rslib.png?inline";
import SpeedyIcon from "@assets/image/rspeedy.png?inline";

import "./App.css";

interface ExampleProps {
  url: string;
}

const ImageAutoSizeExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear" style="linear-layout-gravity:left">
      <text className="sub-title">Image AutoSize Examples</text>
      <text>auto-size with no width</text>
      <image className="no-width" src={url} auto-size={true} />
      <text>auto-size with no height</text>
      <image className="no-height" src={url} auto-size={true} />
    </view>
  );
};

const ImageBasicExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Basic Examples</text>
      <text>scaleToFill</text>
      <image src={url} style="width:200px;height:100px" />
      <text>aspectFit</text>
      <image src={url} mode="aspectFit" style="width:200px;height:100px" />
      <text>aspectFill</text>
      <image src={url} mode="aspectFill" style="width:200px;height:100px" />
    </view>
  );
};

const ImageStyledExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Styled Examples</text>
      <text>aspectFit</text>
      <image
        className="mode-image"
        mode="aspectFit"
        src={url}
        style="border-radius: 10px"
      />

      <text>aspectFill</text>
      <image
        className="mode-image"
        mode="aspectFill"
        src={url}
        style="border-radius:50% "
      />

      <text>scaleToFill</text>
      <image
        className="mode-image"
        mode="scaleToFill"
        src={url}
        style="border-radius: 20px 30px 40px 10px"
      />
    </view>
  );
};

const ImageFilterExample = ({ url }: ExampleProps) => {
  return (
    <view className="linear">
      <text className="sub-title">Image Filter Examples</text>
      <text>origin pic</text>
      <image className="filter-image" src={url} />

      <text>blur pic</text>
      <image className="filter-image" src={url} blur-radius="5px" />

      <text>tint pic</text>
      <image className="filter-image" src={url} tint-color="#123aff" />
    </view>
  );
};

const ImageEventExample = ({ url }: ExampleProps) => {
  const handleImageLoad = (event: LoadEvent) => {
    console.log("Image loaded success:", JSON.stringify(event));
  };
  const handleImageError = (event: ErrorEvent) => {
    console.log("Image loaded error:", JSON.stringify(event));
  };
  return (
    <view className="linear">
      <text className="sub-title">Image Event Examples</text>
      <text>load event</text>
      <image className="filter-image" src={url} bindload={handleImageLoad} />
      <text>error event</text>
      <image
        className="filter-image"
        src={"error url"}
        binderror={handleImageError}
      />
    </view>
  );
};

const ImageExample = ({ type, url }: ExampleProps & { type: string }) => {
  switch (type) {
    case "auto-size":
      return <ImageAutoSizeExample url={url} />;
    case "styled":
      return <ImageStyledExample url={url} />;
    case "filter":
      return <ImageFilterExample url={url} />;
    case "event":
      return <ImageEventExample url={url} />;
    default:
      return <ImageBasicExample url={url} />;
  }
};

export const App = () => {
  const examples = [
    { type: "auto-size", url: LynxIcon },
    { type: "basic", url: SpeedyIcon },
    { type: "styled", url: LibIcon },
    { type: "filter", url: DoctorIcon },
    { type: "event", url: SpeedyIcon },
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">Image Examples</text>
      {examples.map((example, index) => <ImageExample type={example.type} url={example.url} />)}
    </scroll-view>
  );
};

```



Used to display images

## Attributes

### `auto-size`

Android
iOS
Clay
Harmony
2.6

```tsx
// @defaultValue: false
'auto-size'?: boolean;
```

When set to true and the
`<image>`
element has no width or height,
the size of the
`<image>`
will be automatically adjusted
to match the image's original dimensions after the image is successfully loaded,
ensuring that the aspect ratio is maintained.

### `autoplay`

Android
iOS
Clay
Harmony
2.11

```tsx
// @defaultValue: true
autoplay?: boolean;
```

Specifies whether the animated image should start playing automatically once it is loaded.

### `blur-radius`

Android
iOS
Clay
Harmony
0.2

```tsx
'blur-radius'?: string;
```

Image blur radius

### `cap-insets`

Android
iOS
Clay
Harmony
1.4

```tsx
'cap-insets'?: string;
```

Stretchable area for 9patch images, in percentage or decimal, four values for top, right, bottom, left

:::note
Using cap-insets does not require the original image to be a 9-patch image.
:::

### `cap-insets-scale`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 1
'cap-insets-scale'?: number;
```

Adjust the scale of stretchable area for 9patch images

### `defer-src-invalidation`

Android
iOS
Clay
Harmony
2.7

```tsx
// @defaultValue: false
'defer-src-invalidation'?: boolean;
```

When set to true, the
`<image>`
will only clear the previously displayed image resource after a new image has successfully loaded.
The default behavior is to clear the image resource before starting a new load.
This can resolve flickering issues when the image src is switched and reloaded. It is not recommended to enable this in scenarios where there is node reuse in views like lists.

### `image-config`

Android
Clay
1.4

```tsx
// @defaultValue: "ARGB_8888"
'image-config'?: 'ARGB_8888' | 'RGB_565';
```

`ARGB_8888`
: 32-bit memory per pixel, supports semi-transparent images.

`RGB_565`
: 16-bit memory per pixel, reduces memory usage but loses transparency.

Support PC platform since 3.5

:::note

Affects the actual memory usage of the image bitmap.

Taking an image with a resolution of 1024\*768 as an example, the actual memory usage is (1024 \* 768 \* bits per pixel / 8) Bytes.

The default is ARGB\_8888. Frontend developers can optimize image memory usage by setting it to RGB\_565.

`ARGB_8888`
: Each pixel occupies 32 bits of memory and includes an alpha channel.

`RGB_565`
: Each pixel occupies 16 bits of memory, which reduces memory usage but results in the loss of transparency.

Setting RGB\_565 may affect the display of
`<image>`
's border-radius. You can set border-radius on the parent view of the
`<image>`
and add the clip-radius attribute to the parent view.

It is not recommended to use RGB\_565 when mode="aspectFit", as it may cause black borders in the cropped area.

:::

### `loop-count`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'loop-count'?: number;
```

Number of times an animated image plays, 0 stands for infinite

### `mode`

Android
iOS
Clay
Harmony
0.2

```tsx
// @defaultValue: 'scaleToFill'
mode?: 'scaleToFill' | 'aspectFit' | 'aspectFill' | 'center';
```

Specifies image cropping/scaling mode

`scaleToFill`
: Scales the image without preserving the aspect ratio, stretching the image to fill the element.

`aspectFit`
: Scales the image while preserving aspect ratio so that the long side is fully visible.

`aspectFill`
: Scales the image while preserving aspect ratio, ensuring the short side fills the element.

`center`
: Does not scale the image; image is centered.

### `placeholder`

Android
iOS
Clay
Harmony
1.4

```tsx
placeholder?: string;
```

Placeholder image, used same as src

### `prefetch-height`

Android
iOS
1.4

```tsx
// @defaultValue: "0px"
'prefetch-height'?: string;
```

Image won't load if its size is 0, but will load if prefetch-height is set

### `prefetch-width`

Android
iOS
1.4

```tsx
// @defaultValue: "0px"
'prefetch-width'?: string;
```

Image won't load if its size is 0, but will load if prefetch-width is set

### `src`

Android
iOS
Clay
Harmony
0.2

```tsx
// @defaultValue: undefined
src?: string;
```

Supports http/https/base64

### `tint-color`

Android
iOS
Clay
Harmony
2.12

```tsx
'tint-color'?: string;
```

Changes the color of all non-transparent pixels to the tint-color specified. The value is a
`<color>`
.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindcurrentloopcomplete`

Android
iOS
Harmony
3.7

```tsx
bindcurrentloopcomplete = (e: BaseEvent) => {};
```

Triggered when one loop of the animated image finishes playing.

### `binderror`

Android
iOS
Clay
Harmony
0.2

```tsx
binderror = (e: ErrorEvent) => {};
```

Image load error event

### `bindfinalloopcomplete`

Android
iOS
Harmony
3.7

```tsx
bindfinalloopcomplete = (e: BaseEvent) => {};
```

Triggered when the animated image finishes playing all
`loop-count`
loops. If
`loop-count`
is not set, this callback will not be triggered.

### `bindload`

Android
iOS
Clay
Harmony
0.2

```tsx
bindload = (e: LoadEvent) => {};
```

Image load success event

### `bindstartplay`

Android
iOS
Harmony
3.7

```tsx
bindstartplay = (e: BaseEvent) => {};
```

Triggered when the animated image starts playing.

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `pauseAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'pauseAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Pauses the animation, without resetting the loop-count.

### `resumeAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'resumeAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Resumes the animation, without resetting the loop-count.

### `startAnimate`

Android
iOS
Clay
Harmony
Deprecated
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'startAnimate',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Restart the animation playback method controlled by the front end, and the animation playback progress and loop count will be reset.

### `stopAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'stopAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Stops the animation, and it will reset the loop-count.

## Advanced Features

### Request URL Redirection Mapping

#### Feature Description

By implementing a URL redirection mechanism, developers can intercept specific image URLs and map them to specific resource paths. This ability is useful for the following scenarios:

- Improving static resource loading speed
- Supporting custom image protocol access schemes
- Protecting sensitive resource access paths

#### Implementation Principle

This feature is implemented based on the [`MediaResourceFetcher`](/api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md) interface, with the core process divided into two stages:

1. **Resource Type Detection** (`isLocalResource`)

   - Determines if the request URL matches the custom protocol
   - Returns a boolean indicating whether to handle it locally

2. **Path Conversion** (`shouldRedirectUrl`)
   - Parses the original URL
   - Converts it into a valid resource path
   - Returns the final accessible URL address

The following example shows how to map a URL like `http://localhost/xxx` to an app's built-in resource path:

iOSAndroidHarmonyOS```objective-c
/// Local resource handler header
#import <LynxMediaResourceFetcher/LynxMediaResourceFetcher.h>

@interface LocalMediaFetcher : NSObject <LynxMediaResourceFetcher>

- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request;

- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url;

@end
```
```objective-c
/// Local resource handler implementation
#import "LocalMediaFetcher.h"

@implementation LocalMediaFetcher

/**
 * Resource path conversion method
 * @param request Resource request object
 * @return Local file path or empty string
 */
- (NSString *)shouldRedirectUrl:(LynxResourceRequest *)request {
  NSURL *url = [NSURL URLWithString:request.url];
  NSString *fileType = [url pathExtension];
  NSString *fileName = [[url URLByDeletingPathExtension] lastPathComponent];
  NSString *subdir = [[[url URLByDeletingLastPathComponent] absoluteString] stringByReplacingOccurrencesOfString:@"http://localhost" withString:@""];
  NSString *path = [[NSBundle mainBundle] pathForResource:fileName ofType:fileType inDirectory:subdir];
  return path ? [NSString stringWithFormat:@"file://%@", path] : @"";
}

/**
 * Local resource detection method
 * @param url The original request URL
 * @return LynxResourceOptionalBoolTrue indicates the request needs redirection
 */
- (LynxResourceOptionalBool)isLocalResource:(NSURL *)url {
    return [url.absoluteString hasPrefix:@"http://localhost"] ?
           LynxResourceOptionalBoolTrue :
           LynxResourceOptionalBoolFalse;
}

@end
```
```java
import com.lynx.tasm.resourceprovider.LynxResourceRequest
import com.lynx.tasm.resourceprovider.media.LynxMediaResourceFetcher
import com.lynx.tasm.resourceprovider.media.OptionalBool

/**
 * Custom media resource handler
 *
 * @property protocol The protocol to intercept "http://localhost"
 * @property scheme The target resource protocol "asset://"
 */
class LocalMediaFetcher : LynxMediaResourceFetcher() {

    /**
     * Determines if the resource is local
     * @param url The original request URL
     * @return OptionalBool.TRUE indicates the request needs redirection
     */
    override fun isLocalResource(url: String?): OptionalBool {
        return if (url?.startsWith("http://localhost") == true) {
            OptionalBool.TRUE
        } else {
            OptionalBool.FALSE
        }
    }

    /**
     * Performs URL redirection
     * @param request The resource request object
     * @return The converted valid resource path
     */
    override fun shouldRedirectUrl(request: LynxResourceRequest?): String {
        return request?.url?.replace(
            oldValue = "http://localhost",
            newValue = "asset://",
            ignoreCase = true
        ) ?: ""
    }
}
```
```typescript
import {
  LynxMediaResourceFetcher,
  LynxResourceRequest,
  LynxOptionalBool,
} from '@lynx/lynx';

// Local resource handler implementation
export class ExampleMediaResourceFetcher extends LynxMediaResourceFetcher {
  // Resource path conversion method
  // @param request Resource request object
  // @return Local file path or empty string
  shouldRedirectUrl(request: LynxResourceRequest): string {
    return request.url?.replace('http://localhost', 'file://') ?? '';
  }

  // Determines if the resource is local
  // @param url The original request URL
  // @return LynxOptionalBool.TRUE indicates the request needs redirection
  isLocalResource(url: string): LynxOptionalBool {
    if (url.startsWith('http://localhost')) {
      return LynxOptionalBool.TRUE;
    }
    return LynxOptionalBool.FALSE;
  }
}
```

Read the API reference of [`MediaResourceFetcher`](/api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md) for more details.

## Compatibility

**Compatibility Table**
**Query:** `elements.image`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** image


```
```



---
url: /api/elements/built-in/scroll-view.md
---

# `<scroll-view>`

APISummary
Basic scrolling component supporting both horizontal and vertical scrolling. When its content area is larger than its visible area, it allows users to scroll to reveal more content.

## Usage

### Horizontal and Vertical Scrolling

`<scroll-view>` supports both horizontal and vertical scrolling, implemented through the `scroll-orientation` properties.
`<scroll-view>` always uses the [linear](/guide/ui/layout/linear-layout.md) layout, and the layout direction is determined by the `scroll-orientation` attributes.

**This is an example below: scroll-view**

**Entry:** `src/base`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {15,24}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { VerticalScrollItem } from "../component/scrollItem.jsx";
import { HorizontalScrollItem } from "../component/scrollItem.jsx";

export const App = () => {
  return (
    <view style={{ width: "100%", height: "100%", padding: 10, display: "linear", marginTop: 20 }}>
      <text style={{ fontSize: "20px", fontWeight: "bold", height: "40px", paddingLeft: "10px", marginTop: "10px" }}>
        Horizontal ScrollView Example
      </text>
      <scroll-view
        scroll-orientation="horizontal"
        style={{ width: "calc(100% - 10px)", height: "100px", paddingLeft: "5px", borderRadius: "10px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => <HorizontalScrollItem index={index} />)}
      </scroll-view>
      <text style={{ fontSize: "20px", fontWeight: "bold", height: "40px", paddingLeft: "10px", marginTop: "10px" }}>
        Vertical ScrollView Example
      </text>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px", marginLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => <VerticalScrollItem index={index} />)}
      </scroll-view>
    </view>
  );
};

```



### Scroll Events

Use event callbacks such as [`bindscroll`](#bindscroll), [`bindscrolltoupper`](#bindscrolltoupper), and [`bindscrolltolower`](#bindscrolltolower) to monitor changes in scroll progress.

**This is an example below: scroll-view**

**Entry:** `src/event`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {16-24}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root } from "@lynx-js/react";
import "./index.css";
import { VerticalScrollItem } from "../component/scrollItem.jsx";
const VerticalScrollContainer = () => {
  return (
    <view
      style={{ width: "100%", height: "100%" }}
    >
      <text className="title">ScrollView Example</text>
      <scroll-view
        scroll-orientation="vertical"
        style="width:100%; height: 100%; padding-left: 5px;margin-left:5px"
        bindscroll={(e) => {
          console.log(e.detail);
        }}
        bindscrolltoupper={(e) => {
          console.log(e.detail);
        }}
        bindscrolltolower={(e) => {
          console.log(e.detail);
        }}
      >
        {Array.from({ length: 20 }).map((item, index) => <VerticalScrollItem index={index} />)}
      </scroll-view>
    </view>
  );
};
export default VerticalScrollContainer;
root.render(<VerticalScrollContainer />);

```



### Sticky Capability

As a child node of `<scroll-view>`, you can set the `sticky` attribute making the child node remain at a certain distance from the top of the `<scroll-view>` and not continue scrolling with the content.

**This is an example below: scroll-view**

**Entry:** `src/sticky`
**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root } from "@lynx-js/react";
import { VerticalScrollItem } from "../component/scrollItem.jsx";
import { StickyItem } from "./stickyItem.jsx";

const VerticalScrollContainer = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <text className="title">ScrollView Example</text>
      <scroll-view
        scroll-orientation="vertical"
        style={{ width: "100%", height: "100%", paddingLeft: "5px", marginTop: "5px", marginLeft: "5px" }}
      >
        {Array.from({ length: 20 }).map((item, index) => {
          if (index == 2) {
            return <StickyItem index={index} height={100} sticky={true} />;
          }
          return <VerticalScrollItem index={index} />;
        })}
      </scroll-view>
    </view>
  );
};
export default VerticalScrollContainer;
root.render(<VerticalScrollContainer />);

```



:::tip
`sticky`
 can only be set for direct child nodes of `<scroll-view>`
. On Android, you need to add the `flatten={false}`
 attribute to `sticky`
 nodes.
The direct child nodes of `<scroll-view>` only support `linear` and `sticky`. If you need more complex layouts, such as child nodes adapting to expand, it is recommended to provide a single child view to the `<scroll-view>` and implement more robust CSS capabilities within that single child node.

```javascript
<scroll-view> scroll-y>
  <view> // do anything you want
  {...}
  </view>
</scroll-view>
```

:::

## Attributes

### `bounces`

iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
bounces?: boolean;
```

Enable bounce effect

### `enable-scroll`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
'enable-scroll'?: boolean;
```

Enable dragging

### `initial-scroll-offset`

Android
iOS
Clay
Harmony
2.17

```tsx
// @defaultValue: 0
'initial-scroll-offset'?: number;
```

Initial scroll position, only effective once, in PX

### `initial-scroll-to-index`

Android
iOS
Clay
Harmony
2.17

```tsx
// @defaultValue: 0
'initial-scroll-to-index'?: number;
```

Scroll to specified child node on first screen, only effective once. All direct child nodes must be flatten=false.

### `lower-threshold`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'lower-threshold'?: number;
```

Set upper threshold to bindscrolltoupper event.

### `scroll-bar-enable`

iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
'scroll-bar-enable'?: boolean;
```

Enable scrollbar

### `scroll-orientation`

Android
iOS
Clay
Harmony
3.0

```tsx
// @defaultValue: 'vertical'
'scroll-orientation'?: 'vertical' | 'horizontal';
```

Replacement of scroll-x and scroll-y

### `upper-threshold`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'upper-threshold'?: number;
```

Set upper threshold to bindscrolltoupper event.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindcontentsizechanged`

Android
iOS
Harmony
1.6

```tsx
bindcontentsizechanged = (e: ContentSizeChangedEvent) => {};
```

This event is triggered when the scrollview's content size changed.

### `bindscroll`

Android
iOS
Clay
Harmony
1.4

```tsx
bindscroll = (e: ScrollEvent) => {};
```

This event is triggered when the scrollview is scrolling.

### `bindscrollend`

Android
iOS
Clay
Harmony
1.6

```tsx
bindscrollend = (e: ScrollEndEvent) => {};
```

This event is triggered when the scrollview's scroll ended.

### `bindscrolltolower`

Android
iOS
Harmony
1.4

```tsx
bindscrolltolower = (e: ScrollToLowerEvent) => {};
```

This event is triggered when the lower/right edge of the scrolling area intersects with the visible area defined by the lowerThreshold.

### `bindscrolltoupper`

Android
iOS
Harmony
1.4

```tsx
bindscrolltoupper = (e: ScrollToUpperEvent) => {};
```

This event is triggered when the upper/left edge of the scrolling area intersects with the visible area defined by the upperThreshold.

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `autoScroll`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'autoScroll',
      params: {
        /**
         * The distance of each second's scrolling, which supports positive and negative values. The unit of distance can be "px", "rpx", "ppx", or null (for iOS, the value must be greater than 1/screen.scale px).
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        rate: number;
        /**
         * Start/stop automatic scrolling.
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        start: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Automatic scrolling

### `getScrollInfo`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getScrollInfo',
      success: Callback<{
        /**
         * Total scrollable range along orientation, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollRange: number;
        /**
         * Content offset on X-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollX: number;
        /**
         * Content offset on Y-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollY: number;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get scroll info

### `scrollBy`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollBy',
      params: {
        /**
         * Offset to scroll
         */
        offset?: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Scroll by specified offset

### `scrollTo`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollTo',
      params: {
        /**
         * Target item index
         * @defaultValue 0
         */
        index?: number;
        /**
         * Offset relative to target node
         */
        offset?: number;
        /**
         * Enable scroll animation
         */
        smooth?: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Scroll to specified position

## Performance Optimization Suggestions

`<scroll-view>` creates all of its child nodes at once, potentially causing severe first-screen load times. Use exposure events to drive it to create only visible child nodes.

`<scroll-view>` lacks any reuse mechanism. If content is too extensive, it may consume an exceptionally large amount of memory, possibly causing OOM and other stability problems.

For data exceeding three screens, use `<list>` to optimize performance, or simulate `<VisualizedList>` logic based on exposure events.

## Compatibility

**Compatibility Table**
**Query:** `elements.scroll-view`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** scroll-view




---
url: /api/elements/built-in/list.md
---

# `<list>`

APISummary
The `<list>` component is a high-performance scrollable container that optimizes performance and memory usage through element recycling and lazy loading. It supports horizontal and vertical scrolling with single-column, grid, and waterfall layouts, making it ideal for infinite-scroll feeds and similar use cases.

## Usage

### Single-Column Layout

**1. Set width and height**: The width and height of `<list>` represent the size of its viewport, so they need to be fixed values and cannot be expanded by internal content. Only child nodes visible in the visible area will be rendered.

**2. Set scroll direction and layout form**: Set the attribute [`scroll-orientation`](#scroll-orientation) to specify the layout and scroll direction, and set [`list-type`](#list-type) and [`span-count`](#span-count) to specify the layout form.

**3. Configure child nodes**: Use the `<list-item>` tag as a direct child node of `<list>` , and set [`item-key`](#item-key) and [`key`](#key) for `<list-item>`, ensuring they are consistent.

**This is an example below: list**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {11-13,23-26}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      scroll-orientation="vertical"
      list-type="single"
      span-count={1}
      style={{
        width: "100%",
        height: "100vh",
        listMainAxisGap: "5px",
        padding: "10px",
      }}
    >
      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Multi-Column Layout

**1. Set layout type and column count**: Set the layout type [`list-type`](#list-type) to `flow` (grid layout) or `waterfall` (waterfall layout), and set [`span-count`](#span-count) >= 2.

**2. Full-span child nodes in multi-column layout**: Set the [`full-span`](#full-span) attribute for `<list-item/>` to make it occupy a full row or column in the layout.

Grid Layout Example:

**This is an example below: list**

**Entry:** `src/flow`
**Bundle:** `dist/flow.lynx.bundle` | Web: `dist/flow.web.bundle`

```tsx {14-15,24}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { ItemView } from "./flowItemView.jsx";

import "./index.scss";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      list-type="flow"
      span-count={3}
      scroll-orientation="vertical"
    >
      {Array.from({ length: 40 }).map((item, index) => {
        if (index % 4 == 3) {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
              full-span={true}
              className="full-span-item"
            >
              <text className="full-span-text">{`full span item`}</text>
            </list-item>
          );
        } else {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <ItemView index={index} />
            </list-item>
          );
        }
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Waterfall Layout Example:

**This is an example below: list**

**Entry:** `src/waterfall`
**Bundle:** `dist/waterfall.lynx.bundle` | Web: `dist/waterfall.web.bundle`

```tsx {14-15}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";

import "./index.scss";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      list-type="waterfall"
      span-count={2}
      scroll-orientation="vertical"
    >
      {Array.from({ length: 40 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## List-specific CSS Properties

:::note

List-specific CSS properties are a set of CSS properties designed exclusively for styling the `<list>` component. These properties, such as `list-main-axis-gap` and `list-cross-axis-gap`, provide fine-grained control over the layout and spacing of items within the list. It is important to note that these properties will only work on `<list>` and will be ignored on any other component.

:::

### `list-main-axis-gap`

```tsx
// DefaultValue: null
list-main-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listMainAxisGap:'10px'}}
/>
```

Specifies the spacing of `<list>` child nodes in the main axis direction, which needs to be written in the style.

### `list-cross-axis-gap`

```tsx
// DefaultValue: null
list-cross-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listCrossAxisGap:'10px'}}
/>
```

Specifies the spacing of `<list>` child nodes in the cross axis direction, which needs to be written in the style.

## Attributes

### `list-type`
 Required {#required-list-type}
```tsx
list-type: 'single' | 'flow' | 'waterfall'
```

Controls the layout type of the `<list>` component, which needs to be used in conjunction with [`span-count`](#span-count).

| Value       | Description                                                                                                                                                                                                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `single`    | Single-column/row layout                                                                                                                                                                                                                                                                    |
| `flow`      | Multi-column/row grid layout. The grid layout fully reflects regularity, with the `top` of adjacent child nodes in columns being consistent. Typically used for child nodes of uniform size. The width of child nodes is determined by the width of `<list>` and `span-count`.              |
| `waterfall` | Multi-column/row waterfall layout. Content is continuously filled from top to bottom into the shortest column, achieving visual continuity and dynamism. Typically used for child nodes of varying sizes. The width of child nodes is determined by the width of `<list>` and `span-count`. |

You can find real world examples in the [Multi-Column Layout](#multi-column-layout) section to see the difference between `flow` and `waterfall` more clearly.

### `span-count`
 Required {#required-span-count}
```tsx
span-count: number
```

Sets the number of columns or rows for the `<list>` component layout.

### `scroll-orientation`
 Required {#required-scroll-orientation}
```tsx
// DefaultValue: "vertical"
scroll-orientation?: 'vertical' ｜ 'horizontal'
```

Sets the scrolling direction and layout direction of the `<list>` component.

### `item-key`
 Required {#required-item-key}
```tsx
// DefaultValue: null
item-key: string

<list-item item-key="item"/>
```

The `item-key` attribute is a required attribute on `<list-item>`.

:::note

Developers need to set a unique `item-key` for each `<list>` child node. It is used to help `<list>` identify which `<list>` child nodes have changed, been added, or removed. Therefore, developers need to ensure the correct setting of `item-key`. Incorrect settings may lead to disorder and flickering issues.

:::

### `key`
 Required {#required-key}
```tsx
// DefaultValue: null
key: string

<list-item
  item-key="item-0"
  key="item-0"
/>
```

Use the `key` attribute to help the framework identify which elements have changed, been added, or removed.

:::note

In the list scenario, `key` and `item-key` should remain consistent.

:::

### `enable-scroll`

```tsx
// DefaultValue: true
enable-scroll?: boolean
```

Indicates whether the `<list>` component is allowed to scroll.

### `enable-nested-scroll`

```tsx
// DefaultValue: true
enable-nested-scroll?: boolean
```

Indicates whether `<list>` can achieve nested scrolling with other scrollable containers. When enabled, the inner container scrolls first, followed by the outer container.

### `sticky`

```tsx
// DefaultValue: false
sticky?: boolean
```

Declared on the `<list>` component to control whether the `<list>` component as a whole is allowed to be sticky at the top or bottom.

### `sticky-offset`

```tsx
// DefaultValue: 0
sticky-offset?: number
```

The offset distance from the top or bottom of `<list>` for sticky positioning, in `px`.

### `sticky-top`

```tsx
// DefaultValue: false
sticky-top?: boolean
```

Declared on the `<list-item>` child node to control whether the node will be sticky at the top.

### `sticky-bottom`

```tsx
// DefaultValue: false
sticky-bottom?: boolean
```

Declared on the `<list-item>` child node to control whether the node will be sticky at the bottom.

### `recyclable`

```tsx
// DefaultValue: true
recyclable?: boolean
```

```json
"dependencies": {
  "@lynx-js/react": "^0.112.2"
}
```

Declared on the `<list-item>` node to control whether the node can be recycled, and if set to `false`, the `<list-item>` will not be recycled when it is scrolled out of the viewport of `<list>`.

### `bounces`

```ts
// DefaultValue: true
bounces?: boolean
```

Enables edge bounce effect.

### `initial-scroll-index`

```tsx
// DefaultValue: 0
initial-scroll-index?: number
```

Specifies the node position to which `<list>` automatically scrolls after rendering, effective only once.

### `need-visible-item-info`

```tsx
// DefaultValue: false
need-visible-item-info?: boolean
```

Controls whether the scroll event callback parameters include the position information of the currently rendering node. The scroll events include: [`scroll`](#scroll), [`scrolltoupper`](#scrolltoupper), [`scrolltolower`](#scrolltolower).

Scroll event callback parameter format:

```tsx
interface ListScrollInfo {
  // Horizontal scroll offset since the last scroll, in px
  deltaX: number;
  // Vertical scroll offset since the last scroll, in px
  deltaY: number;
  // Current horizontal scroll offset, in px
  scrollLeft: number;
  // Current vertical scroll offset, in px
  scrollTop: number;
  // Current content area width, in px
  scrollWidth: number;
  // Current content area height, in px
  scrollHeight: number;
  // `<list>` width, in px
  listWidth: number;
  // `<list>` height, in px
  listHeight: number;
  // Scroll event source
  eventSource: ListEventSource;
  // Position information of the currently rendering node
  attachedCells: [
    {
      id: number; // Node id
      itemKey: string; // Node item-key
      index: number; // Node index in list
      left: number; // Node left boundary position relative to list, in px
      top: number; // Node top boundary position relative to list, in px
      right: number; // Node right boundary position relative to list, in px
      bottom: number; // Node bottom boundary position relative to list, in px
    },
  ];
}
```

### `upper-threshold-item-count`

```tsx
// DefaultValue: 0
upper-threshold-item-count?: number
```

Triggers a [`scrolltoupper`](#scrolltoupper) event once when the number of remaining displayable child nodes at the top of `<list>` is less than [`upper-threshold-item-count`](#upper-threshold-item-count) for the first time.

### `lower-threshold-item-count`

```tsx
// DefaultValue: 0
lower-threshold-item-count?: number
```

Triggers a [`scrolltolower`](#scrolltolower) event once when the number of remaining displayable child nodes at the bottom of `<list>` is less than [`lower-threshold-item-count`](#lower-threshold-item-count) for the first time.

### `scroll-event-throttle`

```tsx
// DefaultValue: 200
scroll-event-throttle?: number
```

Sets the time interval for the `<list>` callback [`scroll`](#scroll) event, in milliseconds (ms). By default, the scroll event is called back every 200 ms.

:::note

When the `engineVersion`
 version is less than 3.4, this attribute will not take effect, and the [`scroll`](#scroll)
 event will not be intercepted. When the `engineVersion`
 version is greater than or equal to 3.4, if this attribute is not set, it will use default value 200 ms.
:::

### `item-snap`

```tsx
// defaultValue: undefined
'item-snap'?: ListItemSnapAlignment;

interface ListItemSnapAlignment {
  factor: number;
  offset: number;
}
```

Controls the paginated scrolling effect of `<list>`.

Pagination parameters

- `factor`: The parameter for paginated positioning, with a range of `[0, 1]`
  - A value of `0` means the paginated scrolling `<list>` child node aligns with the top of `<list>`
  - A value of `1` means the paginated scrolling `<list>` child node aligns with the bottom of `<list>`
- `offset`: Additional offset parameter added on top of `factor`

:::note

When the 'engineVersion' version is less than '3.2', there will be inconsistencies in the scrolling speed on the mobile platform.

:::

### `update-animation`

```tsx
update-animation?: "default" | "none"
```

This property controls whether the list runs animations while the data source is being updated. It currently supports insert, delete, and update animations.

Example of update-animation:

| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_delete.gif)
delete | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_update.gif)
update | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_insert.gif)
insert |


:::note

Currently, `update-animation` can only work when `list-type` is `single` or `flow`.

:::

### `need-layout-complete-info`

Controls whether the [`layoutcomplete`](#layoutcomplete) event includes the node layout information before and after this `layout`, the `<list>` Diff information that triggered this layout, and the current `<list>` scroll state information.

```tsx
export interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // Enable need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // Enable need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // Enable need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // Enable need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}
```

### `layout-id`

```tsx
// defaultValue: -1
layout-id?: number
```

Used to mark the unique identifier for this data source update, which will be returned in the [`layoutcomplete`](#layoutcomplete) event callback.

### `preload-buffer-count`

```tsx
// DefaultValue: 0
preload-buffer-count?: number
```

This attribute controls the number of nodes outside `<list>` that are preloaded.

:::note

- The larger the value of `preload-buffer-count`, the more off-screen nodes can be preloaded, but it will also increase the memory usage of `<list>`.

- The recommended value for `preload-buffer-count` is the number of nodes that fill one screen of `<list>`.

- Only effective when `list-type='single'/'flow'`.

:::

### `scroll-bar-enable`

```tsx
// DefaultValue: true
scroll-bar-enable?: boolean
```

Indicates whether the `<list>` component scroll bar is displayed.

### `harmony-scroll-edge-effect`

```tsx
// DefaultValue: true
harmony-scroll-edge-effect: boolean
```

On Harmony, when the contentSize is smaller than its own container size, set whether to enable the scroll effect.

### `reuse-identifier`

```tsx
// DefaultValue: null
reuse-identifier: string

<list>
  <list-item
    reuse-identifier="type1"
  >
  <list-item
    reuse-identifier="type2"
  >
</list>
```

Sets the reuse id for `<list-item>`. When rendering child nodes, the `<list>` component reuses `<list-item>` based on the `reuse-identifier` attribute value. Only `<list-item>` with the same `reuse-identifier` attribute value will be reused.

By default, developers do not need to provide a `reuse-identifier`, as the framework determines it during the compilation phase. For example, when `<list-item>` is within a loop (e.g., `Array.prototype.map`), since they have the same form and position during the compilation phase, we generate the same `reuse-identifier` for them, allowing this group of `<list-item>` to be reused with each other.

:::note

Use case: `<list-item>` with significant structural differences perform poorly when reused. Therefore, it is recommended to set different `reuse-identifier` values for them to avoid mutual reuse.

:::

### `full-span`

```tsx
// DefaultValue: false
full-span?: boolean
<list>
  <list-item full-span={true}/>
</list>
```

The `full-span` attribute is used to indicate that a `<list-item>` occupies a full row or column.

### `estimated-main-axis-size-px`

```tsx
// DefaultValue: -1
estimated-main-axis-size-px?: number
<list-item
  estimated-main-axis-size-px={100}
/>
```

Specifies the placeholder size in the main axis direction for `<list-item>` before it is fully rendered, in `px`. If not set, the default value is the size of `<list>` in the main axis direction.

:::note

It is strongly recommended that developers set `estimated-main-axis-size-px` to a value close to the actual size of the child nodes.

:::

### `experimental-recycle-sticky-item`

```tsx
// DefaultValue: true
experimental-recycle-sticky-item?: boolean
```

When there are multiple sticky nodes, after a sticky node is pushed out of the `<list>`
 area by other sticky nodes, the node is recycled to address the memory overhead issue caused by too many sticky nodes. This optimization is enabled by default when `engineVersion`
 version is greater than or equal to 3.4.
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/not-recycle-sticky-1.gif)
sticky nodes not recycled, the ui count will keep increasing | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recycle-sticky-1.gif)
sticky nodes is recycled and reused, the ui count will not keep
increasing |


## Events

Front-end developers can bind corresponding event callbacks to components to monitor runtime behavior. The usage is as follows.

### `scroll`

```tsx
bindscroll?: EventHandler<ListScrollEvent>;

interface ListScrollEvent {
  // Horizontal scroll offset since the last scroll, in px
  deltaX: number;
  // Vertical scroll offset since the last scroll, in px
  deltaY: number;
  // Current horizontal scroll offset, in px
  scrollLeft: number;
  // Current vertical scroll offset, in px
  scrollTop: number;
  // Current content area width, in px
  scrollWidth: number;
  // Current content area height, in px
  scrollHeight: number;
  // `<list>` width, in px
  listWidth: number;
  // `<list>` height, in px
  listHeight: number;
  // Scroll event source
  eventSource: ListEventSource;
  // Position information of the currently rendering node
  attachedCells: [
    {
      "id": number,        // Node id
      "itemKey": string,   // Node item-key
      "index": number,     // Node index in list
      "left": number,      // Node left boundary position relative to list, in px
      "top": number,       // Node top boundary position relative to list, in px
      "right": number,     // Node right boundary position relative to list, in px
      "bottom": number,    // Node bottom boundary position relative to list, in px
    },
  ];
}

enum ListEventSource {
  DIFF = 0,
  LAYOUT = 1,
  SCROLL = 2,
}
```

`<list>` scroll event.

:::note

- The frequency of scroll event triggers can be controlled by [`scroll-event-throttle`](#scroll-event-throttle).

- If `<list>` enables [`need-visible-item-info`](#need-visible-item-info), the callback parameters will include the position information of the currently rendering child nodes.

:::

### `scrolltoupper`

```tsx
bindscrolltoupper?: EventHandler<ListScrollEvent>;
```

Callback triggered when scrolling to the top of `<list>`. The trigger position of this callback can be controlled by [`upper-threshold-item-count`](#upper-threshold-item-count).

### `scrolltolower`

```tsx
bindscrolltolower?: EventHandler<ListScrollEvent>;
```

Callback triggered when scrolling to the bottom of `<list>`. The trigger position of this callback can be controlled by [`lower-threshold-item-count`](#lower-threshold-item-count).

### `scrollstatechange`

```tsx
bindscrollstatechange?: EventHandler<ListScrollStateChangeEvent>;

interface ScrollStateChangeEvent extends CustomEvent {
  detail: {
    // The scroll state of this slide, value description
    //   1 - Stationary
    //   2 - Dragging
    //   3 - Inertial scrolling
    //   4 - Smooth animation scrolling
    state: number;
  };
}
```

Callback triggered when the scroll state of `<list>` changes. The `state` field in the event parameter's `detail` indicates the scroll state: `1` for stationary, `2` for dragging, and `3` for inertial scrolling, `4` for smooth animation scrolling.

### `layoutcomplete`

```tsx
bindlayoutcomplete?: EventHandler<ListLayoutFinishEvent>;

interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // Enable need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // Enable need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // Enable need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // Enable need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}

interface ListItemInfo {
  // Child node height
  height: number;
  // Child node width
  width: number;
  // Child node itemKey
  itemKey: string;
  // Whether the child node is in rendering state
  isBinding: boolean;
  // X coordinate position of the child node relative to the entire scroll area
  originX: number;
  // Y coordinate position of the child node relative to the entire scroll area
  originY: number;
  // Whether the child node has been updated
  updated: boolean;
}
```

Callback triggered after `<list>` layout is complete.

### `snap`

```tsx
bindsnap?: EventHandler<ListSnapEvent>;

interface ListSnapEvent extends common.BaseEvent<'snap', {}> {
  detail: {
    // The index of the node that will be paginated to
    position: number;
    // Current horizontal scroll offset, in px
    currentScrollLeft: number;
    // Current vertical scroll offset, in px
    currentScrollTop: number;
    // Target horizontal scroll offset for pagination, in px
    targetScrollLeft: number;
    // Target vertical scroll offset for pagination, in px
    targetScrollTop: number;
  };
};
```

Callback when pagination scrolling is about to occur.

## Methods

### `scrollToPosition`

```tsx
this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollToPosition',
    params: {
      position: 10,
      offset: 100,
      alignTo: 'top',
      itemKey: `${itemKey}`
      smooth: true,
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();
```

Scroll the `<list>` component to the specified position. Parameter description:

| Parameter | Type    | Default | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :-------- | :------ | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| position  | number  | None    | Yes      | Specifies the index of the node to scroll to, with a range of `[0, data source count)`                                                                                                                                                                                                                                                                                                                                                                            |
| offset    | number  | None    | No       | After applying `alignTo` alignment, continue scrolling the `offset` length                                                                                                                                                                                                                                                                                                                                                                                        |
| alignTo   | string  | null    | Yes      | The position of the target node in the view after scrolling. <br /><br />`"bottom"`: Scroll until the node is fully visible in `<list>`, and the bottom of the node aligns with the bottom of `<list>`<br /><br />`"top"`: Scroll until the node is fully visible in `<list>`, and the top of the node aligns with the top of `<list>`<br /><br />`"middle"`: Scroll until the node is fully visible in `<list>`, and the node is vertically centered in `<list>` |
| itemKey   | string  | null    | NO       | Specifies the `item-key` of the node to scroll to. If set `position` and `item-key`, the list will scroll to the node with the specified `item-key`.                                                                                                                                                                                                                                                                                                              |
| smooth    | boolean | false   | No       | Whether there is animation during the scrolling process                                                                                                                                                                                                                                                                                                                                                                                                           |

### `autoScroll`

```tsx
this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'autoScroll',
    params: {
      rate: string, //  The distance scrolled per second, supports positive and negative. Distance supports units "px/rpx/ppx" default->null (iOS value must be greater than 1/screen.scale px)
      start: bool, //  Start/pause auto-scrolling default->false
      autoStop: bool, // Whether to automatically stop when reaching the bottom default->true
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();
```

Trigger `<list>` auto-scrolling. Parameter description:

| Parameter | Type   | Default | Required | Description                                                                                   |
| :-------- | :----- | :------ | :------- | :-------------------------------------------------------------------------------------------- |
| rate      | string | None    | null     | The distance scrolled per second, supports positive and negative, can set units: `px/rpx/ppx` |
| start     | bool   | None    | false    | Start or pause auto-scrolling, `true`: start auto-scrolling, `false`: pause auto-scrolling    |
| autoStop  | bool   | None    | true     | Whether to automatically stop when reaching the bottom                                        |

### `getVisibleCells`

```tsx
lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'getVisibleCells',
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();
```

Get information about all currently displayed `<list>` child nodes. The returned information is as follows:

```tsx
attachedCells: [
  {
    id: number, // Node id
    itemKey: string, // Node item-key
    index: number, // Node index in list
    left: number, // Node left boundary position relative to list, in px
    top: number, // Node top boundary position relative to list, in px
    right: number, // Node right boundary position relative to list, in px
    bottom: number, // Node bottom boundary position relative to list, in px
  },
];
```

### `scrollBy`

```tsx
lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollBy',
    params: {
      offset: number,
    },
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();
```

Continue scrolling the distance specified by `offset` based on the existing offset, in `px`. The returned information is as follows:

```tsx
{
  "consumedX" : number,  // Distance scrolled horizontally, in px
  "consumedY" : number,  // Distance scrolled vertically, in px
  "unconsumedX" : number,  // Distance not scrolled horizontally, in px
  "unconsumedY" : number,  // Distance not scrolled vertically, in px
}
```

## More Features

### Sticky Elements

In the `<list>` component, you can achieve sticky top or sticky bottom node effects by setting the [`sticky-top`](#sticky-top) or [`sticky-bottom`](#sticky-bottom) attributes on `<list-item>`.

Ensure that the [`sticky`](#sticky) attribute of the `<list>` component is set to `true` to allow child nodes to be sticky. You can also set the [`sticky-offset`](#sticky-offet) to determine the sticky position.

```tsx
<list
  className="list-container"
  sticky={true}
  sticky-offset={50}
  list-type="single"
  span-count={1}
  scroll-orientation="vertical"
>
```

Set the [`sticky-top`](#sticky-top) or [`sticky-bottom`](#sticky-bottom) attributes on `<list-item>` to make the node sticky top or sticky bottom when scrolling. Since sticky nodes must be a full row item, you also need to set the [`full-span`](#full-span) attribute for the node.

```tsx
<list-item
  className="sticky-top-item"
  full-span={true}
  sticky-top={true}
  item-key={`list-item-${index}`}
  key={`list-item-${index}`}
/>
```

**This is an example below: list**

**Entry:** `src/sticky`
**Bundle:** `dist/sticky.lynx.bundle` | Web: `dist/sticky.web.bundle`

```tsx {16,25-26}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import "./index.scss";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      list-type="single"
      span-count={1}
      scroll-orientation="vertical"
      sticky={true}
    >
      {Array.from({ length: 40 }).map((item, index) => {
        if (index % 6 == 0) {
          return (
            <list-item
              className="sticky-top-item"
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
              full-span={true}
              sticky-top={true}
            >
              <text className="full-span-text">
                {`sticky-top-item-${index}`}
              </text>
            </list-item>
          );
        } else {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <ItemView index={index} />
            </list-item>
          );
        }
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Loading Content When Scrolling to Edge

The `<list>` component supports infinite scroll loading functionality through two key steps:

First, set an appropriate value for the [`lower-threshold-item-count`](#lower-threshold-item-count) attribute on the `<list>` component. This determines how close to the bottom the scroll needs to be before triggering the load more event. Then, bind the [`scrolltolower`](#scrolltolower) event handler which will be called when scrolling reaches the bottom threshold, allowing you to load additional data.

**This is an example below: list**

**Entry:** `src/loadmore`
```tsx {44-47}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import { type Poster, posterImgs } from "./posterImgs.jsx";

import add from "@assets/add.jpg?inline";
import left from "@assets/left_arrow.jpg?inline";

import "./index.scss";

function App() {
  const generatePosterData = (count: number) => {
    return Array.from({ length: count }, (_, i) => ({
      ...posterImgs[i % posterImgs.length],
      name: `${posterImgs[i % posterImgs.length].name} (${Math.floor(i / posterImgs.length) + 1})`,
    }));
  };
  const [contentArray, setContentArray] = useState(generatePosterData(15));
  const [hasMoreData, setHadMoreData] = useState(true);

  const addDataToLower = () => {
    console.log("addDataToLower");
    setTimeout(() => {
      setHadMoreData(false);
      setContentArray(generatePosterData(30));
    }, 1500);
  };

  return (
    <view className="container">
      <view className="header">
        <image src={left} className="nav-icon left" />
        <text className="title">Load More Data</text>
        <image src={add} className="nav-icon right" />
      </view>
      <list
        className="list-wrapper"
        list-type="single"
        span-count={1}
        scroll-orientation="vertical"
        bounces={false}
        lower-threshold-item-count={2}
        bindscrolltolower={(e) => {
          addDataToLower();
        }}
      >
        {contentArray.map((movie: Poster, index) => (
          <list-item
            item-key={movie.name + index}
            key={movie.name + index}
          >
            <view className="movie-card">
              <image className="poster-image" src={movie.poster} />
              <view className="score-container">
                <view className="score-badge">
                  <view className="score-spacer" />
                  <text className="score-value">{`list-item-${index}`}</text>
                </view>
              </view>
            </view>
          </list-item>
        ))}
        {hasMoreData
          ? (
            <list-item item-key="loading" key="loading">
              <text className="title-align">{`Load More Data...`}</text>
            </list-item>
          )
          : (
            <list-item item-key="no-more" key="no-more">
              <text className="title-align">{`No More Data`}</text>
            </list-item>
          )}
      </list>
    </view>
  );
}

root.render(<App />);

export default App;

```



### Pagination with `item-snap`

Set the `factor` to determine the parameter for paginated scrolling positioning, with a range of `[0, 1]`. `0` means `<list-item>` aligns with the top of `<list>`, and `1` means `<list-item>` aligns with the bottom of `<list>`. You can also set `offset` to add a scrolling offset on top of factor.

Example of vertical orientation:

 
**This is an example below: list**

**Entry:** `src/itemsnap`
```tsx {20}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";

import { ItemView } from "./baseView.jsx";

import "./index.scss";

function App() {
  return (
    <view className="container">
      <list
        className="list-wrapper"
        list-type="single"
        span-count={1}
        scroll-orientation="vertical"
        item-snap={{ factor: 0, offset: 0 }}
      >
        {Array.from({ length: 40 }).map((item, index) => (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        ))}
      </list>
    </view>
  );
}

root.render(<App />);

export default App;

```



Example of horizontal orientation:

**This is an example below: list**

**Entry:** `src/horizontal-snap`
```tsx {19,26}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { HorizontalView } from "./horizontalView.jsx";
import { VerticalView } from "./verticalView.jsx";

const ListContainer = () => {
  return (
    <view
      style={{
        width: "100%",
        height: "100vh",
        display: "linear",
      }}
    >
      <list
        scroll-orientation="horizontal"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "20vh",
        }}
        item-snap={{ factor: 0, offset: -20 }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <HorizontalView index={index} />
            </list-item>
          );
        })}
      </list>
      <list
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "80vh",
        }}
        item-snap={{ factor: 0, offset: 0 }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <VerticalView index={index} />
            </list-item>
          );
        })}
      </list>
    </view>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Use `z-index`

**This is an example below: list**

**Entry:** `src/zIndex`
**Bundle:** `dist/zIndex.lynx.bundle` | Web: `dist/zIndex.web.bundle`

```tsx {20,23,31}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      scroll-orientation="vertical"
      list-type="single"
      span-count={1}
      preload-buffer-count={1} // add buffer
      style={{
        width: "100%",
        height: "100vh",
        listMainAxisGap: "5px",
        padding: "10px",
        zIndex: "0",
      }}
    >
      <list-item item-key={`list-item-over-flow`} key={`list-item-list-item-over-flow`} style={{ zIndex: "1" }}>
        <view style={{ width: "100%", height: "20px", backgroundColor: "red" }}>
          <text
            style={{
              fontSize: "16px",
              paddingLeft: "6px",
              paddingTop: "6px",
              height: "40px",
              overflow: "visible",
              background: "blue",
            }}
          >
            {`overflowView:z-index:1`}
          </text>
        </view>
      </list-item>

      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Not recycle `<list-item>`

By setting the [`recyclable`](#recyclable) property of `<list-item>` to `false`, you can prevent the node from being recycled. In this example, we added an overflowing `<view>` with a background color to the first `<list-item>`. When this `<list-item>` is scrolled off the screen, we can still see the `<view>` with background color on the screen.

**This is an example below: list**

**Entry:** `src/recyclable`
**Bundle:** `dist/recyclable.lynx.bundle` | Web: `dist/recyclable.web.bundle`

```tsx {25}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import "./index.scss";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      scroll-orientation="vertical"
      list-type="flow"
      span-count={2}
    >
      <list-item
        item-key="list-item-over-flow"
        key="list-item-over-flow"
        style={{
          overflow: "visible",
          height: "40px",
          width: "100%",
        }}
        full-span={true}
        recyclable={false}
      >
        <view
          style={{
            height: "600px",
            backgroundImage: "linear-gradient(to bottom, rgba(255, 255, 0, 0.5), rgb(255, 255, 255, 0))",
          }}
        >
          <text style={{ fontSize: "15px" }}>
            {`The list item with overflow background color and recyclable: false`}
          </text>
        </view>
      </list-item>
      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index + 1}`}
            key={`list-item-${index + 1}`}
            style={{
              height: "160px",
            }}
          >
            <view
              style={{
                border: "1px solid black",
                height: "100%",
              }}
            >
              <text style={{ height: "100%", fontSize: "20px" }}>{`list-item-${index + 1}`}</text>
            </view>
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

### `<list>`

**Compatibility Table**
**Query:** `elements.list`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** list


### `<list-item>`

**Compatibility Table**
**Query:** `elements.list-item`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** list-item




---
url: /api/elements/built-in/page.md
---

# `<page>`

`<page>` element is the root node, only one `<page>` element is allowed per page. You can omit the explicit `<page>` wrapper, as the frontend framework will generate the root node by default.

## Usage

### Omitting the `<page>` Element

By default, you don't need to manually add the `<page>` element as the frontend framework generates the root node automatically.

In this case, while direct `style` and `class` attributes cannot be set explicitly, you can still style the root node using [`page`](/api/css/selectors.md#using-page-to-select-the-root-node) and [`:root`](/api/css/selectors.md#root-selector) selectors, or select it via [`SelectorQuery:selectRoot()`](/api/lynx-api/selector-query/selector-query-select-root.md).

```css
/* use `page` selector */
page {
  background-color: white;
}

/* or you can use `:root` selector */
:root {
  background-color: white;
}
```

**This is an example below: page**

**Entry:** `src/no_page_tag/`
**Bundle:** `dist/no_page_tag.lynx.bundle` | Web: `dist/no_page_tag.web.bundle`

```scss {1-3,5-8}
:root {
  background: linear-gradient(120deg, rgb(255, 53, 26), rgb(0, 235, 235));
}

page {
  border: 10px solid black;
  border-radius: 20px;
}

.title {
  font-size: 20px;
  font-weight: bold;
}

```



### Using `<page>` Element Explicitly

For more flexibility in styling the root node or binding events, you can add `<page>` as the outermost element. It works similarly to `<view>` and supports all its styles and attributes except for `width`, `height`, and `position`. See [No Direct Size Modification](#no-direct-size-modification) for details.

```jsx {3,7}
const App = () => {
  return (
    <page className="body" bindtap={handlePageClick}>
      <view style={{ width: '100%', height: '100%' }}>
        <text className="title">Page Example</text>
      </view>
    </page>
  );
};
```

Similar to `<view>`, you can add `style`, `class` and bind events to `<page>`. Note that you can only have one `<page>` element.

**This is an example below: page**

**Entry:** `src/with_page_tag/`
**Bundle:** `dist/no_page_tag.lynx.bundle` | Web: `dist/no_page_tag.web.bundle`

```tsx {13,29}
import { root } from "@lynx-js/react";
import { useState } from "react";
import "./index.scss";

const App = () => {
  const [showPopup, setShowPopup] = useState(false);

  const handlePageClick = () => {
    setShowPopup(prev => !prev);
  };

  return (
    <page className="container" bindtap={handlePageClick}>
      <view
        style={{
          width: "100%",
          height: "100%",
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <text className="title">Use Page Element Example, Click it</text>
      </view>
      {showPopup && (
        <view className="popup">
          <text className="popup-text">Click Response</text>
        </view>
      )}
    </page>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### No Direct Size Modification

The size constraints of `<page>` element are specified by its parent [native view](/guide/embed-lynx-to-native.md#Constraining-LynxView). You cannot directly modify its `width`, `height`, `left`, or `top` styles through `style` or `class`. This design allows Lynx pages to be embedded into native views, enabling better adaptation to the native app's layout flow.



---
url: /api/elements/built-in/frame.md
---

# `<frame>`

APISummary
A page element similar to HTML's `<iframe>`, which can embed a Lynx page into the current page.

## Usage Guide

The following is an example of a main page loading an embedded page via the `<frame>` element.

- The main page passes `initData` and `globalProps` to the embedded page through the `data` and `globalProps` attributes.
- The main page listens for the embedded page loading status via the `bindload` event.

### Main Page

**This is an example below: frame**

**Bundle:** `dist/frame.lynx.bundle`

```tsx {35-41}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { type InitData, root, useState } from "@lynx-js/react";
import type { FrameLoadEvent, GlobalProps } from "@lynx-js/types";

const App = () => {
  const [bindLoadEvent, setBindLoadEvent] = useState({
    url: "",
    statusCode: 0,
    statusMessage: "",
  });
  const [initData, setInitData] = useState<InitData>({
    id: 123,
    name: "Alice",
    showDetail: true,
  });
  const [globalProps, setGlobalProps] = useState<GlobalProps>({
    message: "hello globalProps!",
    status: 42,
    loaded: true,
  });
  const handleLoad = (e: FrameLoadEvent) => {
    setBindLoadEvent(e.detail);
  };

  const frameUrl = `${process.env.ASSET_PREFIX}/in_frame.lynx.bundle`;
  return (
    <view>
      <text style={{ fontSize: "20px", color: "black", padding: "10px" }}>
        Below is the inline text example in frame page.
      </text>

      <frame
        style={{ width: "100%", height: "150px", border: "3px solid red" }}
        src={frameUrl}
        data={initData}
        bindload={handleLoad}
        global-props={globalProps}
      />
      <view
        style={{
          padding: "10px",
          width: "100%",
          height: "100px",
          border: "3px solid red",
        }}
        bindtap={() => setInitData({ ...initData, showDetail: !initData.showDetail })}
      >
        <text style={{ color: "black", fontSize: "20px" }}>
          {initData.showDetail ? "Hide Detail" : "Show Detail"}
        </text>
      </view>
      <text>load url: {bindLoadEvent.url}</text>
      <text>status code: {bindLoadEvent.statusCode}</text>
      <text>status message: {bindLoadEvent.statusMessage}</text>
    </view>
  );
};

root.render(<App />);

```



### Embedded Page

**This is an example below: frame**

**Bundle:** `dist/frame.lynx.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useInitData } from "@lynx-js/react";

export function App() {
  const initData = useInitData();
  const globalProps = lynx.__globalProps;

  return (
    <view>
      <text style={{ fontSize: "30px", color: "orange" }}>I'm in frame!</text>
      <view style={{ border: "3px solid blue" }}>
        <text>{initData.id}</text>
        <text>{initData.name}</text>
        <text>{initData.showDetail ? "true" : "false"}</text>
        <text>{globalProps.message}</text>
        <text>{globalProps.status}</text>
        <text>{globalProps.loaded ? "true" : "false"}</text>
      </view>
    </view>
  );
}

root.render(<App />);

```



:::tip
The `<frame>`
 element was introduced in 3.4. To use this element, the Lynx dependency version must be upgraded to 3.4 or higher.
:::
:::caution
`<frame>` does not currently support automatic height adjustment. You need to manually set the width and height of the frame.
:::

## Attributes

### `auto-height`

Android
iOS
3.8

```tsx
// @defaultValue: false
'auto-height'?: boolean;
```

Lets the frame height follow the embedded Lynx page’s content height. When enabled, the embedded page can report its content size, and the frame uses that value as its measured height.

### `auto-width`

Android
iOS
3.8

```tsx
// @defaultValue: false
'auto-width'?: boolean;
```

Lets the frame width follow the embedded Lynx page’s content width. When enabled, the embedded page can report its content size, and the frame uses that value as its measured width.

### `data`

Android
iOS
3.4

```tsx
data?: Record<string, unknown>;
```

Passes data to the nested Lynx page within the frame.

### `global-props`

Android
iOS
3.6

```tsx
'global-props'?: Record<string, unknown>;
```

Passes
`globalProps`
to the Lynx page embedded in the frame. The embedded page can read it via
`lynx.__globalProps`
.

### `src`

Android
iOS
3.4

```tsx
src: string;
```

Sets the loading path for the frame resource.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindload`

Android
iOS
3.6

```tsx
bindload = (e: FrameLoadEvent) => {};
```

| Field         | Type   | Optional | Default | Platforms                                                    | Since | Description                  |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------------ | ----- | ---------------------------- |
| statusCode    | number | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | Frame loaded status code.    |
| statusMessage | string | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | Frame loaded status message. |
| url           | string | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | The loaded url of the frame. |

Bind frame load event callback.

## Compatibility

**Compatibility Table**
**Query:** `elements.frame`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** frame




---
url: /api/elements/built-in/input.md
---

# `<input>`

APISummary
`<input>` is used to create interactive input controls that allow users to input and edit single-line text.

:::tip

This feature requires the client to add additional dependencies. Please refer to [More Elements](/guide/start/integrate-with-existing-apps.md) for the integration method.

:::

## Usage

### Basic

Below is a basic usage example of the `<input>` component:

**This is an example below: input**

**Bundle:** `dist/autoHeight.lynx.bundle`

```tsx {13-20}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "10px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#12345678", borderRadius: "10px" }}>
        <input
          style={{ width: "100%", color: "blue", fontSize: "30px" }}
          placeholder="search"
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>
      <scroll-view
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "100%",
        }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <text style={{ fontSize: "20px", color: "gray", padding: "10px" }}>
              {`item-${index}${inputContent ? `-${inputContent}` : ""}`}
            </text>
          );
        })}
      </scroll-view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Keyboard Avoidance

`<input>` doesn't automatically avoid keyboards, but you can adjust its position by listening to keyboard events and modifying its position accordingly:

**This is an example below: input**

**Bundle:** `dist/autoHeight.lynx.bundle`

```tsx {116-123}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useLynxGlobalEventListener, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  const setNativeProps = (itemId: string, props: Record<string, unknown>) => {
    lynx
      .createSelectorQuery()
      .select(`#${itemId}`)
      .setNativeProps(props)
      .exec();
  };

  const getItemRect = (
    itemId: string,
    success: (
      left: number,
      top: number,
      right: number,
      bottom: number,
      width: number,
      height: number,
    ) => void,
    fail?: (res: any) => void,
  ) => {
    const nodeRef = itemId === "root"
      ? lynx.createSelectorQuery().selectRoot()
      : lynx.createSelectorQuery().select(`#${itemId}`);

    nodeRef
      .invoke({
        method: "boundingClientRect",
        params: {
          relativeTo: "screen",
        },
        success: res => {
          success(
            /* eslint-disable @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access*/
            res.left,
            res.top,
            res.right,
            res.bottom,
            res.width,
            res.height,
            /* eslint-enable. no-safe-argument */
          );
        },
        fail: res => {
          fail?.(res);
        },
      })
      .exec();
  };

  const keyboardChanged = (keyboardHeightInPx: number) => {
    if (keyboardHeightInPx === 0) {
      setNativeProps("panel", {
        transform: `translateY(${0}px)`,
        transition: "transform 0.1s",
      });
    } else {
      setNativeProps("panel", {
        transform: `translateY(${-keyboardHeightInPx}px)`,
        transition: "transform 0.3s",
      });
    }
  };

  useLynxGlobalEventListener(
    "keyboardstatuschanged",
    (status: unknown, keyboardHeight: unknown) => {
      console.log(status);
      console.log(keyboardHeight);
      // @ts-ignore
      keyboardChanged(status === "on" ? keyboardHeight : 0);
    },
  );

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "10px" }}>
      <scroll-view
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "100%",
        }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <text style={{ fontSize: "20px", color: "gray", padding: "10px" }}>
              {`item-${index}${inputContent ? `-${inputContent}` : ""}`}
            </text>
          );
        })}
      </scroll-view>
      <view
        id="panel"
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "white",
          height: "100px",
          background: "lightgray",
          border: "1px solid black",
          position: "absolute",
          bottom: "0px",
        }}
      >
        {
          <input
            style={{ width: "100%", color: "blue", fontSize: "30px" }}
            placeholder="search"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

### `android-fullscreen-mode`

Android
3.4

```tsx
// @defaultValue: true
'android-fullscreen-mode'?: boolean;
```

Whether to enter the full-screen input mode when in landscape screen, in which the keyboard and input box will take up the entire screen

### `confirm-type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 'send'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

Android
iOS
Harmony
3.5

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `input-filter`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

iOS
3.4

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

iOS
3.4

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `maxlength`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `placeholder`

Android
iOS
Harmony
3.4

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: "text"
type?: 'number' | 'text' | 'digit' | 'password' | 'tel' | 'email';
```

Input content type

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindblur`

Android
iOS
Harmony
3.4

```tsx
bindblur = (e: InputBlurEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Blurred

### `bindconfirm`

Android
iOS
Harmony
3.4

```tsx
bindconfirm = (e: InputConfirmEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Confirm button clicked

### `bindfocus`

Android
iOS
Harmony
3.4

```tsx
bindfocus = (e: InputFocusEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Focused

### `bindinput`

Android
iOS
Harmony
3.4

```tsx
bindinput = (e: InputInputEvent) => {};
```

| Field          | Type    | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| isComposing    | boolean | Yes      | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Is composing or not                 |
| selectionEnd   | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |
| value          | string  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content                       |

Input content changed

### `bindselection`

Android
iOS
Harmony
3.4

```tsx
bindselection = (e: InputSelectionEvent) => {};
```

| Field          | Type   | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| selectionEnd   | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |

Input selection changed

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `blur`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'blur',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Release focus

### `focus`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getValue',
      success: Callback<{
        /**
         * Is composing or not, iOS only
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        isComposing: boolean;
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Begin position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get input content

### `setSelectionRange`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setSelectionRange',
      params: {
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Start position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set selection range

### `setValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setValue',
      params: {
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set input content

## Compatibility

**Compatibility Table**
**Query:** `elements.input`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.4 | - |
| Clay iOS | 3.4 | - |
| Clay Windows | 3.4 | - |
| Clay macOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** input




---
url: /api/elements/built-in/textarea.md
---

# `<textarea>`

APISummary
`<textarea>` is used to create interactive input controls that allow users to input and edit multi-line text.

:::tip

This feature requires the client to add additional dependencies. Please refer to [More Elements](/guide/start/integrate-with-existing-apps.md) for the integration method.

:::

## Usage

### Basic

Below is a basic usage example of the `<textarea>` component:

**This is an example below: textarea**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#87654321", borderRadius: "10px" }}>
        <textarea
          style={{ width: "100%", color: "blue", fontSize: "50px" }}
          placeholder="Title"
          maxlines={2}
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>

      <view
        style={{
          width: "100%",
          padding: "10px",
          marginTop: "20px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        {
          <textarea
            style={{ width: "100%", height: "300px", fontSize: "30px" }}
            placeholder="Content"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Custom Placeholder Style

`<textarea>` can customize its style using the `::placeholder` pseudo-element:

**This is an example below: textarea**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import "./index.scss";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <text style={{ fontSize: "15px" }}>Customized Placeholder And Caret Color</text>
      <view
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "#87654321",
          borderRadius: "10px",
          marginTop: "20px",
        }}
      >
        <textarea
          style={{ width: "100%" }}
          placeholder=".textarea::placeholder {
                              color: oragne
                            }"
          class="textarea"
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

### `android-fullscreen-mode`

Android
3.4

```tsx
// @defaultValue: true
'android-fullscreen-mode'?: boolean;
```

Whether to enter the full-screen input mode when in landscape screen, in which the keyboard and input box will take up the entire screen

### `bounces`

iOS
3.4

```tsx
// @defaultValue: true
bounces?: boolean;
```

Bounce effect for iOS

### `confirm-type`

iOS
Harmony
3.4

```tsx
// @defaultValue: 'done'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

Android
iOS
Harmony
3.5

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `enable-scroll-bar`

Android
iOS
3.6

```tsx
// @defaultValue: false
'enable-scroll-bar'?: boolean;
```

Whether to show scroll bar, on HarmonyOS, the scroll bar will always be shown

### `input-filter`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

iOS
3.4

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

iOS
3.4

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `line-spacing`

Android
iOS
3.4

```tsx
// @defaultValue: undefined
'line-spacing'?: number | any | any;
```

Line spacing

### `maxlength`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `maxlines`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
maxlines?: number;
```

Max input lines

### `placeholder`

Android
iOS
Harmony
3.4

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

Android
iOS
3.4

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: "text"
type?: 'number' | 'text' | 'digit' | 'tel' | 'email';
```

Input content type

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindblur`

Android
iOS
Harmony
3.4

```tsx
bindblur = (e: TextAreaBlurEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Blurred

### `bindconfirm`

Android
iOS
Harmony
3.4

```tsx
bindconfirm = (e: TextAreaConfirmEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Confirm button clicked, only work when confirm-type is defined

### `bindfocus`

Android
iOS
Harmony
3.4

```tsx
bindfocus = (e: TextAreaFocusEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Focused

### `bindinput`

Android
iOS
Harmony
3.4

```tsx
bindinput = (e: TextAreaInputEvent) => {};
```

| Field          | Type    | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| isComposing    | boolean | Yes      | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Is composing or not                 |
| selectionEnd   | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |
| value          | string  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content                       |

Input content changed

### `bindselection`

Android
iOS
Harmony
3.4

```tsx
bindselection = (e: TextAreaSelectionChangeEvent) => {};
```

| Field          | Type   | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| selectionEnd   | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |

Input selection changed

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `blur`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'blur',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Release focus

### `focus`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getValue',
      success: Callback<{
        /**
         * Is composing or not, iOS only
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        isComposing: boolean;
        /**
         * End position of the cursor
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Begin position of the cursor
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get input content

### `setSelectionRange`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setSelectionRange',
      params: {
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Start position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set selection range

### `setValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setValue',
      params: {
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set input content

## Compatibility

**Compatibility Table**
**Query:** `elements.textarea`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.4 | - |
| Clay iOS | 3.4 | - |
| Clay Windows | 3.4 | - |
| Clay macOS | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** textarea




---
url: /api/elements/built-in/overlay.md
---

# `<overlay>`

APISummary
`<overlay>` is a container that does not participate in page layout. It occupies no space itself and requires neither width nor height.

When rendered, the content inside `<overlay>` is completely detached from the Lynx document flow and promoted to a rendering layer outside of Lynx.

By default, the only child of `<overlay>` uses the screen dimensions as its width and height. It is recommended to treat it as an independent drawing container for the full overlay content.

:::info

**Use cases**

- When embedding a Lynx sub-module in a native page, use `<overlay>` to build a dialog that covers the entire page.
- When the page is built entirely with Lynx, **do not** use `<overlay>`; simply use `position: fixed` instead.

:::

## Usage

### Requirements

- `<overlay>` **can only have one direct child node**.
- `<overlay>` **itself must set `position: fixed`**.

### Recommended Usage

- Use the only child node of `<overlay>` as the backdrop container:
  - Even if the background is transparent, it is still recommended to render it.
  - Explicitly set the size: **`width: 100%; height: 100%`**.
  - Explicitly create an independent stacking context: **`z-index: 0`**.

```tsx
<overlay class="overlay">
  <view class="backdrop">
    // Dialog Content
    <Dialog class="dialog-content" />
  </view>
</overlay>
```

```css
.overlay {
  overflow: visible;
  position: fixed;
}

.backdrop {
  width: 100%;
  height: 100%;
  z-index: 0;
}
```

- To adjust the dialog’s visual size, control it inside the backdrop (e.g. with `margin`) instead of changing the backdrop’s own size.

```css
.dialog-content {
  margin: 100px;
  position: absolute;
}
```

**This is an example below: overlay**

**Bundle:** `dist/base.lynx.bundle`

```tsx {19-72}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [visible, setVisible] = useState(true);

  return (
    <view
      style={{
        linearOrientation: "vertical",
        width: "100%",
        height: "100%",
        padding: "10px",
      }}
    >
      <overlay visible={visible} style={{ position: "fixed" }}>
        <view
          style={{
            width: "100%",
            height: "100%",
            backgroundColor: "rgba(0, 0, 0, 0.5)",
            display: "flex",
            justifyContent: "center",
            alignItems: "center",
          }}
          bindtap={() => setVisible(false)}
        >
          <view
            catchtap={() => console.log("tap inside the overlay")}
            style={{
              width: "80%",
              height: "50%",
              backgroundColor: "white",
              display: "flex",
              justifyContent: "center",
              alignItems: "center",
              borderRadius: "10px",
            }}
          >
            <text
              style={{
                fontSize: "30px",
                color: "red",
                textAlign: "center",
                width: "max-content",
              }}
            >
              Biz Content
            </text>
            <text
              catchtap={() => setVisible(false)}
              style={{
                position: "absolute",
                fontSize: "20px",
                color: "white",
                textAlign: "center",
                left: "20px",
                right: "20px",
                bottom: "20px",
                backgroundColor: "green",
                padding: "10px",
                borderRadius: "5px",
              }}
            >
              Dismiss
            </text>
          </view>
        </view>
      </overlay>
      <view
        bindtap={() => setVisible(true)}
        style={{
          width: "100%",
          padding: "10px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        <text
          style={{
            fontSize: "30px",
            color: "red",
            textAlign: "center",
            width: "max-content",
          }}
        >
          Open the overlay
        </text>
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

### `ios-enable-swipe-back`

iOS
```tsx
// @defaultValue: false
'ios-enable-swipe-back'?: boolean;
```

When overlay is displayed, 'true' allows swiping right to close the current page, 'false' does not allow it

### `level`

Android
iOS
Clay
Harmony
```tsx
// @defaultValue: 1
level?: 4 | 2 | 1 | 3;
```

Introduces the concept of layers, which are divided into four levels. The larger the layer, the closer it is to the bottom. By default, it is the first level. The layers are arranged in order from 1 to 4. The displayed layer is specified and is not affected by the order of display. Within each layer, the arrangement is based on the 'last in, first out' logic. The layer cannot be dynamically adjusted when the overlay is displayed, and can only be adjusted when it is hidden.     \*

### `mode`

iOS
```tsx
// @defaultValue: 'window'
mode?: string;
```

Specifies the level at which the overlay content resides on iOS. window: Mounted on the window, the top level of the app; top: Mounted on the topViewController; page: Mounted on UINavigationController; others: customize the name of class in the client.

### `visible`

Android
iOS
Clay
Harmony
```tsx
// @defaultValue: false
visible?: boolean;
```

Control whether the overlay is displayed

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `binddismissoverlay`

Android
iOS
Clay
Harmony
```tsx
binddismissoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is hidden.

### `binderror`

Android
2.18

```tsx
binderror = (e: OverlayErrorEvent) => {};
```

| Field     | Type   | Optional | Default | Platforms       | Since | Description                                                                                                                                                  |
| --------- | ------ | -------- | ------- | --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| errorCode | string | No       | –       | <AndroidOnly /> |       | Error code: 0 - Display normally; non-0 - Unable to display, you can try to solve it by using the preloading scheme mentioned below for adapting containers. |
| errorMsg  | string | No       | –       | <AndroidOnly /> |       | Error message                                                                                                                                                |

Callback when touch on the overlay

### `bindoverlaytouch`

Android
iOS
Clay
```tsx
bindoverlaytouch = (e: OverlayTouchEvent) => {};
```

| Field | Type              | Optional | Default | Platforms                                | Since | Description                              |
| ----- | ----------------- | -------- | ------- | ---------------------------------------- | ----- | ---------------------------------------- |
| state | OverlayTouchState | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | Touch state                              |
| x     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | x position relative to the window, in px |
| y     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | y position relative to the window, in px |

Callback when touch on the overlay

### `bindrequestclose`

Android
Clay
Harmony
```tsx
bindrequestclose = (e: BaseEvent) => {};
```

Callback when the back button is clicked.

### `bindshowoverlay`

Android
iOS
Clay
Harmony
```tsx
bindshowoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is displayed

## Compatibility

**Compatibility Table**
**Query:** `elements.overlay`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ✅ Yes | ⚠️ Partial implementation |

**Description:** overlay




---
url: /api/elements/built-in/svg.md
---

# `<svg>`

APISummary
`<svg>` is the cornerstone element for embedding Scalable Vector Graphics (SVG) directly within your markup. It lets you create crisp, resolution-independent graphics, from simple icons to complex data visualizations, that scale flawlessly across every screen size and pixel density.

Lynx SVG is designed for performant static rendering. Instead of creating individual element nodes on the main thread for each SVG tag, it offloads parsing to a background thread and renders the entire graphic as a single native view, reducing both main-thread parsing time and element node count. It covers 17 commonly used SVG tags and over 40 attributes, sufficient for the vast majority of real-world SVG assets.

## Usage

### Basic

Below is a basic usage example of the `<svg>` element:

**This is an example below: svg**

**Bundle:** `dist/base.lynx.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";

const logoContent = `<svg width="320" height="320" viewBox="0 0 320 320" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
  <linearGradient id="panelFill" x1="28" y1="28" x2="292" y2="292" gradientUnits="userSpaceOnUse">
    <stop offset="0%" stop-color="#26292D" stop-opacity="0.72"/>
    <stop offset="55%" stop-color="#4B4F56" stop-opacity="0.62"/>
    <stop offset="100%" stop-color="#8B9098" stop-opacity="0.52"/>
  </linearGradient>
</defs>
<rect x="28" y="28" width="264" height="264" rx="40" fill="url(#panelFill)"/>
<rect x="28.5" y="28.5" width="263" height="263" rx="39.5" stroke="#FFFFFF" stroke-opacity="0.08"/>
<g transform="translate(100 100) scale(6)" opacity="0.98">
  <path fill-rule="evenodd" clip-rule="evenodd" d="M5.19683 4.42475L2.58326 6.22507C2.29923 6.42072 2.10258 6.71472 2.0335 7.04698L1.77798 8.27604C1.76443 8.34121 1.73438 8.40204 1.69058 8.45301L0.504615 10.0077C0.344941 10.1935 0.348791 10.6871 0.786137 11.0031C0.953848 11.1493 1.17807 11.477 1.43312 11.8497L1.43312 11.8497C1.97313 12.639 2.65131 13.6302 3.22376 13.5272C4.03382 13.2426 5.02541 13.1516 5.78673 13.5272C7.2667 14.8049 6.90331 15.983 6.38234 17.672C6.17271 18.3516 5.93755 19.114 5.78673 19.9988C6.49755 17.4117 8.09592 14.4069 10.9781 13.3874C10.4588 12.9632 9.39906 12.5691 8.46129 12.4742C8.46129 12.4742 11.3423 10.0077 14.8957 8.87434C12.4151 2.97197 8.32052 0.151295 8.32052 0.151295C8.11187 -0.10677 7.69054 -0.0221092 7.6036 0.295351C7.53376 1.22845 7.41798 1.86295 7.22685 2.46105L5.78673 0.799291C5.6363 0.61794 5.33557 0.722655 5.33707 0.955861C5.5809 2.31136 5.54668 3.07222 5.19683 4.42475ZM6.21052 4.30085L6.21912 4.3003C6.23794 4.29909 6.25646 4.29664 6.27456 4.29302L6.21052 4.30085ZM8.15541 1.25793C9.1423 2.96321 9.58937 3.932 9.74102 5.73998C8.6912 5.14364 8.23382 4.99187 7.46183 4.99565C7.91215 3.62621 8.04976 2.8016 8.15541 1.25793Z" fill="white"/>
  <path d="M14.4988 13.9228C10.479 14.8427 8.19556 16.2278 6.44922 19.9994C9.58406 14.7399 19.0737 15.6805 19.0737 15.6805C18.8964 14.8214 17.0097 13.183 15.7688 12.1782C15.7688 12.1782 16.7699 10.9474 18.983 10.3244C18.983 10.3244 14.728 10.5709 12.2508 11.9084C13.0533 12.3319 14.0812 13.0467 14.4988 13.9228Z" fill="white"/>
</g>
</svg>`;

const App = () => {
  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#0f0f10",
        padding: "32px",
      }}
    >
      <svg content={logoContent} style={{ width: "320px", height: "320px" }} />
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Supported SVG Tags

The following SVG tags are fully supported:

| Tag            | Description                                     |
| -------------- | ----------------------------------------------- |
| circle         | Defines a circle.                               |
| clipPath       | Defines a clipping path.                        |
| defs           | Container for definitions that can be reused.   |
| text           | Defines a text element.                         |
| ellipse        | Defines an ellipse.                             |
| g              | Groups elements together.                       |
| image          | Embeds raster images.                           |
| line           | Defines a straight line.                        |
| linearGradient | Defines a linear gradient.                      |
| path           | Defines a path.                                 |
| polygon        | Defines a closed shape with straight sides.     |
| polyline       | Defines a series of connected straight lines.   |
| radialGradient | Defines a radial gradient.                      |
| rect           | Defines a rectangle.                            |
| stop           | Defines a gradient stop.                        |
| svg            | Root SVG element.                               |
| use            | References and reuses shapes defined elsewhere. |

### Supported SVG Attributes

The following attributes can be applied to the above tags:

| Attribute           | Description                                              |
| ------------------- | -------------------------------------------------------- |
| xlink:href          | Reference to a resource (deprecated, prefer href).       |
| style               | Inline CSS styling.                                      |
| points              | List of points for polygon/polyline.                     |
| offset              | Gradient stop offset.                                    |
| font-size           | Text font size.                                          |
| id                  | Unique identifier.                                       |
| xmlns               | XML namespace.                                           |
| clip-path           | Clipping path reference.                                 |
| clip-rule           | Clipping rule for fill vs. stroke.                       |
| clipPathUnits       | Units for clipPath.                                      |
| color               | Foreground color.                                        |
| cx, cy              | Center coordinates for circles/ellipses.                 |
| d                   | Path data.                                               |
| fill                | Fill color/paint.                                        |
| fill-opacity        | Fill transparency.                                       |
| fill-rule           | Fill rule for intersecting paths.                        |
| fx, fy              | Focal point for radial gradients.                        |
| gradientTransform   | Transform matrix for gradients.                          |
| gradientUnits       | Coordinate system for gradients.                         |
| height, width       | Dimensions.                                              |
| href                | Hyperlink reference (modern replacement for xlink:href). |
| opacity             | Overall transparency.                                    |
| preserveAspectRatio | Aspect ratio behavior on scaling.                        |
| r                   | Radius for circles.                                      |
| rx, ry              | Corner radii for rounded rectangles.                     |
| spreadMethod        | How gradient fills beyond defined range.                 |
| stop-color          | Gradient stop color.                                     |
| stop-opacity        | Gradient stop transparency.                              |
| stroke              | Stroke color/paint.                                      |
| stroke-dasharray    | Dash pattern for strokes.                                |
| stroke-dashoffset   | Offset for dash pattern.                                 |
| stroke-linecap      | Shape at the end of open subpaths.                       |
| stroke-linejoin     | Shape at path corners.                                   |
| stroke-miterlimit   | Limit for miter joins.                                   |
| stroke-opacity      | Stroke transparency.                                     |
| stroke-width        | Stroke thickness.                                        |
| transform           | Transformation matrix.                                   |
| viewBox             | Coordinate system and aspect ratio.                      |
| x, y                | Position coordinates.                                    |
| x1, y1, x2, y2      | Line endpoints.                                          |

## Attributes

### `content`

Android
iOS
Clay
Harmony
```tsx
content?: string;
```

SVG XML content

### `src`

Android
iOS
Clay
Harmony
```tsx
src?: string;
```

SVG resource URL

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindload`

Android
iOS
Clay
Harmony
```tsx
bindload = (e: BaseEvent) => {};
```

SVG Loaded

## Compatibility

**Compatibility Table**
**Query:** `elements.svg`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.7 | - |
| iOS | 3.7 | - |
| HarmonyOS | 3.7 | - |
| Clay Android | 3.7 | - |
| Clay iOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Clay macOS | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** svg




---
url: /api/elements/built-in/refresh.md
---

# `<refresh>`

APISummary
`<refresh>` element provides a pull-to-refresh gesture that reveals a customizable header view while new data is being fetched.

It fires the `refresh` event when the user pulls down past a configurable threshold, allowing you to trigger asynchronous updates and automatically hide the header once the operation completes.

## Usage

- `<refresh>` only supports vertical pull-to-refresh gestures.
- It accepts up to two direct children: `<refresh-header>` and `<view>` has vertically scrollable inside.

### Pull to refresh

Define the refresh effect through `<refresh-header>`, and set `enable-refresh` to true for `<refresh>`.

1. Pull to refresh: Drag down or call `autoStartRefresh` to lock the `<refresh-header>` at the top and fire the `startrefresh` event.

2. Finish loading: Call `finishRefresh` to animate the `<refresh-header>` out of view.

**This is an example below: refresh**

**Bundle:** `dist/base.lynx.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from "@lynx-js/react";
import type { NodesRef } from "@lynx-js/types";

const App = () => {
  const refreshViewRef = useRef<NodesRef>(null);
  const [refreshCount, setRefreshCount] = useState<number>(0);
  const [items, setItems] = useState<number[]>([0, 1, 2, 4, 5, 6, 7, 8]);
  const onStartRefresh = () => {
    console.log("on start refresh");
    setTimeout(() => {
      refreshViewRef.current?.invoke({
        method: "finishRefresh",
      }).exec();
      setItems([0, 1, 2, 4, 5, 6, 7, 8]);
      setRefreshCount(refreshCount + 1);
    }, 1000);
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        flexDirection: "column",
        backgroundColor: "white",
      }}
    >
      {
        // @ts-expect-error type error


          <refresh ref={refreshViewRef} style={{ width: "100%", height: "100%" }} bindstartrefresh={onStartRefresh}>
            <refresh-header
              style={{
                width: "100%",
                height: "50px",
                position: "absolute",
                justifyContent: "center",
                alignItems: "center",
                backgroundColor: "red",
              }}
            >
              <text style={{ fontSize: "30px" }}>Refreshing...</text>
            </refresh-header>
            <list style={{ width: "100%", height: "100%" }} scroll-orientation="vertical" bounces={true}>
              {items.map((item, index) => {
                return (
                  <list-item key={item + ""} item-key={item + ""}>
                    <text
                      style={{
                        "height": "200px",
                        width: "100%",
                        fontSize: "100px",
                        color: refreshCount % 2 === 0 ? "red" : "green",
                        padding: "25px",
                        textAlign: "center",
                        border: "1px solid black",
                      }}
                    >
                      {`item-${index}`}
                    </text>
                  </list-item>
                );
              })}
            </list>
          </refresh>

      }
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Attributes

### `enable-refresh`

Android
iOS
Harmony
```tsx
// @defaultValue: true
'enable-refresh'?: boolean;
```

Determines if dragging down or calling autoStartRefresh can trigger the startrefresh event.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindheaderoffset`

Android
iOS
Harmony
```tsx
bindheaderoffset = (e: RefreshHeaderOffsetEvent) => {};
```

| Field         | Type    | Optional | Default | Platforms                                   | Since | Description                                                    |
| ------------- | ------- | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------------------- |
| isDragging    | boolean | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates if  `<refresh-header>`  is being dragged             |
| offsetPercent | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | The ratio of the pull-down movement distance to its own height |

Triggered during movement when
`<refresh-header>`
is exposed.

### `bindrefreshstatechange`

Android
iOS
Harmony
```tsx
bindrefreshstatechange = (e: RefreshStateChangeEvent) => {};
```

| Field | Type         | Optional | Default | Platforms                                   | Since | Description                                        |
| ----- | ------------ | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------- |
| state | RefreshState | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates if  `<refresh-header>`  is being dragged |

Triggered when
`<refresh-header>`
state changes.

### `bindstartrefresh`

Android
iOS
Harmony
```tsx
bindstartrefresh = (e: RefreshStartRefreshEvent) => {};
```

| Field    | Type    | Optional | Default | Platforms                                   | Since | Description                                                          |
| -------- | ------- | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------------------------- |
| isManual | boolean | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates whether the startrefresh event is triggered by manual drag |

Triggered when enable-refresh is true, and dragging down or calling autoStartRefresh (enters refresh state).

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `autoStartRefresh`

Android
iOS
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'autoStartRefresh',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

When enable-refresh is true, call this method to expose the entire
`<refresh-header>`
, triggering the startrefresh event, after which
`<refresh-header>`
will attach to the top edge of the refresh's viewport.

### `finishRefresh`

Android
iOS
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'finishRefresh',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Called after the startrefresh event to end the refresh state, making
`<refresh-header>`
rebound.

## Compatibility

**Compatibility Table**
**Query:** `elements.refresh`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |
| HarmonyOS | 3.8 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | 3.8 | - |

**Description:** refresh




---
url: /api/elements/built-in/title-bar-view.md
---

# `<title-bar-view>`
 Clay Windows Clay macOS
APISummary
`<title-bar-view>` is designed to customize the draggable area of the window.

## Usage

**This is an example below: title-bar-view**

**Bundle:** `dist/base.lynx.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from "@lynx-js/react";

const App = () => {
  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        flexDirection: "column",
        backgroundColor: "white",
      }}
    >
      <title-bar-view moveable={true} style={{ width: "100%", height: "50px", backgroundColor: "red" }}>
        <text style={{ fontSize: "30px" }}>Title Bar View, drag me</text>
      </title-bar-view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



`<title-bar-view>` is similar to the `app-region` style on the web and allows developers to customize the draggable area of the window.

## Attributes

### `moveable`

Clay Windows
Clay macOS
```tsx
// @defaultValue: false
moveable?: boolean;
```

When set to `true`, dragging the title bar view moves the window.

## Compatibility

**Compatibility Table**
**Query:** `elements.title-bar-view`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | 3.8 | - |
| Clay macOS | 3.8 | - |
| Web | ❌ No | - |

**Description:** title-bar-view




---
url: /api/css/properties.md
---

# Overview

## Properties

### [-x-auto-font-size-line-ranges](/api/css/properties/-x-auto-font-size-line-ranges.md)

### [-x-auto-font-size-preset-sizes](/api/css/properties/-x-auto-font-size-preset-sizes.md)

### [-x-auto-font-size](/api/css/properties/-x-auto-font-size.md)

### [-x-handle-color](/api/css/properties/-x-handle-color.md)

### [-x-handle-size](/api/css/properties/-x-handle-size.md)

### [align-content](/api/css/properties/align-content.md)

### [align-items](/api/css/properties/align-items.md)

### [align-self](/api/css/properties/align-self.md)

### [animation-delay](/api/css/properties/animation-delay.md)

### [animation-direction](/api/css/properties/animation-direction.md)

### [animation-duration](/api/css/properties/animation-duration.md)

### [animation-fill-mode](/api/css/properties/animation-fill-mode.md)

### [animation-iteration-count](/api/css/properties/animation-iteration-count.md)

### [animation-name](/api/css/properties/animation-name.md)

### [animation-play-state](/api/css/properties/animation-play-state.md)

### [animation-timing-function](/api/css/properties/animation-timing-function.md)

### [animation](/api/css/properties/animation.md)

### [aspect-ratio](/api/css/properties/aspect-ratio.md)

### [background-clip](/api/css/properties/background-clip.md)

### [background-color](/api/css/properties/background-color.md)

### [background-image](/api/css/properties/background-image.md)

### [background-origin](/api/css/properties/background-origin.md)

### [background-position](/api/css/properties/background-position.md)

### [background-repeat](/api/css/properties/background-repeat.md)

### [background-size](/api/css/properties/background-size.md)

### [background](/api/css/properties/background.md)

### [border-bottom-color](/api/css/properties/border-bottom-color.md)

### [border-bottom-left-radius](/api/css/properties/border-bottom-left-radius.md)

### [border-bottom-right-radius](/api/css/properties/border-bottom-right-radius.md)

### [border-bottom-style](/api/css/properties/border-bottom-style.md)

### [border-bottom-width](/api/css/properties/border-bottom-width.md)

### [border-bottom](/api/css/properties/border-bottom.md)

### [border-color](/api/css/properties/border-color.md)

### [border-end-end-radius](/api/css/properties/border-end-end-radius.md)

### [border-end-start-radius](/api/css/properties/border-end-start-radius.md)

### [border-inline-end-color](/api/css/properties/border-inline-end-color.md)

### [border-inline-end-style](/api/css/properties/border-inline-end-style.md)

### [border-inline-end-width](/api/css/properties/border-inline-end-width.md)

### [border-inline-start-color](/api/css/properties/border-inline-start-color.md)

### [border-inline-start-style](/api/css/properties/border-inline-start-style.md)

### [border-inline-start-width](/api/css/properties/border-inline-start-width.md)

### [border-left-color](/api/css/properties/border-left-color.md)

### [border-left-style](/api/css/properties/border-left-style.md)

### [border-left-width](/api/css/properties/border-left-width.md)

### [border-left](/api/css/properties/border-left.md)

### [border-radius](/api/css/properties/border-radius.md)

### [border-right-color](/api/css/properties/border-right-color.md)

### [border-right-style](/api/css/properties/border-right-style.md)

### [border-right-width](/api/css/properties/border-right-width.md)

### [border-right](/api/css/properties/border-right.md)

### [border-start-end-radius](/api/css/properties/border-start-end-radius.md)

### [border-start-start-radius](/api/css/properties/border-start-start-radius.md)

### [border-style](/api/css/properties/border-style.md)

### [border-top-color](/api/css/properties/border-top-color.md)

### [border-top-left-radius](/api/css/properties/border-top-left-radius.md)

### [border-top-right-radius](/api/css/properties/border-top-right-radius.md)

### [border-top-style](/api/css/properties/border-top-style.md)

### [border-top-width](/api/css/properties/border-top-width.md)

### [border-top](/api/css/properties/border-top.md)

### [border-width](/api/css/properties/border-width.md)

### [border](/api/css/properties/border.md)

### [bottom](/api/css/properties/bottom.md)

### [box-shadow](/api/css/properties/box-shadow.md)

### [box-sizing](/api/css/properties/box-sizing.md)

### [clip-path](/api/css/properties/clip-path.md)

### [color](/api/css/properties/color.md)

### [column-gap (grid-column-gap)](/api/css/properties/column-gap.md)

### [Custom properties (`--*`): CSS variables](/api/css/properties/css-variable.md)

### [cursor](/api/css/properties/cursor.md)

### [direction](/api/css/properties/direction.md)

### [display](/api/css/properties/display.md)

### [filter](/api/css/properties/filter.md)

### [flex-basis](/api/css/properties/flex-basis.md)

### [flex-direction](/api/css/properties/flex-direction.md)

### [flex-flow](/api/css/properties/flex-flow.md)

### [flex-grow](/api/css/properties/flex-grow.md)

### [flex-shrink](/api/css/properties/flex-shrink.md)

### [flex-wrap](/api/css/properties/flex-wrap.md)

### [flex](/api/css/properties/flex.md)

### [font-family](/api/css/properties/font-family.md)

### [font-feature-settings](/api/css/properties/font-feature-settings.md)

### [font-optical-sizing](/api/css/properties/font-optical-sizing.md)

### [font-size](/api/css/properties/font-size.md)

### [font-style](/api/css/properties/font-style.md)

### [font-variation-settings](/api/css/properties/font-variation-settings.md)

### [font-weight](/api/css/properties/font-weight.md)

### [gap](/api/css/properties/gap.md)

### [grid-auto-columns](/api/css/properties/grid-auto-columns.md)

### [grid-auto-flow](/api/css/properties/grid-auto-flow.md)

### [grid-auto-rows](/api/css/properties/grid-auto-rows.md)

### [grid-column-end](/api/css/properties/grid-column-end.md)

### [grid-column-span](/api/css/properties/grid-column-span.md)

### [grid-column-start](/api/css/properties/grid-column-start.md)

### [grid-row-end](/api/css/properties/grid-row-end.md)

### [grid-row-span](/api/css/properties/grid-row-span.md)

### [grid-row-start](/api/css/properties/grid-row-start.md)

### [grid-template-columns](/api/css/properties/grid-template-columns.md)

### [grid-template-rows](/api/css/properties/grid-template-rows.md)

### [height](/api/css/properties/height.md)

### [image-rendering](/api/css/properties/image-rendering.md)

### [inset-inline-end](/api/css/properties/inset-inline-end.md)

### [inset-inline-start](/api/css/properties/inset-inline-start.md)

### [justify-content](/api/css/properties/justify-content.md)

### [justify-items](/api/css/properties/justify-items.md)

### [justify-self](/api/css/properties/justify-self.md)

### [left](/api/css/properties/left.md)

### [letter-spacing](/api/css/properties/letter-spacing.md)

### [line-height](/api/css/properties/line-height.md)

### [linear-cross-gravity](/api/css/properties/linear-cross-gravity.md)

### [linear-direction](/api/css/properties/linear-direction.md)

### [linear-gravity](/api/css/properties/linear-gravity.md)

### [linear-layout-gravity](/api/css/properties/linear-layout-gravity.md)

### [linear-weight-sum](/api/css/properties/linear-weight-sum.md)

### [linear-weight](/api/css/properties/linear-weight.md)

### [margin-bottom](/api/css/properties/margin-bottom.md)

### [margin-inline-end](/api/css/properties/margin-inline-end.md)

### [margin-inline-start](/api/css/properties/margin-inline-start.md)

### [margin-left](/api/css/properties/margin-left.md)

### [margin-right](/api/css/properties/margin-right.md)

### [margin-top](/api/css/properties/margin-top.md)

### [margin](/api/css/properties/margin.md)

### [mask-image](/api/css/properties/mask-image.md)

### [mask](/api/css/properties/mask.md)

### [max-height](/api/css/properties/max-height.md)

### [max-width](/api/css/properties/max-width.md)

### [min-height](/api/css/properties/min-height.md)

### [min-width](/api/css/properties/min-width.md)

### [opacity](/api/css/properties/opacity.md)

### [order](/api/css/properties/order.md)

### [overflow-x](/api/css/properties/overflow-x.md)

### [overflow-y](/api/css/properties/overflow-y.md)

### [overflow](/api/css/properties/overflow.md)

### [padding-bottom](/api/css/properties/padding-bottom.md)

### [padding-inline-end](/api/css/properties/padding-inline-end.md)

### [padding-inline-start](/api/css/properties/padding-inline-start.md)

### [padding-left](/api/css/properties/padding-left.md)

### [padding-right](/api/css/properties/padding-right.md)

### [padding-top](/api/css/properties/padding-top.md)

### [padding](/api/css/properties/padding.md)

### [perspective](/api/css/properties/perspective.md)

### [pointer-events](/api/css/properties/pointer-events.md)

### [position](/api/css/properties/position.md)

### [relative-align-bottom](/api/css/properties/relative-align-bottom.md)

### [relative-align-inline-end](/api/css/properties/relative-align-inline-end.md)

### [relative-align-inline-start](/api/css/properties/relative-align-inline-start.md)

### [relative-align-left](/api/css/properties/relative-align-left.md)

### [relative-align-right](/api/css/properties/relative-align-right.md)

### [relative-align-top](/api/css/properties/relative-align-top.md)

### [relative-bottom-of](/api/css/properties/relative-bottom-of.md)

### [relative-center](/api/css/properties/relative-center.md)

### [relative-id](/api/css/properties/relative-id.md)

### [relative-inline-end-of](/api/css/properties/relative-inline-end-of.md)

### [relative-inline-start-of](/api/css/properties/relative-inline-start-of.md)

### [relative-layout-once](/api/css/properties/relative-layout-once.md)

### [relative-left-of](/api/css/properties/relative-left-of.md)

### [relative-right-of](/api/css/properties/relative-right-of.md)

### [relative-top-of](/api/css/properties/relative-top-of.md)

### [right](/api/css/properties/right.md)

### [row-gap (grid-row-gap)](/api/css/properties/row-gap.md)

### [text-align](/api/css/properties/text-align.md)

### [text-decoration](/api/css/properties/text-decoration.md)

### [text-indent](/api/css/properties/text-indent.md)

### [text-overflow](/api/css/properties/text-overflow.md)

### [text-shadow](/api/css/properties/text-shadow.md)

### [text-stroke-color](/api/css/properties/text-stroke-color.md)

### [text-stroke-width](/api/css/properties/text-stroke-width.md)

### [text-stroke](/api/css/properties/text-stroke.md)

### [top](/api/css/properties/top.md)

### [transform-origin](/api/css/properties/transform-origin.md)

### [transform](/api/css/properties/transform.md)

### [transition-delay](/api/css/properties/transition-delay.md)

### [transition-duration](/api/css/properties/transition-duration.md)

### [transition-property](/api/css/properties/transition-property.md)

### [transition-timing-function](/api/css/properties/transition-timing-function.md)

### [transition](/api/css/properties/transition.md)

### [vertical-align](/api/css/properties/vertical-align.md)

### [visibility](/api/css/properties/visibility.md)

### [white-space](/api/css/properties/white-space.md)

### [width](/api/css/properties/width.md)

### [word-break](/api/css/properties/word-break.md)

### [z-index](/api/css/properties/z-index.md)



---
url: /api/css/properties/-x-auto-font-size-line-ranges.md
---

# -x-auto-font-size-line-ranges

APISummary
## Introduction

The `-x-auto-font-size-line-ranges` property defines line-count-based font size ranges for text auto sizing. Use it together with `-x-auto-font-size: true` to provide different font size search ranges for different rendered line counts.

## Examples

**This is an example below: css-api**

**Entry:** `src/-x-auto-font-size-line-ranges`
**Bundle:** `dist/-x-auto-font-size-line-ranges.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";

import "./index.scss";

const samples = [
  "Short title",
  "A medium title that wraps into two lines",
  "A very long title that wraps into three lines and uses the last line range rule",
];

const XAutoFontSizeLineRanges = () => {
  return (
    <view className="page">
      {samples.map((sample) => (
        <view key={sample} className="card">
          <text className="title" text-maxline="3">
            {sample}
          </text>
        </view>
      ))}
    </view>
  );
};

root.render(<XAutoFontSizeLineRanges />);

```



## Syntax

```css
-x-auto-font-size: true;
-x-auto-font-size-line-ranges:
  line-range(1, 18px, 22px), line-range(2, 16px, 18px),
  line-range(3 to infinity, 14px);
```

### Values

- `line-range(<line-count>, <min-size>[, <max-size>])`
  - Defines one line-count rule.
  - `<line-count>` can be an exact positive integer such as `1` or an open-ended range such as `3 to infinity`.
  - `<min-size>` is required and must be a [`<length>`](/api/css/data-type/length.md).
  - `<max-size>` is optional and must be a [`<length>`](/api/css/data-type/length.md). If omitted, the value defaults to `<min-size>`, meaning a fixed font size is used for the matched rule.

## Formal definition

| Initial value | [] |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
-x-auto-font-size-line-ranges = <line-range-function>#

<line-range-function> = line-range( <line-count> , <length> [, <length>]? )
<line-count> = <integer> | <integer> to infinity
```

## Differences from Web

- This is a Lynx-specific property.

## Notes

- This property is only effective when `-x-auto-font-size` is enabled.
- This property overrides the minimum and maximum font size settings in `-x-auto-font-size`.
- When this property is set, `-x-auto-font-size-preset-sizes` does not take effect.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-auto-font-size-line-ranges`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |




---
url: /api/css/properties/-x-auto-font-size-preset-sizes.md
---

# -x-auto-font-size-preset-sizes

APISummary
## Description

The `-x-auto-font-size-preset-sizes` property specifies an array of preset font sizes. When text auto-scaling is enabled, the most suitable font size will be selected from this array - the largest size that satisfies the width constraints.

## Examples

**This is an example below: css-api**

**Entry:** `src/-x-auto-font-size-preset-sizes`
**Bundle:** `dist/-x-auto-font-size-preset-sizes.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const XAutoFontSizePresetSizes = () => {
  const containerStyle = {
    display: "linear" as const,
    backgroundColor: "white",
  };

  const baseTextStyle = {
    backgroundColor: "gray",
    fontSize: "20px",
    overflow: "hidden",
  };

  const autoFontStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
  };

  const autoFontWithSizeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px",
  };

  const autoFontWithRangeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px",
  };

  const autoFontWithStepStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px 3px",
  };

  const presetSizesStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
    XAutoFontSizePresetSizes: "10px 16px 25px",
  };

  const sampleText = "This is a test text for auto-sizing font This is a test text for auto-sizing font";

  return (
    <view className="intro" style={containerStyle}>
      <text text-maxline="1" style={autoFontStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithSizeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithRangeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithStepStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={presetSizesStyle}>
        {sampleText}
      </text>
    </view>
  );
};

root.render(<XAutoFontSizePresetSizes />);

```



## Syntax

```css
-x-auto-font-size: true;
-x-auto-font-size-preset-sizes: 10px 12px 15px;
```

## Formal definition

| Initial value | [] |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
-x-auto-font-size-preset-sizes = (<length>){3}
```

## Differences from the Web

- This is a Lynx-specific property.

## Notes

- This property is only effective when `-x-auto-font-size` is enabled, and it overrides the minimum and maximum font size settings in `-x-auto-font-size`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-auto-font-size-preset-sizes`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.2 | - |
| Clay iOS | 3.2 | - |
| Clay Windows | 3.2 | - |
| Clay macOS | 3.2 | - |
| Web | ❓ Unknown | - |




---
url: /api/css/properties/-x-auto-font-size.md
---

# -x-auto-font-size

APISummary
## Introduction

The `-x-auto-font-size` property sets whether to enable text adaptive font size adjustment, minimum text font size, maximum text font size, and font size adjustment granularity value. All parameters except the first one are optional.

## Examples

**This is an example below: css-api**

**Entry:** `src/-x-auto-font-size`
**Bundle:** `dist/-x-auto-font-size.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const XAutoFontSize = () => {
  const containerStyle = {
    display: "linear" as const,
    backgroundColor: "white",
  };

  const baseTextStyle = {
    backgroundColor: "gray",
    fontSize: "20px",
    overflow: "hidden",
  };

  const autoFontStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
  };

  const autoFontWithSizeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px",
  };

  const autoFontWithRangeStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px",
  };

  const autoFontWithStepStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true 10px 50px 3px",
  };

  const presetSizesStyle = {
    ...baseTextStyle,
    XAutoFontSize: "true",
    XAutoFontSizePresetSizes: "10px 16px 25px",
  };

  const sampleText = "This is a test text for auto-sizing font This is a test text for auto-sizing font";

  return (
    <view className="intro" style={containerStyle}>
      <text text-maxline="1" style={autoFontStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithSizeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithRangeStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={autoFontWithStepStyle}>
        {sampleText}
      </text>

      <text text-maxline="1" style={presetSizesStyle}>
        {sampleText}
      </text>
    </view>
  );
};

root.render(<XAutoFontSize />);

```



## Syntax

```css
-x-auto-font-size: 'true';
-x-auto-font-size: 'true 10px';
-x-auto-font-size: 'true 10px 30px';
-x-auto-font-size: 'true 10px 30px 2px';
```

### Values

- First parameter indicates whether to enable text adaptive font size adjustment, 'true' to enable, 'false' to disable

- Second parameter specifies the minimum text font size, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional

- Third parameter specifies the maximum text font size, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional when the first two parameters exist

- Fourth parameter specifies the font size adjustment granularity value, value is [`<length>`](/api/css/data-type/length.md), this parameter is optional when the first three parameters exist, default value is 1px

## Formal definition

| Initial value | false |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
-x-auto-font-size = true (<length>){0,3} | false
```

## Differences from Web

- This is a Lynx-specific property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-auto-font-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.2 | - |
| Clay iOS | 3.2 | - |
| Clay Windows | 3.2 | - |
| Clay macOS | 3.2 | - |
| Web | ❌ No | - |




---
url: /api/css/properties/-x-handle-color.md
---

# -x-handle-color

APISummary
## Introduction

The `-x-handle-color` property specifies the color of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples

**This is an example below: css-api**

**Entry:** `src/-x-handle-color`
**Bundle:** `dist/-x-handle-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const XHandleColor = () => {
  return (
    <view className="container">
      <text className="text1" text-selection={true} flatten={false}>This is a text</text>
      <text className="text2" text-selection={true} flatten={false}>This is a text</text>
    </view>
  );
};

root.render(<XHandleColor />);

```



## Syntax

```css
::selection {
  -x-handle-color: blue;
}
```

### Values

- [`<color>`](/api/css/properties/color.md)<br />
  Sets the color of the floating marker

## Formal definition

| Initial value | false |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
-x-handle-color = <color>
```

## Differences from web

- This is a Lynx-specific property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-handle-color`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |




---
url: /api/css/properties/-x-handle-size.md
---

# -x-handle-size

APISummary
## Introduction

The `-x-handle-size` property specifies the size of the floating marker when copying text, only valid in the selection pseudo-element.

## Examples

**This is an example below: css-api**

**Entry:** `src/-x-handle-size`
**Bundle:** `dist/-x-handle-size.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const XHandleSize = () => {
  return (
    <view className="container">
      <text className="text1" text-selection={true} flatten={false}>This is a text</text>
      <text className="text2" text-selection={true} flatten={false}>This is a text</text>
    </view>
  );
};

root.render(<XHandleSize />);

```



## Syntax

```css
::selection {
  -x-handle-size: 5px;
}
```

### Values

- [`<length>`](/api/css/data-type/length.md)<br />
  Sets the size of the floating marker

## Formal definition

| Initial value | 0 |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
-x-handle-size = <length>
```

## Differences from web

- This is a Lynx-specific property.

## Notes

- On Android, it corresponds to the size of the entire floating marker, while on iOS, it corresponds to the diameter of the floating marker's circular ball

## Compatibility

**Compatibility Table**
**Query:** `css.properties.-x-handle-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ❌ No | - |




---
url: /api/css/properties/align-content.md
---

# align-content

APISummary
## Introduction

In [flexible box layout](/guide/ui/layout/flexible-box-layout.md), the `align-content` property defines how flex lines are aligned along the **cross-axis**.

In [grid layout](/guide/ui/layout/grid-layout.md), the `align-content` property defines how to align grid tracks along the **block axis**.

## Examples

**This is an example below: css-api**

**Entry:** `src/align-content`
**Bundle:** `dist/align-content.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AlignContent = () => {
  const colorBlockStyle = (color: string) => ({
    width: "100px",
    height: "50px",
    backgroundColor: color,
  });

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text>align-content:stretch;</text>
        <view className="container1">
          <view style={colorBlockStyle("red")} />
          <view style={colorBlockStyle("yellow")} />
          <view style={colorBlockStyle("green")} />
          <view style={colorBlockStyle("blue")} />
        </view>
        <text>align-content:center;</text>
        <view className="container2">
          <view style={colorBlockStyle("red")} />
          <view style={colorBlockStyle("yellow")} />
          <view style={colorBlockStyle("green")} />
          <view style={colorBlockStyle("blue")} />
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignContent />);

```



## Syntax

### Values

#### `stretch`

**Default value**. If the combined size of the items along the cross axis (block axis in grid layout) is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container along the cross axis (block axis in grid layout).

#### `start`

All lines are packed starting from the start edge of the container.

#### `end`

All lines are packed starting from the end edge of the container.

#### `flex-start`

Behaves the same as `start`. Recommended to use only in flexible box layout.

#### `flex-end`

Behaves the same as `end`. Recommended to use only in flexible box layout.

#### `center`

All lines are packed toward the center of the container. Lines are tightly packed against each other and aligned centrally within the container. The distance between the cross-axis (block axis in grid layout) start edge and the first line equals the distance between the cross-axis (block axis in grid layout) end edge and the last line.

#### `space-between`

Lines are evenly distributed in the container. The spacing between each pair of adjacent lines is equal. The cross-axis (block axis in grid layout) start edge and end edge of the container are flush with the first and last lines respectively.

#### `space-around`

Lines are evenly distributed in the container, with equal space between lines. The space between the cross-axis (block axis in grid layout) start edge and the first line, and between the cross-axis (block axis in grid layout) end edge and the last line, is half the size of the space between adjacent lines.

## Formal definition

| Initial value | `stretch` |
| Applies to | flex containers/grid containers |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
align-content = stretch | start | end | flex-start | flex-end | center | space-between | space-around
```

## Differences from web

[mdn: align-content](https://developer.mozilla.org/en/docs/Web/CSS/align-content)

1. `normal`, `baseline`, `first baseline`, and `last baseline` are not supported. Initial value is `stretch`.
2. `space-evenly` is not supported, will be supported in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-content`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-content](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/align-items.md
---

# align-items

APISummary
## Introduction

`align-items` property sets the [`align-self`](/api/css/properties/align-self.md) value on all direct children as a group. In flexible box layout and [linear layout](/guide/ui/layout/linear-layout.md), it controls the alignment of items on the **cross axis**. In grid layout, it controls the alignment of items on the **block axis** within their grid area.

For flexible box layout, if any child element's cross-axis [`margin`](/api/css/properties/margin.md) is set to `auto`, `align-items` will be ignored.

:::info
For grid layout, Lynx doesn't support `writing-mode`, so the block axis is the vertical axis.
:::

## Examples

**This is an example below: css-api**

**Entry:** `src/align-items`
**Bundle:** `dist/align-items.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AlignItems = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const itemStyle = {
    width: "50px",
    height: "50px",
    margin: "5px",
    backgroundColor: "#4e98f4",
    color: "#ffffff",
    textAlign: "center" as const,
    lineHeight: "50px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="title">align-items: stretch;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "stretch" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: center;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: flex-start;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-start" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
        </view>

        <text className="title">align-items: flex-end;</text>
        <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-end" }}>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>X</text>
          <text style={itemStyle}>XS</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignItems />);

```



## Syntax

### Values

#### `stretch`

**Default value**. If items are smaller than the container in the **cross-axis** direction (block axis in [grid](/guide/ui/layout/grid-layout.md) layout), items with unspecified dimensions (height/width) or set to `auto` will be stretched to match the height of the row or width of the column. These items still maintain their aspect ratio constraints.

#### `center`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are centered along the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are centered along the block axis within their grid area.

:::info
In flexible box layout, if an item's cross-axis size is larger than the flex container, it will overflow equally in both directions.
:::

#### `start`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are aligned at the start of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are aligned with the start edge of their grid area along the block axis.

#### `end`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, items are aligned at the end of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, items are aligned with the end edge of their grid area along the block axis.

#### `flex-start`

Behaves the same as `start`.

#### `flex-end`

Behaves the same as `end`.

#### `baseline`

All flex items are aligned such that their flex container baselines align. The item with the largest distance between its cross-start margin edge and its baseline is flushed with the cross-start edge of the line. Currently only supported in flexible box layout.

#### `auto`
 Deprecated
Equivalent to `stretch`. Not recommended, as this value doesn't exist in Web.

## Formal definition

| Initial value | stretch |
| Applies to | flex/grid/linear containers |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
align-items = stretch | center | start | end | flex-start | flex-end | baseline | auto
```

## Differences from web

[mdn: align-items](https://developer.mozilla.org/en/docs/Web/CSS/align-items)

1. `normal`, `self-start` and `self-end` are not supported. Initial value is `stretch`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-items`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-items](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-items)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/align-self.md
---

# align-self

APISummary
## Introduction

In flex and [linear](/guide/ui/layout/linear-layout.md) layout, `align-self` will align the elements in the current container on the **cross axis**. In grid layout, `align-self` controls the alignment of child elements along the **block axis** within their grid area, and `align-self` overrides the existing value of [`align-items`](/api/css/properties/align-items.md).

For flexible box layout, if any child element's cross-axis [`margin`](/api/css/properties/margin.md) is set to auto, `align-self` will be ignored.

:::info
For grid layout, Lynx doesn't support `writing-mode`, so the block axis is the vertical axis.
:::

## Examples

**This is an example below: css-api**

**Entry:** `src/align-self`
**Bundle:** `dist/align-self.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AlignSelf = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const itemStyle = {
    width: "50px",
    height: "50px",
    margin: "5px",
    backgroundColor: "#4e98f4",
    color: "#ffffff",
    textAlign: "center" as const,
    lineHeight: "50px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view style={{ width: "100%", height: "100%", flexDirection: "column" }}>
          <text className="title">align-self: stretch;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "stretch" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: center;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "flex-start" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "center" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: flex-start;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "flex-start" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>

          <text className="title">align-self: flex-end;</text>
          <view style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
            <text style={itemStyle}>X</text>
            <text style={{ ...itemStyle, alignSelf: "flex-end" }}>X</text>
            <text style={itemStyle}>X</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<AlignSelf />);

```



## Syntax

### Values

#### `auto`

**Default value**. Aligns according to the parent's [`align-items`](/api/css/properties/align-items.md) value.

#### `stretch`

If items are smaller than the container in the **cross-axis** direction (block axis in [grid](/guide/ui/layout/grid-layout.md) layout), items with unspecified dimensions (height/width) or set to `auto` will be stretched to match the height of the row or width of the column. These items still maintain their aspect ratio constraints.

#### `center`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is centered along the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is centered along the block axis within its grid area.

#### `start`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is aligned at the start of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is aligned with the start edge of its grid area along the block axis.

#### `end`

In flex and [linear](/guide/ui/layout/linear-layout.md) layouts, the item is aligned at the end of the cross axis.

In [grid](/guide/ui/layout/grid-layout.md) layout, the item is aligned with the end edge of its grid area along the block axis.

#### `flex-start`

Behaves the same as `start`.

#### `flex-end`

Behaves the same as `end`.

#### `baseline`

The item participates in baseline alignment. Currently only supported in flexible box layout.

## Formal definition

| Initial value | auto |
| Applies to | flex/grid/linear items |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
align-self = auto | center | start | end | flex-start | flex-end | baseline | stretch
```

## Differences from web

[mdn: align-self](https://developer.mozilla.org/en/docs/Web/CSS/align-self)

1. `normal`, `self-start` and `self-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.align-self`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-self](https://developer.mozilla.org/zh-CN/docs/Web/CSS/align-self)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-delay.md
---

# animation-delay

APISummary
## Introduction

`animation-delay` property specifies the delay before the animation starts playing.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-delay`
**Bundle:** `dist/animation-delay.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationDelay = () => {
  const delaySecondsProps = ["0s", "1s", "2s", "3s", "4s"];
  const delayMilliSecondsProps = ["0ms", "1000ms", "2000ms", "3000ms", "4000ms"];

  const containerStyle = {
    height: "200rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (delay: string, unit: string = "s") => ({
    animation: `rotateZ-ani 2s ease ${delay}${unit} infinite alternate both running`,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo : delay s</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">delay</text>
        <view className="fd-row" style={containerStyle}>
          {delaySecondsProps.map((item, index) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(index.toString())} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <text className="h1">keyframes animation demo : delay ms</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">delay</text>
        <view className="fd-row" style={containerStyle}>
          {delayMilliSecondsProps.map((item, index) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view
                flatten={false}
                style={getAnimationStyle(index.toString(), "ms")}
                className="ani-size mg5 mgl15 mgt15"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationDelay />);

```



## Syntax

```css
animation-delay: 3s;
animation-delay: 2s, 4ms;
```

## Caution

:::caution

- Lynx defaults to requiring **units** for `duration` and `delay`. Writing without units may result in undefined behavior.

:::

## Formal definition

| Initial value | 0s |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/* default value: 0s */
animation-delay: <time>;
```

## See Also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-delay`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-delay](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-delay)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-direction.md
---

# animation-direction

APISummary
## Introduction

`animation-direction` property specifies whether the animation should play in reverse.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-direction`
**Bundle:** `dist/animation-direction.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationDirection = () => {
  const directionProperties = ["normal", "reverse", "alternate", "alternate-reverse"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "750rpx",
  };

  const getAnimationStyle = (direction: string) => ({
    animation: `ani 1.5s ease 0s infinite ${direction} forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: direction</text>
      <view className="sep"></view>

      {directionProperties.map(item => (
        <>
          <view className="fd-col group pd5" key={item}>
            <text className="button h2">direction: {item}</text>
            <view className="fd-row" style={containerStyle}>
              <view style={columnStyle} className="fd-col mg5">
                <text className="h4">direction: {item}</text>
                <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
              </view>
            </view>
          </view>
          <view className="sep"></view>
        </>
      ))}
    </scroll-view>
  );
};

root.render(<AnimationDirection />);

```



## Syntax

```css
animation-direction: normal
animation-direction: reverse
animation-direction: alternate
animation-direction: alternate-reverse
animation-direction: normal, reverse
animation-direction: alternate, reverse, normal

```

### Values

#### normal

The animation plays forward in each cycle. In other words, each animation cycle ends and resets to the starting point to begin again. This is the default behavior.

#### alternate

The animation alternates between running forwards and backwards. When running backwards, the animation steps backward and timing functions are also reversed. For example, ease-in becomes ease-out when reversed.

#### reverse

The animation runs backwards, playing from end to start.

#### alternate-reverse

The animation runs backwards on the first iteration, then forwards on the next, and continues alternating.

## Formal definition

| Initial value | normal |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/*default value: normal*/
animation-direction: normal | reverse | alternate | alternate-reverse;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-direction`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-direction](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-direction)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-duration.md
---

# animation-duration

APISummary
## Introduction

`animation-duration` property specifies the length of time that an animation should take to complete one cycle.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-duration`
**Bundle:** `dist/animation-duration.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationDuration = () => {
  const durationSecondsProps = ["0s", "1s", "2s", "3s", "4s"];
  const durationMilliSecondsProps = ["0ms", "1000ms", "2000ms", "3000ms", "4000ms"];

  const containerStyle = {
    height: "200rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (duration: string) => ({
    animation: `rotateZ-ani ${duration} ease 0s infinite alternate both running`,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">Animation Duration Demo (seconds)</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">Duration</text>
        <view className="fd-row" style={containerStyle}>
          {durationSecondsProps.map((item) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <text className="h1">Animation Duration Demo (milliseconds)</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">Duration</text>
        <view className="fd-row" style={containerStyle}>
          {durationMilliSecondsProps.map((item) => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h3 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationDuration />);

```



## Syntax

```css
/* Single animation */
animation-duration: 6s
animation-duration: 120ms

/* Multiple animations */
animation-duration: 1s, 15s
animation-duration: 10s, 30s, 230ms
```

## Caution

:::caution

- Lynx defaults to requiring **units** for `duration` and `delay`. Writing without units may result in undefined behavior.

:::

## Formal definition

| Initial value | 0s |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/* default value: 0s */
animation-duration: <time>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-duration`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-duration](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-duration)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-fill-mode.md
---

# animation-fill-mode

APISummary
## Introduction

`animation-fill-mode` property sets how a CSS animation applies styles to its target before and after its execution.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-fill-mode`
**Bundle:** `dist/animation-fill-mode.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationFillMode = () => {
  const noneProperties = ["none"];
  const forwardsProperties = ["forwards"];
  const backwardsProperties = ["backwards"];
  const bothProperties = ["both"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "350px",
  };

  const getAnimationStyle = (fillMode: string) => ({
    animation: `ani 3s ease 2s 1 normal ${fillMode} running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: fillmode</text>
      <text className="h4">From--&gt; transform: translateX(50px);background-color: blue;</text>
      <text className="h4">To--&gt; transform: translateX(200px);background-color: red;</text>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">none</text>
        <view className="fd-row" style={containerStyle}>
          {noneProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">forwards</text>
        <view className="fd-row" style={containerStyle}>
          {forwardsProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">backwards</text>
        <view className="fd-row" style={containerStyle}>
          {backwardsProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">both</text>
        <view className="fd-row" style={containerStyle}>
          {bothProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4 mgl15">{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationFillMode />);

```



## Syntax

```css
/* Single animation */
animation-fill-mode: none;
animation-fill-mode: forwards;
animation-fill-mode: backwards;
animation-fill-mode: both;

/* Multiple animations */
animation-fill-mode: none, backwards;
animation-fill-mode: both, forwards, none;
```

### Values

#### none

**Default value**. The animation will not apply any styles to the target when it's not executing. The element will display using the CSS rules that have already been applied to it. This is the default value.

#### forwards

The target will retain the computed values set by the last keyframe encountered during execution. The last keyframe depends on the values of [animation-direction](/api/css/properties/animation-direction.md) and [animation-iteration-count](/api/css/properties/animation-iteration-count.md):

| animation-direction | animation-iteration-count | last keyframe encountered |
| ------------------- | ------------------------- | ------------------------- |
| normal              | even or odd               | 100% or to                |
| reverse             | even or odd               | 0% or from                |
| alternate           | even                      | 0% or from                |
| alternate           | odd                       | 100% or to                |
| alternate-reverse   | even                      | 100% or to                |
| alternate-reverse   | odd                       | 0% or from                |

#### backwards

The animation will apply the values defined in the first keyframe at the start of the animation. The first keyframe depends on the value of [animation-direction](/api/css/properties/animation-direction.md):

| animation-direction          | first relevant keyframe |
| ---------------------------- | ----------------------- |
| normal or alternate          | 0% or from              |
| reverse or alternate-reverse | 100% or to              |

#### both

The animation will follow both the forwards and backwards rules, applying the keyframe values both before and after the animation.

## Formal definition

| Initial value | none |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/*none*/
animation-fill-mode: none | forwards | backwards | both;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-fill-mode`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-fill-mode](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-fill-mode)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-iteration-count.md
---

# animation-iteration-count

APISummary
## Introduction

`animation-iteration-count` property specifies the number of times an animation should be played.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-iteration-count`
**Bundle:** `dist/animation-iteration-count.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationIterationCount = () => {
  const iteration1Properties = ["1"];
  const iteration3Properties = ["3"];
  const iterationInfiniteProperties = ["infinite"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (count: string) => ({
    animation: `ani 1.5s ease 0s ${count} normal forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: iteration-count</text>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: 1</text>
        <view className="fd-row" style={containerStyle}>
          {iteration1Properties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: 3</text>
        <view className="fd-row" style={containerStyle}>
          {iteration3Properties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">iteration-count: infinite</text>
        <view className="fd-row" style={containerStyle}>
          {iterationInfiniteProperties.map(item => (
            <view style={columnStyle} className="fd-col mg5" key={item}>
              <text className="h4">iteration-count:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<AnimationIterationCount />);

```



## Syntax

```css
animation-iteration-count: infinite;

animation-iteration-count: 3;

animation-iteration-count: 2, 0, infinite;
```

### Values

#### infinite

The animation will repeat forever.

#### `<number>`

The number of times the animation should repeat. Can be a non-integer value. A value of 0 will cause the animation to have no effect.

::: info
When animation-iteration-count is 0, Lynx will treat it as an animation with duration 0, and its lifetime will continue as usual. This differs from standard CSS animations where it would be treated as if the animation didn't work at all.
:::

## Formal definition

| Initial value | 1 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/*default value: 1*/
animation-iteration-count: <number> | infinite;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-iteration-count`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-iteration-count](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-iteration-count)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-name.md
---

# animation-name

APISummary
## Introduction

`animation-name` property specifies a list of animations to apply to an element. Each name refers to an animation sequence defined by [@keyframes](https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes).

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-name`
**Bundle:** `dist/animation-name.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";
import lynxImage from "../../resource/lynxicon.png";

const Keyframes = () => {
  const [flag, setFlag] = useState(true);

  const transProperties = ["translateX", "translateY", "translateXY"];
  const rotateProperties = ["rotateZ", "rotateX", "rotateY"];
  const scaleProperties = ["scaleX", "scaleY", "scaleXY"];
  const flipProperties = ["flipX", "flipY", "flipXY"];
  const otherProperties = ["background-color", "opacity"];

  const heightStyle = {
    height: "200rpx",
  };

  const widthStyle = {
    width: "250rpx",
  };

  const rotateHeightStyle = {
    height: "150rpx",
  };

  const scaleImageStyle = {
    marginLeft: "15px",
    marginTop: "30px",
  };

  const otherStyle = {
    marginLeft: "15px",
    marginTop: "15px",
  };

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">translate animation</text>
        <view className="fd-row" style={heightStyle}>
          {transProperties.map((item, index) => (
            <view style={widthStyle} key={`trans-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">rotate animation</text>
        <view className="fd-row" style={rotateHeightStyle}>
          {rotateProperties.map((item, index) => (
            <view style={widthStyle} key={`rotate-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">scale animation</text>
        <view className="fd-row" style={heightStyle}>
          {scaleProperties.map((item, index) => (
            <view style={widthStyle} key={`scale-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running`, ...scaleImageStyle }}
                className="ani-size"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">flip animation</text>
        <view className="fd-row" style={heightStyle}>
          {flipProperties.map((item, index) => (
            <view style={widthStyle} key={`flip-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image
                style={{ animation: `${item}-ani 2s ease 0s infinite alternate both running` }}
                className="ani-size mg5 mgl15 mgt15"
                src={lynxImage}
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">bg-color opacity animation</text>
        <view className="fd-row" style={heightStyle}>
          {otherProperties.map((item, index) => (
            <view style={widthStyle} key={`other-${index}`} className="fd-col mg5">
              <text className="h4 mgl15">{item}</text>
              <view className="base"></view>
              <view
                style={{
                  animation: `${item}-ani 2s ease 0s infinite alternate both ${flag ? "running" : "paused"}`,
                  ...otherStyle,
                }}
                className="ani-size"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<Keyframes />);

```



## Syntax

```css
/* Single animation */
animation-name: none;
animation-name: test_05;
animation-name: -specific;
animation-name: sliding-vertically;

/* Multiple animations */
animation-name: test1, animation4;
animation-name:
  none,
  -moz-specific,
  sliding;
```

::: info
Animation names are case-sensitive. The identifier must follow these naming rules, otherwise it may be treated as invalid.
:::

## Formal definition

| Initial value | none |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
animation-name: <string>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-name`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-name](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-name)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-play-state.md
---

# animation-play-state

APISummary
## Introduction

`animation-play-state` property specifies whether an animation is running or paused. When resuming a paused animation, it will continue from where it was paused rather than starting from the beginning of the animation sequence.

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-play-state`
**Bundle:** `dist/animation-play-state.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const AnimationPlayState = () => {
  const [playState, setPlayState] = useState(true);

  const degProperties = ["90deg", "180deg", "270deg"];
  const radProperties = ["1rad", "2rad", "3rad"];
  const turnProperties = ["0.25turn", "0.5turn", "0.75turn"];

  const containerStyle = {
    height: "150rpx",
  };

  const columnStyle = {
    width: "250rpx",
  };

  const getAnimationStyle = (index: number, playState: boolean) => ({
    animation: `deg-${index} 2s ease 0s infinite alternate both ${playState ? "running" : "paused"}` as const,
  });

  return (
    <view>
      <scroll-view scroll-orientation="vertical" className="fd-col container">
        <text className="h1" bindtap={() => setPlayState(!playState)}>Click to start animation</text>
        <text className="h1">Animation Play State Demo: Deg, Rad, Turn</text>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">deg</text>
          <view className="fd-row" style={containerStyle}>
            {degProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">rad</text>
          <view className="fd-row" style={containerStyle}>
            {radProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>

        <view className="fd-col group pd5">
          <text className="button h2">turn</text>
          <view className="fd-row" style={containerStyle}>
            {turnProperties.map((item, index) => (
              <view style={columnStyle} className="fd-col mg5" key={item}>
                <text className="h4 mgl15">{item}</text>
                <view flatten={false} style={getAnimationStyle(index, playState)} className="ani-size mg5" />
              </view>
            ))}
          </view>
        </view>
        <view className="sep"></view>
      </scroll-view>
    </view>
  );
};

root.render(<AnimationPlayState />);

```



## Syntax

```css
/* Single animation */
animation-play-state: running;
animation-play-state: paused;

/* Multiple animations */
animation-play-state: paused, running, running;
```

## Formal definition

| Initial value | running |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/*default value:running*/
animation-play-state: running | paused;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-play-state`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-play-state](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-play-state)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation-timing-function.md
---

# animation-timing-function

APISummary
## Introduction

`animation-timing-function` property specifies how an animation progresses through each cycle. It can accept one or more [timing functions](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function).

## Examples

**This is an example below: css-api**

**Entry:** `src/animation-timing-function`
**Bundle:** `dist/animation-timing-function.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AnimationTimingFunction = () => {
  const timingFunctions = ["linear", "ease", "ease-in", "ease-out", "ease-in-out"];

  const columnStyle = {
    width: "500rpx",
  };

  const getAnimationStyle = (timingFunction: string) => ({
    animation: `ani 3s ${timingFunction} 0s infinite normal forwards running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation demo: time functions</text>
      <view className="sep"></view>

      {timingFunctions.map(item => (
        <>
          <view className="fd-col group pd5" key={item}>
            <view style={columnStyle} className="fd-col mg5">
              <text className="h4">time functions:{item}</text>
              <view flatten={false} style={getAnimationStyle(item)} className="ani-size mg5" />
            </view>
          </view>
          <view className="sep"></view>
        </>
      ))}
    </scroll-view>
  );
};

root.render(<AnimationTimingFunction />);

```



## Syntax

```css
/* Keyword values */
animation-timing-function: ease;
animation-timing-function: ease-in;
animation-timing-function: ease-out;
animation-timing-function: ease-in-out;
animation-timing-function: linear;

/* Function values */
animation-timing-function: cubic-bezier(0.1, 0.7, 1, 0.1);
animation-timing-function: steps(4, end);
animation-timing-function: frames(10);

/* Multiple animations */
animation-timing-function: ease, steps(5, end), cubic-bezier(0.1, 0.7, 1, 0.1);
```

## Formal definition

| Initial value | linear |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
/*default value: linear*/
animation-timing-function: linear | ease | ease-in | ease-out | ease-in-out |
  <timing-function>;
```

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation-timing-function`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-timing-function](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-timing-function)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/animation.md
---

# animation

APISummary
## Introduction

The animation property is a shorthand property for [animation-name](/api/css/properties/animation-name.md), [animation-duration](/api/css/properties/animation-duration.md), [animation-timing-function](/api/css/properties/animation-timing-function.md), [animation-delay](/api/css/properties/animation-delay.md), [animation-iteration-count](/api/css/properties/animation-iteration-count.md), [animation-direction](/api/css/properties/animation-direction.md), [animation-fill-mode](/api/css/properties/animation-fill-mode.md), and [animation-play-state](/api/css/properties/animation-play-state.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/animation`
**Bundle:** `dist/animation.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";
import lynxImage from "../../resource/lynxicon.png";

const Keyframes = () => {
  const [flag, setFlag] = useState(true);

  const transProperties = ["translateX", "translateY", "translateXY"];
  const rotateProperties = ["rotateZ", "rotateX", "rotateY"];
  const scaleProperties = ["scaleX", "scaleY", "scaleXY"];
  const flipProperties = ["flipX", "flipY", "flipXY"];
  const otherProperties = ["background-color", "opacity"];

  const containerHeightStyle = {
    height: "200rpx",
  };

  const columnWidthStyle = {
    width: "250rpx",
  };

  const rotateHeightStyle = {
    height: "150rpx",
  };

  const scaleImageStyle = {
    marginLeft: "15px",
    marginTop: "30px",
  };

  const otherStyle = {
    marginLeft: "15px",
    marginTop: "15px",
  };

  const getAnimationStyle = (name: string) => ({
    animation: `${name}-ani 2s ease 0s infinite alternate both running` as const,
  });

  return (
    <scroll-view scroll-orientation="vertical" className="fd-col container">
      <text className="h1">keyframes animation</text>
      <view className="sep"></view>
      <view className="fd-col group pd5">
        <text className="button h2">translate animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {transProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`trans-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">rotate animation</text>
        <view className="fd-row" style={rotateHeightStyle}>
          {rotateProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`rotate-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">scale animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {scaleProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`scale-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={{ ...getAnimationStyle(item), ...scaleImageStyle }} className="ani-size" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">flip animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {flipProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`flip-${index}`} className="fd-col mg5">
              <text className="h3 mgl15">{item}</text>
              <image style={getAnimationStyle(item)} className="ani-size mg5 mgl15 mgt15" src={lynxImage} />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>

      <view className="fd-col group pd5">
        <text className="button h2">bg-color opacity animation</text>
        <view className="fd-row" style={containerHeightStyle}>
          {otherProperties.map((item, index) => (
            <view style={columnWidthStyle} key={`other-${index}`} className="fd-col mg5">
              <text className="h4 mgl15">{item}</text>
              <view className="base"></view>
              <view
                style={{
                  animation: `${item}-ani 2s ease 0s infinite alternate both ${flag ? "running" : "paused"}`,
                  ...otherStyle,
                }}
                className="ani-size"
              />
            </view>
          ))}
        </view>
      </view>
      <view className="sep"></view>
    </scroll-view>
  );
};

root.render(<Keyframes />);

```



## Syntax

```css
/* @keyframes name | duration | timing-function | delay |
   iteration-count | direction | fill-mode | play-state*/
animation: slidein 3s ease-in 1s 2 reverse both paused;

/* @keyframes name | duration | timing-function | delay */
animation: slidein 3s linear 1s;

/* @keyframes name | duration */
animation: slidein 3s;

/* Multiple animations */
animation:
  slidein 3s ease-in 1s 2 reverse both paused,
  ani_scale 3s linear 1s;
```

## Caution

:::caution

- When writing CSS `@keyframes`, it is recommended not to omit the values for the `0%` (or `from`) stage and `100%` (or `to`) stage. If the start and end stage values are not specified, we will use the node's current property value. Due to system limitations, the transform property on Android systems may have issues.

:::

## Formal definition

| Initial value | animation-name: none
animation-duration: 0s
animation-timing-function: ease
animation-delay: 0s
animation-iteration-count: 1
animation-direction: normal
animation-fill-mode: none
animation-play-state: running |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

Animation can specify multiple sets of animations. Properties within each set of animations are separated by spaces, and sets of animations are separated by commas.

```
animation: <animation-name> || <animation-duration> ||
  <animation-timing-function> || <animation-delay> ||
  <animation-iteration-count> || <animation-direction> || <animation-fill-mode>
  || <animation-play-state>;
```

## Animation events

- [Animation Event](/api/lynx-api/event/animation-event.md)

## See also

- [animation](/api/css/properties/animation.md)
- [animation-name](/api/css/properties/animation-name.md)
- [animation-duration](/api/css/properties/animation-duration.md)
- [animation-timing-function](/api/css/properties/animation-timing-function.md)
- [animation-delay](/api/css/properties/animation-delay.md)
- [animation-iteration-count](/api/css/properties/animation-iteration-count.md)
- [animation-direction](/api/css/properties/animation-direction.md)
- [animation-fill-mode](/api/css/properties/animation-fill-mode.md)
- [animation-play-state](/api/css/properties/animation-play-state.md)
- [CSS animation event](/api/lynx-api/event/animation-event.md)
- [Animated API](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.animation`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/aspect-ratio.md
---

# aspect-ratio

APISummary
## Introduction

The `aspect-ratio` CSS property sets a preferred aspect-ratio for the box, which will be used in the calculation of auto sizes and some other layout functions.

## Examples

**This is an example below: css-api**

**Entry:** `src/aspect-ratio`
**Bundle:** `dist/aspect-ratio.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const AspectRatio = () => {
  const textStyle = {
    width: "50px",
    aspectRatio: "1/4",
    backgroundColor: "red",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text style={textStyle}>test</text>
      </view>
    </scroll-view>
  );
};

root.render(<AspectRatio />);

```



## Syntax

```css
aspect-ratio: 1 / 1;
aspect-ratio: 16 / 9;
aspect-ratio: 0.5;
```

### Values

#### `<ratio>`

The box's preferred aspect-ratio is the ratio of `width` to `height`. If the height and preceding slash are omitted, height defaults to 1. Size calculations involving aspect-ratio use the dimensions of the box specified by [`box-sizing`](/api/css/properties/box-sizing.md).

:::info
The `<ratio>` CSS data type represents a ratio between two numbers. It consists of:

- A positive [`<number>`](/api/css/data-type/number.md) value
- Followed by a forward slash ('/', Unicode U+002F SOLIDUS)
- Followed by a second positive `<number>` value
- Alternatively, a single positive `<number>` is allowed as a value
  :::

## Formal definition

| Initial value | has no preferred `aspect ratio` |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |


## Formal syntax

```css
aspect-ratio = <number [0,∞]> [ / <number [0,∞]> ]
```

## Difference with the web

[mdn: aspect-ratio](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio)

1. `auto` is not supported, one has no preferred `aspect-ratio` by default.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.aspect-ratio`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/aspect-ratio](https://developer.mozilla.org/zh-CN/docs/Web/CSS/aspect-ratio)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.2 | - |
| iOS | 1.2 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.2 | - |
| Clay iOS | 1.2 | - |
| Clay macOS | 1.2 | - |
| Clay Windows | 1.2 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-clip.md
---

# background-clip

APISummary
## Introduction

The `background-clip` CSS property sets whether an element's background extends underneath its border box, padding box, or content box.

## Examples

**This is an example below: css-api**

**Entry:** `src/background-clip`
**Bundle:** `dist/background-clip.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundClip = () => {
  const scrollViewStyle = {
    flexDirection: "column" as const,
    height: "2500px",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="shared border-box"></text>
        <text className="shared padding-box"></text>
        <text className="shared content-box"></text>
        <text className="shared border-box radius"></text>
        <text className="shared padding-box radius"></text>
        <text className="shared content-box radius"></text>
        <text className="shared border-box radius2"></text>
        <text className="shared padding-box radius2"></text>
        <text className="shared content-box radius2"></text>
        <text className="shared border-area"></text>
        <text className="shared border-area radius"></text>
        <text className="shared border-area radius2"></text>
        <view className="container"></view>
        <view className="border-area-container"></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundClip />);

```



## Syntax

```css
background-clip: border-box;
background-clip: padding-box;
background-clip: content-box;
background-clip: border-area;

// multiple clip
background-clip: border-box, content-box, padding-box, border-area;
```

### Values

- **`border-box`** <br />
  The background extends to the outside edge of the border (but underneath the border in z-ordering).

- **`padding-box`** <br />
  The background extends to the outside edge of the padding. No background is drawn beneath the border

- **`content-box`**
  The background is painted within (clipped to) the content box.

- **`border-area`**
  The background is painted within (clipped to) the area painted by the border, taking [`border-width`](/api/css/properties/border-width.md) into account.

## Note

If the length of `background-clip` is less than [`background-image`](/api/css/properties/background-image.md), the first clip value will effect on all remained [`background-image`](/api/css/properties/background-image.md).

## Formal definition

| Initial value | border-box |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
<background-clip> = <box> | border-area

where

<box> = border-box | padding-box | content-box

```

## Difference between web

- Only support `border-box`、`padding-box`、`content-box` 、 `border-area` <br />

- `background-clip:text` is not support, and if want show text with gradient color, just set `color: <gradient>`.

- `border-area` doesn't take `border-style` into account.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-clip`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-clip](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-clip)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-color.md
---

# background-color

APISummary
## Introduction

The `background-color` CSS property sets the background color of an element.

## Examples

**This is an example below: css-api**

**Entry:** `src/background-color`
**Bundle:** `dist/background-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundColor = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="container text1"></text>
        <text className="container text2"></text>
        <text className="container text3"></text>
        <text className="container text4"></text>
        <text className="container text5"></text>
        <text className="container text6"></text>
        <text className="container text7"></text>
        <text className="container text8"></text>
        <text className="container text9"></text>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundColor />);

```



## Syntax

```css
/* Keyword values */
background-color: red;

/* Hexadecimal value */
background-color: #bbff00;

/* RGB value */
background-color: rgb(255, 255, 128);

/* HSLA value */
background-color: hsla(50, 33%, 25%, 0.75);
```

### Values

- [`<color>`](/api/css/data-type/color.md) <br />
  The uniform color of the background.

- Default value **transparent** <br />

## Formal definition

| Initial value | transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```
<bg-color> = <rgb()> | <rgba()> | <hsl()> | <hsla()> | <hex-color> | <named-color>
```

## Difference between web

- Not support special keywords like `currentcolor`
- Not support global keywords like `inherit`、`initial`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-image.md
---

# background-image

APISummary
## Introduction

The `background-image`
 CSS property sets one or more background images on an element. 

The background images are drawn on stacking context layers on top of each other. The first layer specified is drawn as if it is closest to the user. 

The [border](/api/css/properties/border.md)
 of the element are then drawn on top of them, and the [`background-color`](/api/css/properties/background-color.md)
 is drawn beneath them. How the images are drawn relative to the box and its borders is defined by the [`background-clip`](/api/css/properties/background-clip.md)
 and [`background-origin`](/api/css/properties/background-origin.md)
 CSS properties. 

## Examples

**This is an example below: css-api**

**Entry:** `src/background-image`
**Bundle:** `dist/background-image.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

import Flower from "../../resource/bg_flower.gif?inline";
import LynxIcon from "../../resource/lynx.png?inline";

const BackgroundImage = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    image1: {
      backgroundImage: `url(${Flower})`,
    },
    image2: {
      backgroundImage: `url(${LynxIcon}), url(${Flower})`,
    },
    gradient1: {
      width: "50%",
      backgroundImage: "linear-gradient(black, green)",
    },
    gradient2: {
      width: "50%",
      backgroundImage: "linear-gradient(green 40%, yellow 30%, blue 70%)",
    },
    gradient3: {
      width: "50%",
      backgroundImage: "linear-gradient(green 40%, yellow 40%, blue 70%)",
    },
    conic: {
      width: "50%",
      height: "100%",
      backgroundImage: "conic-gradient(from 180deg at 50% 50%, red, blue, red)",
    },
    radial1: {
      width: "50%",
      backgroundImage: "radial-gradient(red, green)",
    },
    radial2: {
      width: "50%",
      backgroundImage: "radial-gradient(circle at 100%, #333, #333 50%, #eee 75%, #333 75%)",
    },
    radial3: {
      width: "100%",
      height: "100%",
      backgroundImage: "radial-gradient(ellipse closest-side at 0% 0%, #eabf8a 0%, #c5a35f 100%)",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container" style={containerStyles.image1}></view>
        <view className="container" style={containerStyles.image2}></view>
        <view className="container">
          <view style={containerStyles.gradient1}></view>
          <view style={containerStyles.conic}></view>
        </view>
        <view className="container">
          <view style={containerStyles.gradient2} />
          <view style={containerStyles.gradient3} />
        </view>
        <view className="container">
          <view style={containerStyles.radial1} />
          <view style={containerStyles.radial2} />
        </view>
        <view className="container">
          <view style={containerStyles.radial3} />
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundImage />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Syntax

```css
background-image:
  linear-gradient(to bottom, rgba(255, 255, 0, 0.5), rgba(0, 0, 255, 0.5)),
  url('https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/catfront.png');
```

### Values

Each background image is specified either as the keyword `none`
 or as an `<image>`
 value. 

- `none`
  Is a keyword denoting the absence of images.

- `<image>`
  Is an `<image>` denoting the image to display. There can be several of them, separated by commas.
  The supported image formats for background-image are the same as those for image, including jpg, png, gif, webp, etc. Refer to [Supported Image Formats](/api/elements/built-in/image.md#compatibility)

## Events

| Name        | Type     | Essential | Description     |
| ----------- | -------- | --------- | --------------- |
| bindbgload  | function | NO        | Loading succeed |
| bindbgerror | function | NO        | Loading failed  |

## Related properties of view

| Name                             | Type    | Default | Example | Essential | Description                                                                                                                                                                                     |
| -------------------------------- | ------- | ------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <AndroidOnly /> skip-redirection | boolean | false   | true    | NO        | It only needs to be set when the background-image uses `<url()>` and is a CDN image. When set to true, the logic of container redirection can be skipped to optimize the related time-consuming |

## Formal definition

| Initial value | none |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
background-image = <bg-image>#

<bg-image> = none | <image>

<image> = <url()> | <gradient>

<url()> = url(<string>)

<gradient> = <linear-gradient()> | <radial-gradient()> | <conic-gradient()>

<linear-gradient()> =
  linear-gradient( [ <angle> | to <side-or-corner> ]? , <color-stop-list> )

<radial-gradient()> =
  radial-gradient( [ <ending-shape> || <size> ]? [ at <position> ]? , <color-stop-list> )

<conic-gradient()> =
  conic-gradient( [ from [ <angle> | <zero> ] ]? [ at <position> ]? , <color-stop-list> )

<side-or-corner> =
  [ left | right ] || [ top | bottom ]

<ending-shape> =
  circle | ellipse

<size> =
  closest-side       |
  farthest-side      |
  closest-corner     |
  farthest-corner    |
  <length>           |
  <length-percentage>{2}

<position> =
  [ left | center | right ] || [ top | center | bottom ]                            |
  [ left | center | right | <length-percentage> ]
    [ top | center | bottom | <length-percentage> ]?                                |
  [ [ left | right ] <length-percentage> ] &&
    [ [ top | bottom ] <length-percentage> ]

<color-stop-list> = <linear-color-stop> ( ',' <linear-color-stop> )*

<linear-color-stop> = <color>

<length-percentage> = <length> | <percentage>

```

## Difference between web

- `<image>`
  Only support `<url()>` and `<gradient>`.

- `<gradient>`
  Support `linear-gradient`, `radial-gradient`, and `conic-gradient`(since version 3.6).

- `<linear-color-stop>`
  Not support [`linear-color-hint`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image#linear-color-hint)

  Not support [`color-interpolation-method`](https://www.w3.org/TR/css-images-4/#linear-gradients)

  Not support [`<length>`](/api/css/data-type/length.md) value for position

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-image`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-image)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-origin.md
---

# background-origin

APISummary
## Introduction

The `background-origin` CSS property sets the background's origin: from the border start, inside the border, or inside the padding.

## Examples

**This is an example below: css-api**

**Entry:** `src/background-origin`
**Bundle:** `dist/background-origin.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundOrigin = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
    },
    style3: {
      backgroundOrigin: "border-box" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundOrigin />);

```



## Syntax

```css
background-origin: border-box
background-origin: padding-box
background-origin: content-box
// multiple bg-origin
background-origin: content-box, padding-box;
```

### Values

- Default value **padding-box** <br />
  The background is positioned relative to the border box.

- **border-box** <br />
  The background is positioned relative to the padding box.

- **content-box** <br />
  The background is positioned relative to the content box.

## Formal definition

| Initial value | padding-box |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
border-box | padding-box | content-box
```

## Difference between web

- Not support `inherit`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-origin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-origin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-origin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-position.md
---

## Introduction

The `background-position` CSS property sets the initial position for each background image. The position is relative to the position layer set by [`background-origin`](/api/css/properties/background-origin.md).

# Examples

APISummary
**This is an example below: css-api**

**Entry:** `src/background-position`
**Bundle:** `dist/background-position.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundPosition = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "30px 40px",
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "50% 40px, right bottom",
    },
    style5: {
      backgroundOrigin: "padding-box" as const,
      backgroundSize: "auto 100%",
      backgroundRepeat: "no-repeat" as const,
      backgroundPosition: "-13px -20px",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
        <view className="container image1" style={containerStyles.style5}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundPosition />);

```



## Syntax

```css
/* Keyword values */
background-position: top;
background-position: bottom;
background-position: left;
background-position: right;
background-position: center;

/* <percentage> values */
background-position: 25% 75%;

/* <length> values */
background-position: 0px 0px;
background-position: 1rem 2rem;
background-position: 10em 8em;

/* Multiple images */
background-position:
  0px 0px,
  center;
```

### Values

- **1-value syntax**
  - Keyword `center`, which centers the image.
  - Keyword `top`, `left`, `bottom`, `right`. This specifies an edge against which to place the item. The other dimension is then set to 50%, so the item is placed in the middle of the edge specified.
  - [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md). This specifies the X coordinate relative to the left edge, with the Y coordinate set to 50%.

- **2-value syntax**
  - One of the keyword values `top`, `left`, `bottom`, `right`. If `left` or `right` are given here, then this defines X and the other given value defines Y. If `top` or `bottom` are given, then this defines Y and the other value defines X.
  - A [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md). If the other value is left or right, then this value defines Y, relative to the top edge. If the other value is top or bottom, then this value defines X, relative to the left edge. If both values are `<length>` or `<percentage>` values, then the first defines X and the second Y.
  - Note that: If one value is `top` or `bottom`, then the other value may not be `top` or `bottom`. If one value is `left` or `right`, then the other value may not be `left` or `right`. This means, e.g., that `top` `top` and `left` `right` are not valid.

- Default value
  - `left top` or `0% 0%`

## Formal definition

| Initial value | 0% 0% |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
[ left | center | right | top | bottom | <length-percentage> ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]

<length-percentage> = <length> | <percentage>
```

## Difference between web

- Not support **Global Value** like `inherit`、`initial` and `unset`.
- Not support **Edge offsets syntax** like:

```
background-position: bottom 10px right 20px
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-position`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-position](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-position)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-repeat.md
---

# background-repeat

APISummary
## Introduction

The `background-repeat` CSS property sets how background images are repeated. A background image can be repeated along the horizontal and vertical axes, or not repeated at all.

## Examples

**This is an example below: css-api**

**Entry:** `src/background-repeat`
**Bundle:** `dist/background-repeat.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundRepeat = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat-x" as const,
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "30px 40px",
      backgroundRepeat: "repeat" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "50% 40px, right bottom",
      backgroundRepeat: "repeat-y,repeat-x" as const,
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundRepeat />);

```



## Syntax

```css
background-repeat: repeat-x;
background-repeat: repeat-y;
background-repeat: repeat;
background-repeat: space;
background-repeat: round;
background-repeat: no-repeat;

background-repeat: repeat space;
background-repeat: repeat repeat;
background-repeat: round space;
background-repeat: no-repeat round;
```

### Values

- Default value **repeat** <br />
  The image is repeated as much as needed to cover the whole background image painting area. The last image will be clipped if it doesn't fit.

- no-repeat <br />
  The image is not repeated (and hence the background image painting area will not necessarily be entirely covered). The position of the non-repeated background image is defined by `background-position`(./background-position).

- repeat-x <br />
  Repeat along x-axis.

- repeat-y <br />
  Repeat along y-axis.

- space <br />
  The image is repeated as much as possible without clipping. The first and last images are pinned to either side of the element, and whitespace is distributed evenly between the images. And `background-position`(./background-position) is ignored.

- round <br />
  As the allowed space increases in size, the repeated images will stretch (leaving no gaps) until there is room (space left >= half of the image width) for another one to be added.

:::info
The rendering behavior of the `space` and `round` keywords is actually the same as that of `repeat`.
:::

## Formal definition

| Initial value | repeat |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round | no-repeat ]{1,2}
```

## ## Difference between web

- Not support `inherit`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-repeat`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-repeat](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-repeat)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background-size.md
---

# background-size

APISummary
## Introduction

The `background-size` CSS property sets the size of the element's background image. The image can be left to its natural size, stretched, or constrained to fit the available space.

## Examples

**This is an example below: css-api**

**Entry:** `src/background-size`
**Bundle:** `dist/background-size.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BackgroundSize = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const containerStyles = {
    style1: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
      backgroundSize: "50%",
    },
    style2: {
      backgroundOrigin: "padding-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat-x" as const,
      backgroundSize: "40px, 30px",
    },
    style3: {
      backgroundOrigin: "border-box" as const,
      backgroundPosition: "50% 50%",
      backgroundRepeat: "repeat" as const,
      backgroundSize: "cover" as const,
    },
    style4: {
      backgroundOrigin: "content-box,border-box" as const,
      backgroundPosition: "top left, right bottom",
      backgroundRepeat: "repeat-y,repeat-x" as const,
      backgroundSize: "50% 50%, contain",
    },
    style5: {
      backgroundOrigin: "content-box" as const,
      backgroundPosition: "left top" as const,
      backgroundRepeat: "no-repeat" as const,
      backgroundSize: "auto 200%",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={containerStyles.style1}></view>
        <view className="container image1" style={containerStyles.style2}></view>
        <view className="container image1" style={containerStyles.style3}></view>
        <view className="container image2" style={containerStyles.style4}></view>
        <view className="container image1" style={containerStyles.style5}></view>
      </view>
    </scroll-view>
  );
};

root.render(<BackgroundSize />);

```



## Syntax

```css
background-size: contain;

background-size: 50%;
background-size: 3em;

background-size: auto 1em;
background-size: 50% 25%;
```

### Values

- `cover` <br />
  Scales the image as large as possible within its container without cropping or stretching the image. If the container is larger than the image, this will result in image tiling, unless the [`background-repeat`](/api/css/properties/background-repeat.md) property is set to `no-repeat`.

- `contain` <br />
  Scales the image (while preserving its ratio) to the smallest possible size to fill the container (that is: both its height and width completely cover the container), leaving no empty space. If the proportions of the background differ from the element, the image is cropped either vertically or horizontally.

- Default value **auto** <br />
  Scales the background image in the corresponding direction such that its intrinsic proportions are maintained.

- [`<length>`](/api/css/data-type/length.md) <br />
  Stretches the image in the corresponding dimension to the specified length. Negative values are not allowed.

- [`<percentage>`](/api/css/data-type/percentage.md) <br />
  Stretches the image in the corresponding dimension to the specified percentage of the background positioning area. The background positioning area is determined by the value of [`background-origin`](/api/css/properties/background-origin.md) (by default, the padding box).

### Size Calculation

- If both components of `background-size` are specified and are not `auto`: <br />
  The background image is rendered at the specified size.

- `contain` or `cover`: <br />
  While preserving its intrinsic proportions, the image is rendered at the largest size contained within, or covering, the background positioning area. If the image has no intrinsic proportions, then it's rendered at the size of the background positioning area.

- If the background-size has one `auto` component and one `non-auto` component: <br />
  The image stretched to the specified dimension. The unspecified dimension is computed using the specified dimension and the intrinsic proportions.

## Notes

Do not use `auto` with `<gradient>`. It may cause some rendering issue in old version SDK.

## Formal definition

| Initial value | auto auto |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
<bg-size> = (<length-percentage> | auto){1,2} | cover | contain
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background-size`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-size](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background-size)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/background.md
---

# background

APISummary
## Introduction

The `background` shorthand CSS property sets all background style properties at once, such as [`background-clip`](/api/css/properties/background-clip.md),[`background-color`](/api/css/properties/background-color.md),[`background-image`](/api/css/properties/background-image.md),[`background-origin`](/api/css/properties/background-origin.md),[`background-position`](/api/css/properties/background-position.md),[`background-repeat`](/api/css/properties/background-repeat.md),[`background-size`](/api/css/properties/background-size.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/background`
**Bundle:** `dist/background.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Background = () => {
  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const container1Style = {
    backgroundOrigin: "content-box" as const,
    backgroundPosition: "left top" as const,
    backgroundRepeat: "no-repeat" as const,
  };

  const container2Style = {
    backgroundOrigin: "padding-box" as const,
    backgroundPosition: "50% 50%",
    backgroundRepeat: "repeat-x" as const,
  };

  const container3Style = {
    backgroundOrigin: "border-box" as const,
    backgroundPosition: "30px 40px",
    backgroundRepeat: "repeat" as const,
  };

  const container4Style = {
    backgroundOrigin: "content-box,border-box" as const,
    backgroundPosition: "50% 40px, right bottom",
    backgroundRepeat: "repeat-y,repeat-x" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="container image1" style={container1Style}></view>
        <view className="container image1" style={container2Style}></view>
        <view className="container image1" style={container3Style}></view>
        <view className="container image2" style={container4Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<Background />);

```



## Syntax

```css
/* Using a <background-color> */
background: green;

/* Using a <bg-image> and <repeat-style> */
background: url('test.jpg') repeat-y;

/* Using a <box> and <background-color> */
background: border-box red;

/* A single image, centered and scaled */
background: no-repeat center / 80% url('../img/image.png');
```

The background property is specified as one or more background layers, separated by commas.

The syntax of each layer is as follows:

- [`<bg-image>`](#bg-image)
- [`<position>`](#position)
- [`<bg-size>`](#bg-size)
- [`<repeat-style>`](#repeat-style)
- The `<bg-size>` value may only be included immediately after `<position>`, separated with the '/' character, like this: `"center/80%"`.
- The `<box>` value may be included zero, one, or two times. If included once, it sets both [`background-origin`](/api/css/properties/background-origin.md) and [`background-clip`](/api/css/properties/background-clip.md). If it is included twice, the first occurrence sets [`background-origin`](/api/css/properties/background-origin.md), and the second sets [`background-clip`](/api/css/properties/background-clip.md).

> **The [`background-color`](/api/css/properties/background-color.md) value may only be included in the last layer specified.**

## Values

#### `<box>` \{#box}

See [`background-clip`](/api/css/properties/background-clip.md) and [`background-origin`](/api/css/properties/background-origin.md)

#### `<background-color>` \{#background-color}

See [`background-color`](/api/css/properties/background-color.md)

#### `<bg-image>` \{#bg-image}

See [`background-image`](/api/css/properties/background-image.md)

#### `<position>` \{#position}

See [`background-position`](/api/css/properties/background-position.md)

#### `<repeat-style>` \{#repeat-style}

See [`background-repeat`](/api/css/properties/background-repeat.md)

#### `<bg-size>` \{#bg-size}

See [`background-size`](/api/css/properties/background-size.md)

## Note

- The background-color must be written in the last image, otherwise the parser will consider it an invalid background.
  For example: `background: red url('./a.png'), url('./b.png);'` will be ignored as an error.
  The correct way to write it should be: `background: url('./a.png'),red url('./b.png);`

## Formal definition

| Initial value | background-image: none
background-position: 0% 0%
background-size: auto auto
background-repeat: repeat
background-origin: padding-box
background-clip: border-box
background-color: transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
[ <bg-layer> , ]* <final-bg-layer>

where

<bg-layer> = <bg-image> || <bg-position> [ / <bg-size> ]? || <repeat-style> || <box> || <box>
<final-bg-layer> = <'background-color'> || <bg-image> || <bg-position> [ / <bg-size> ]? || <repeat-style> || <attachment> || <box> || <box>

where

<bg-image> = none | <image>
<bg-position> = [ [ left | center | right | top | bottom | <length-percentage> ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ] | [ center | [ left | right ] <length-percentage>? ] && [ center | [ top | bottom ] <length-percentage>? ] ]
<bg-size> = [ <length-percentage> | auto ]{1,2} | cover | contain
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round | no-repeat ]{1, 2}
<box> = border-box | padding-box | content-box

where

<image> = <url> | <gradient>
<length-percentage> = <length> | <percentage>

where

<gradient> = <linear-gradient> | <radial-gradient>

```

## Difference between web

- `<bg-layer>` does not support the [`<attachment>`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background#attachment)
- `<image>` only support `<url>` and `<gradient>`
  > \_These properties are also supported in web such as `<image-set>`、`<element()>`、`<paint()>`、`<cross-fade()>` \_<br />
- `<gradient>` only support `<linear-gradient>` and `<radial-gradient>`
  > _These properties are also supported in web such as `<repeating-linear-gradient()>`,`<radial-gradient()>`,`<repeating-radial-gradient()>`,`<conic-gradient()>`_

## Compatibility

**Compatibility Table**
**Query:** `css.properties.background`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/background](https://developer.mozilla.org/zh-CN/docs/Web/CSS/background)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-color.md
---

# border-bottom-color

APISummary
## Introduction

Sets the bottom border color of an element. Used when you need to specify the bottom border color separately.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom-color`
**Bundle:** `dist/border-bottom-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottomColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderBottomColor />);

```



## Syntax

```css
border-bottom-color: red;

border-bottom-color: '#ff0000';
```

### Values

- [`<color>`](/api/css/data-type/color.md)

## Formal Definition

| Initial value | Empty |
| Applies to | All elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```css
border-bottom-color = <color>
<color> = <rgb()> | <rgba()> | <hsl()> | <hsla()> | <hex-color> | <named-color>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color)
- Different default value (Web uses `currentColor`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-left-radius.md
---

# border-bottom-left-radius

APISummary
## Introduction

Used to add a rounded border to the bottom-left corner. The first value sets the horizontal radius, and the second value sets the vertical radius. If the second value is omitted, it copies the first value. A value of zero results in a square corner rather than a rounded one. The percentage value of the horizontal radius is relative to the border box width, while the percentage value of the vertical radius is relative to the border box height.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom-left-radius`
**Bundle:** `dist/border-bottom-left-radius.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottomLeftRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderBottomLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomLeftRadius />);

```



## Syntax

```css
/* The corner is a circle */
/* border-bottom-left-radius: radius */
border-bottom-left-radius: 3px;

/* The corner is an ellipse */
/* border-bottom-left-radius: horizontal vertical */
border-bottom-left-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Defines the specific size of the border radius (default is `0`).

- [`<percentage>`](/api/css/data-type/percentage.md)
  Defines the border radius in percentage (horizontal radius is relative to the border box width, vertical radius is relative to the height).

## Formal Definition

| Initial value | 0 |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-bottom-left-radius = <length-percentage>{1,2}
<length-percentage> = <length> | <percentage>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-left-radius)
- Does not support global values (`inherit` / `initial` / `revert` / `unset`).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-left-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-left-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-left-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-right-radius.md
---

# border-bottom-right-radius

APISummary
## Introduction

Used to add a rounded border to the bottom-right corner. The first value sets the horizontal radius, and the second value sets the vertical radius. If the second value is omitted, it copies the first value. A value of zero results in a square corner rather than a rounded one. The percentage value of the horizontal radius is relative to the border box width, while the percentage value of the vertical radius is relative to the border box height.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom-right-radius`
**Bundle:** `dist/border-bottom-right-radius.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottomRightRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderBottomRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomRightRadius />);

```



## Syntax

```css
border-bottom-right-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Defines the specific size of the border radius (default is `0`).

- [`<percentage>`](/api/css/data-type/percentage.md)
  Defines the border radius in percentage (horizontal radius is relative to the border box width, vertical radius is relative to the height).

## Formal Definition

| Initial value | 0 |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-bottom-right-radius = <length-percentage>{1,2}
<length-percentage> = <length> | <percentage>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-right-radius)
- Does not support global values (`inherit` / `initial` / `revert` / `unset`).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-right-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-right-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-right-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-style.md
---

# border-bottom-style

APISummary
## Introduction

Sets the style type of the bottom border of an element. Used when you need to specify the bottom border style separately.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom-style`
**Bundle:** `dist/border-bottom-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottomStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidth1 radiusDiff"
                  style={{ borderBottomStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomStyle />);

```



## Syntax

```css
border-bottom-style: dashed;
```

### Values

- `none`: No border style (border width remains unchanged)
- `hidden`: Hides the border (equivalent to `none`, used in table layouts to resolve border conflicts)
- `dotted`: Dotted border (renders as a solid line)
- `dashed`: Dashed border (renders as a solid line)
- `solid`: Solid line
- `double`: Double line (total width equals `border-width` value)
- `groove`: 3D groove effect (depends on `border-color`)
- `ridge`: 3D ridge effect (depends on `border-color`)
- `inset`: Inset effect (depends on `border-color`)
- `outset`: Outset effect (depends on `border-color`)

## Formal Definition

| Initial value | solid |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-bottom-style = <line-style>
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-style)
- Different default value (Web uses `none`)
- When set to `none` or `hidden`, the border width remains unchanged (on the Web, it is set to `0`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom-width.md
---

# border-bottom-width

APISummary
## Introduction

Used to set the width of the bottom border.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom-width`
**Bundle:** `dist/border-bottom-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottomWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderBottomWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottomWidth />);

```



## Syntax

```css
border-bottom-width: 10px;
```

### Values

- `thin`: Thin border (2px)
- `medium`: Medium border (4px)
- `thick`: Thick border (6px)
- [`<length>`](/api/css/data-type/length.md): Specific size value

## Formal Definition

| Initial value | 0 |
| Applies to | All elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```css
border-bottom-width = <line-width>
<line-width> = thin | medium | thick | <length>
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width)
- Different specific size values (Web standard: `thin=1px, medium=3px, thick=5px`)
- Different default value (Web uses `medium`)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-bottom.md
---

# border-bottom

APISummary
## Introduction

Used to set the styles related to the bottom border. This property allows setting `border-bottom-width`, `border-bottom-style`, and `border-bottom-color` in order.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-bottom`
**Bundle:** `dist/border-bottom.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderBottom = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view key={`normal-${rowIndex}-${colIndex}`} className="box" style={{ borderBottom: borderStyle }}>
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderBottom: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderBottom />);

```



## Syntax

```css
/* Bottom border with thick double red lines */
border-bottom: thick double red;

/* Bottom border with thin dotted blue lines */
border-bottom: thin dotted blue;

/* Bottom border with a 10px dashed orange line */
border-bottom: 10px dashed orange;
```

### Values

Accepts the following value types in order:

- [`<line-width>`](/api/css/properties/border-bottom.md#formal-definition)
  - See [`<border-bottom-width>`](/api/css/properties/border-bottom-width.md)

- [`<line-style>`](/api/css/properties/border-bottom.md#formal-definition)
  - See [`<border-bottom-style>`](/api/css/properties/border-bottom-style.md)

- [`<color>`](/api/css/data-type/color.md)
  - See [`<border-bottom-color>`](/api/css/properties/border-bottom-color.md)

## Formal Definition

| Initial value | Empty |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-bottom =
  <line-width>  ||
  <line-style>  ||
  <color>

<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [mdn:border-bottom](https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom)
- Does not support global values like `inherit`, `initial`, `revert`, and `unset`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-color.md
---

# border-color

APISummary
## Introduction

The `border-color` shorthand CSS property sets the color ([`border-top-color`](/api/css/properties/border-top-color.md), [`border-right-color`](/api/css/properties/border-right-color.md), [`border-bottom-color`](/api/css/properties/border-bottom-color.md), [`border-left-color`](/api/css/properties/border-left-color.md)) of an element's border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-color`
**Bundle:** `dist/border-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderColor = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const colors = [
    ["red", "rgb(255,0,0) rgba(0,255,0,0.3)"],
    ["#ff0000 #00ff00ff #aabbccdd", "black orange transparent pink"],
    ["black rgb(255,255,0) #ff00ff pink", "hsl(89,43%,51%) hsla(89,43%,51%,0.3) red transparent"],
  ];

  const colors2 = [
    ["green blue", "pink rgb(0,0,255) rgba(128,0,128,0.8)"],
    ["#ff00ff #00ffffbb #2211ffaa", "blue pink"],
    ["#aab #ff00ff hsl(89,43%,20%)", "hsl(89,60%,31%) blue"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {colors.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box widthSame solid"
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {colors2.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box widthSame styleDiff${colIndex}`}
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {colors.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((color, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box widthDiff styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderColor: color }}
                >
                  <text className="text">{color}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderColor />);

```



## Syntax

```css
/* border-color: color; */
border-color: red;

/* border-color: vertical horizontal; */
border-color: red #f015ca;

/* border-color: top horizontal bottom; */
border-color: red yellow green;

/* border-color: top right bottom left; */
border-color: red yellow green blue;
```

### Values

The [`<color>`](/api/css/data-type/color.md) property may be specified using one, two, three, or four values.

- When one value is specified, it applies the same color to all four sides.
- When two values are specified, the first color applies to the [`border-top-color`](/api/css/properties/border-top-color.md) and [`border-bottom-color`](/api/css/properties/border-bottom-color.md), the second to the [`border-left-color`](/api/css/properties/border-left-color.md) and [`border-right-color`](/api/css/properties/border-right-color.md).
- When three values are specified, the first color applies to the [`border-top-color`](/api/css/properties/border-top-color.md), the second to the [`border-left-color`](/api/css/properties/border-left-color.md) and [`border-right-color`](/api/css/properties/border-right-color.md), the third to the [`border-bottom-color`](/api/css/properties/border-bottom-color.md).
- When four values are specified, the colors apply to the [`border-top-color`](/api/css/properties/border-top-color.md), [`border-right-color`](/api/css/properties/border-right-color.md), [`border-bottom-color`](/api/css/properties/border-bottom-color.md) and [`border-left-color`](/api/css/properties/border-left-color.md) in that order (clockwise).

## Formal definition

| Initial value | transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
<color>{1, 4}
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-end-end-radius.md
---

# border-end-end-radius

APISummary
## Introduction

The `border-end-end-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-bottom-right-radius`](/api/css/properties/border-bottom-right-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-bottom-left-radius`](/api/css/properties/border-bottom-left-radius.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-end-end-radius`
**Bundle:** `dist/border-end-end-radius.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderEndEndRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderEndEndRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderEndEndRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-end-radius: radius */
border-end-end-radius: 3px;

/* the corner is an ellipsis */
/* border-end-end-radius: horizontal vertical */
border-end-end-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-end-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-end-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-end-end-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-end-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-end-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-end-start-radius.md
---

# border-end-start-radius

APISummary
## Introduction

The `border-end-start-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-bottom-left-radius`](/api/css/properties/border-bottom-left-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-bottom-right-radius`](/api/css/properties/border-bottom-right-radius.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-end-start-radius`
**Bundle:** `dist/border-end-start-radius.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderEndStartRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderEndStartRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderEndStartRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-start-radius: radius */
border-end-start-radius: 3px;

/* the corner is an ellipsis */
/* border-end-start-radius: horizontal vertical */
border-end-start-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-end-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-end-start-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-end-start-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-start-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-end-start-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-color.md
---

# border-inline-end-color

APISummary
## Introduction

The `border-inline-end-color` CSS property defines the color of the logical inline-end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-color`](/api/css/properties/border-right-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-color`](/api/css/properties/border-left-color.md) property.

## Examples

![demo](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/border-color.png)

## Syntax

```css
border-inline-end-color: red;
border-inline-end-color: #ffbb00;
border-inline-end-color: rgb(255, 0, 0);
border-inline-end-color: hsla(100%, 50%, 25%, 0.75);
border-inline-end-color: currentColor;
border-inline-end-color: transparent;
```

### Values

- `transparent`

- [`<color>`](/api/css/data-type/color.md)

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
transparent | <color>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-style.md
---

# border-inline-end-style

APISummary
## Introduction

The `border-inline-end-style` CSS property defines the style of the logical inline end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-style`](/api/css/properties/border-right-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-style`](/api/css/properties/border-left-style.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-inline-end-style`
**Bundle:** `dist/border-inline-end-style.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderInlineEndStyle = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartStyle: "dashed",
    borderInlineEndStyle: "solid",
  } as const;

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineEndStyle />);

```



## Syntax

```css
border-inline-end-style: none;
border-inline-end-style: hidden;
border-inline-end-style: dotted;
border-inline-end-style: dashed;
border-inline-end-style: solid;
border-inline-end-style: double;
border-inline-end-style: groove;
border-inline-end-style: ridge;
border-inline-end-style: inset;
border-inline-end-style: outset;
```

### Values

- `none`

- `hidden`

- `dotted`

- `dashed`

- **default** `solid`

- `double`

- `groove`

- `ridge`

- `inset`

- `outset`

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-end-width.md
---

# border-inline-end-width

APISummary
## Introduction

The `border-inline-end-width` CSS property defines the width of the logical inline-end border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-right-width`](/api/css/properties/border-right-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-left-width`](/api/css/properties/border-left-width.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-inline-end-width`
**Bundle:** `dist/border-inline-end-width.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderInlineEndWidth = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartWidth: "5px",
    borderInlineEndWidth: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineEndWidth />);

```



## Syntax

```css
border-inline-end-width: thin;
border-inline-end-width: medium;
border-inline-end-width: thick;
border-inline-end-width: 10px;
```

### Values

- `thin`

- `medium`

- `thick`

- [`<length>`](/api/css/data-type/length.md)

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-end-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-width)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-end-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-end-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-color.md
---

# border-inline-start-color

APISummary
## Introduction

The `border-inline-start-color` CSS property defines the color of the logical inline start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-color`](/api/css/properties/border-left-color.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-color`](/api/css/properties/border-right-color.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-inline-start-color`
**Bundle:** `dist/border-inline-start-color.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderInlineStartColor = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartColor: "blue",
    borderInlineEndColor: "yellow",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartColor />);

```



## Syntax

```css
border-inline-start-color: red;
border-inline-start-color: #ffbb00;
border-inline-start-color: rgb(255, 0, 0);
border-inline-start-color: hsla(100%, 50%, 25%, 0.75);
border-inline-start-color: currentColor;
border-inline-start-color: transparent;
```

### Values

- `transparent`

- [`<color>`](/api/css/data-type/color.md)

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
transparent | <color>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-style.md
---

# border-inline-start-style

APISummary
## Introduction

The `border-inline-start-style` CSS property defines the style of the logical inline start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-style`](/api/css/properties/border-left-style.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-style`](/api/css/properties/border-right-style.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-inline-start-style`
**Bundle:** `dist/border-inline-start-style.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderInlineStartStyle = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartStyle: "dashed",
    borderInlineEndStyle: "solid",
  } as const;

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartStyle />);

```



## Syntax

```css
border-inline-start-style: none;
border-inline-start-style: hidden;
border-inline-start-style: dotted;
border-inline-start-style: dashed;
border-inline-start-style: solid;
border-inline-start-style: double;
border-inline-start-style: groove;
border-inline-start-style: ridge;
border-inline-start-style: inset;
border-inline-start-style: outset;
```

### Values

- `none`

- `hidden`

- `dotted`

- `dashed`

- **default** `solid`

- `double`

- `groove`

- `ridge`

- `inset`

- `outset`

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-inline-start-width.md
---

# border-inline-start-width

APISummary
## Introduction

The `border-inline-start-width` CSS property defines the width of the logical inline-start border of an element.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-left-width`](/api/css/properties/border-left-width.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-right-width`](/api/css/properties/border-right-width.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-inline-start-width`
**Bundle:** `dist/border-inline-start-width.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderInlineStartWidth = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderInlineStartWidth: "5px",
    borderInlineEndWidth: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderInlineStartWidth />);

```



## Syntax

```css
border-inline-start-width: thin;
border-inline-start-width: medium;
border-inline-start-width: thick;
border-inline-start-width: 10px;
```

### Values

- `thin`

- `medium`

- `thick`

- [`<length>`](/api/css/data-type/length.md)

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
thin | medium | thick | <length>
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-inline-start-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-width)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-inline-start-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-inline-start-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-color.md
---

# border-left-color

APISummary
## Introduction

Used to set the color of the left border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-left-color`
**Bundle:** `dist/border-left-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderLeftColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderLeftColor />);

```



## Syntax

```css
border-left-color: red;
border-left-color: #ffbb00;
border-left-color: rgb(255, 0, 0);
border-left-color: hsla(100%, 50%, 25%, 0.75);
border-left-color: currentColor;
border-left-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition

| Initial value | transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-style.md
---

# border-left-style

APISummary
## Introduction

The **border-left-style** CSS property sets the line style of an element's left [`border`](/api/css/properties/border.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/border-left-style`
**Bundle:** `dist/border-left-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderLeftStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderLeftStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeftStyle />);

```



## Syntax

```css
border-left-style: none;
border-left-style: hidden;
border-left-style: dotted;
border-left-style: dashed;
border-left-style: solid;
border-left-style: double;
border-left-style: groove;
border-left-style: ridge;
border-left-style: inset;
border-left-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-left-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left-width.md
---

# border-left-width

APISummary
## Introduction

Used to set the width of the left border.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-left-width`
**Bundle:** `dist/border-left-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderLeftWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderLeftWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeftWidth />);

```



## Syntax

```css
border-left-width: thin;
border-left-width: medium;
```

### Values

- `thin`
  Thin border.

- `medium`
  Medium border.

- `thick`
  Thick border.

- [`<length>`](/api/css/data-type/length.md)
  Defines the border width with a specific size.

## Formal Definition

| Initial value | 0 |
| Applies to | All elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```css
border-left-width = <line-width>
<line-width> = thin | medium | thick | <length>
```

## Differences from the Web

- [mdn:border-left-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width)
- Does not support `inherit`, `initial`, `revert`, or `unset`.
- Default value is `0`, whereas the web default is `medium`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-left.md
---

# border-left

APISummary
## Introduction

A shorthand property for setting the left border styles of an element. It includes [`border-left-width`](/api/css/properties/border-left-width.md), [`border-left-style`](/api/css/properties/border-left-style.md), and [`border-left-color`](/api/css/properties/border-left-color.md) in order.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-left`
**Bundle:** `dist/border-left.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderLeft = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderLeft: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderLeft: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderLeft />);

```



## Syntax

```css
border-left: 1px solid red;
```

## Values

Can be set in order as follows:

- [`border-left-width`](/api/css/properties/border-left-width.md)
  The width of the border.

- [`border-left-style`](/api/css/properties/border-left-style.md)
  The style of the border.

- [`border-left-color`](/api/css/properties/border-left-color.md)
  The color of the border.

## Formal Definition

| Initial value | Empty |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-left = <line-width> <line-style> <color>
```

## Differences from the Web

- [mdn:border-left](https://developer.mozilla.org/en-US/docs/Web/CSS/border-left)
- Does not support `inherit`, `initial`, `revert`, or `unset`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-radius.md
---

# border-radius

APISummary
## Introduction

The border-radius CSS property rounds the corners of an element's outer border edge. You can set a single radius to make circular corners, or two radii to make elliptical corners.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-radius`
**Bundle:** `dist/border-radius.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em / 5em"],
    ["2em 1em 4em / 0.5em 3em", "15px 50px"],
    ["15px 50px 30px 5px", "1em 2em 4em 4em / 1em 2em 2em 8em"],
    ["100px 200px", "100px 30px / 10px"],
    ["100em / 200em", "2px 0px 2em / 0em 100px"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRadius />);

```



## Syntax

```css
/* The syntax of the first radius allows one to four values */
/* Radius is set for all 4 sides */
border-radius: 10px;

/* top-left-and-bottom-right | top-right-and-bottom-left */
border-radius: 10px 5%;

/* top-left | top-right-and-bottom-left | bottom-right */
border-radius: 2px 4px 2px;

/* top-left | top-right | bottom-right | bottom-left */
border-radius: 1px 0 3px 4px;

/* The syntax of the second radius allows one to four values */
/* (first radius values) / radius */
border-radius: 10px / 20px;

/* (first radius values) / top-left-and-bottom-right | top-right-and-bottom-left */
border-radius: 10px 5% / 20px 30px;

/* (first radius values) / top-left | top-right-and-bottom-left | bottom-right */
border-radius: 10px 5px 2em / 20px 25px 30%;

/* (first radius values) / top-left | top-right | bottom-right | bottom-left */
border-radius: 10px 5% / 20px 25em 30px 35em;
```

The `border-radius` property is specified as:

- one, two, three, or four [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) values. This is used to set a single radius for the corners.
- followed optionally by "/" and one, two, three, or four [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md)values. This is used to set an additional radius, so you can have elliptical corners.

### Values

- [`<length>`](/api/css/data-type/length.md)
  Denotes the size of the circle radius, or the semi-major and semi-minor axes of the ellipse, using length values. Negative values are invalid.

- [`<percentage>`](/api/css/data-type/percentage.md)
  Denotes the size of the circle radius, or the semi-major and semi-minor axes of the ellipse, using percentage values. Percentages for the horizontal axis refer to the width of the box; percentages for the vertical axis refer to the height of the box. Negative values are invalid.

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
border-radius =
  <length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference from Web

- [mdn:border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-color.md
---

# border-right-color

APISummary
## Introduction

Used to set the color of the right border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-right-color`
**Bundle:** `dist/border-right-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderRightColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderRightColor />);

```



## Syntax

```css
border-right-color: red;
border-right-color: #ffbb00;
border-right-color: rgb(255, 0, 0);
border-right-color: hsla(100%, 50%, 25%, 0.75);
border-right-color: currentColor;
border-right-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition

| Initial value | transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-style.md
---

# border-right-style

APISummary
## Introduction

The **border-right-style** CSS property sets the line style of an element's right [`border`](/api/css/properties/border.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/border-right-style`
**Bundle:** `dist/border-right-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderRightStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderRightStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRightStyle />);

```



## Syntax

```css
border-right-style: none;
border-right-style: hidden;
border-right-style: dotted;
border-right-style: dashed;
border-right-style: solid;
border-right-style: double;
border-right-style: groove;
border-right-style: ridge;
border-right-style: inset;
border-right-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-right-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right-width.md
---

# border-right-width

APISummary
## Introduction

The border-right-width CSS property sets the width of the left border of an element.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-right-width`
**Bundle:** `dist/border-right-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderRightWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderRightWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRightWidth />);

```



## Syntax

```css
/* Keyword values */
border-right-width: thin;
border-right-width: medium;
border-right-width: thick;

/* <length> values */
border-right-width: 10rem;
border-right-width: 6px;
```

### Values

`<line-width>`

Defines the width of the border, either as an explicit nonnegative [`<length>`](/api/css/data-type/length.md) or a keyword. If it's a keyword, it must be one of the following values:

- thin
- medium
- thick

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
border-right-width =
  <line-width>

<line-width> =
  <length [0,∞]>  |
  thin            |
  medium          |
  thick
```

## Difference from Web

- [mdn:border-right-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width)

Global values are not supported (inherit, initial, revert, unset, etc).

Default value is 0, different to 'medium' in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-right.md
---

# border-right

APISummary
## Introduction

The border-right shorthand CSS property sets all the properties of an element's right border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-right`
**Bundle:** `dist/border-right.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderRight = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderRight: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderRight: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderRight />);

```



## Syntax

```css
.br-0 {
  border-right: thick double red;
}
.br-1 {
  border-right: thin dotted blue;
}

.br-2 {
  border-right: 10px dashed orange;
}
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-right-width`](/api/css/properties/border-right-width.md)
  width of the border

- [`border-right-style`](/api/css/properties/border-right-style.md)
  style of the border

- [`border-right-color`](/api/css/properties/border-right-color.md)
  color of the border

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Difference from Web

- [mdn:border-right](https://developer.mozilla.org/en-US/docs/Web/CSS/border-right)

Global values are not supported. (inherit, initial, revert, unset, etc)

Default style value is `solid`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-start-end-radius.md
---

# border-start-end-radius

APISummary
## Introduction

The `border-start-end-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-top-right-radius`](/api/css/properties/border-top-right-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-top-left-radius`](/api/css/properties/border-top-left-radius.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-start-end-radius`
**Bundle:** `dist/border-start-end-radius.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderStartEndRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderStartEndRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderStartEndRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-end-radius: radius */
border-start-end-radius: 3px;

/* the corner is an ellipsis */
/* border-end-end-radius: horizontal vertical */
border-start-end-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
[<length> | <percentage>] [ / [<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-start-end-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-end-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-start-end-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-end-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-end-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-start-start-radius.md
---

# border-start-start-radius

APISummary
## Introduction

The `border-start-start-radius` CSS property defines a logical border radius on an element, which notes the size of the circle radius or the semi-major and semi-minor axes of the ellipse.

In a horizontal-tb writing mode with `LTR` direction, it corresponds to the [`border-top-left-radius`](/api/css/properties/border-top-left-radius.md) property.
In a horizontal-tb writing mode with `RTL` direction, it corresponds to the [`border-top-right-radius`](/api/css/properties/border-top-right-radius.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-start-start-radius`
**Bundle:** `dist/border-start-start-radius.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const BorderStartStartRadius = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const textStyle = {
    borderStartStartRadius: "40px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={textStyle}>1</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<BorderStartStartRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-end-start-radius: radius */
border-end-start-radius: 3px;

/* the corner is an ellipsis */
/* border-end-start-radius: horizontal vertical */
border-end-start-radius: 0.5em 1em;
```

### Values

- [`<length>`](/api/css/data-type/length.md)

- [`<percentage>`](/api/css/data-type/percentage.md)

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
[<length> | <percentage>] [[<length> | <percentage>]]?
```

## Extensions

- [direction](/api/css/properties/direction.md)
- [mdn:border-start-start-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-start-start-radius)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-start-start-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-start-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-start-start-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-style.md
---

# border-style

APISummary
## Introduction

Used to set the styles of all four borders. This property can define the styles for the top, right, bottom, and left borders in order.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-style`
**Bundle:** `dist/border-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
    ["dotted groove", "dotted solid double", "groove solid double dashed"],
    ["outset inset", "solid none dashed", "dotted solid dashed inset"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidthSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidthSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidthDiff2 radiusSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidthDiff radiusDiff"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderStyle />);

```



## Syntax

```css
border-style: double solid dotted dashed;
```

### Values

- none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
- Supports 1-4 value syntax (top → right → bottom → left).

## Formal Definition

| Initial value | solid |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```css
border-style = [ <line-style> ]{1,4}
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style)
- Default value is different (Web default is `none`).
- When the value is `none` or `hidden`, the border width remains unchanged (Web sets it to `0`).
- Does not support `inherit`, `initial`, `revert`, or `unset` global values.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-color.md
---

# border-top-color

APISummary
## Introduction

Used to set the color of the top border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top-color`
**Bundle:** `dist/border-top-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTopColor = () => {
  return (
    <view className="intro">
      <text className="border-color">
        {"\n border-left-color: red; \n border-right-color: blue; \n border-top-color: green; \n border-bottom-color: black; \n"}
      </text>
    </view>
  );
};

root.render(<BorderTopColor />);

```



## Syntax

```css
border-top-color: red;
border-top-color: #ffbb00;
border-top-color: rgb(255, 0, 0);
border-top-color: hsla(100%, 50%, 25%, 0.75);
border-top-color: currentColor;
border-top-color: transparent;
```

### Values

- `transparent`
  The border color is transparent.

- [`<color>`](/api/css/data-type/color.md)
  The specific color of the border.

## Formal definition

| Initial value | transparent |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
transparent | <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-left-radius.md
---

# border-top-left-radius

APISummary
## Introduction

The border-top-left-radius CSS property rounds the bottom-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top-left-radius`
**Bundle:** `dist/border-top-left-radius.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTopLeftRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderTopLeftRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopLeftRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-top-left-radius: radius */
border-top-left-radius: 3px;

/* Percentage values */

/* circle if box is a square or ellipse if box is a rectangle */
border-top-left-radius: 20%;

/* same as above: 20% of horizontal(width) and vertical(height) */
border-top-left-radius: 20% 20%;

/* 20% of horizontal(width) and 10% of vertical(height) */
border-top-left-radius: 20% 10%;

/* the corner is an ellipse */
/* border-top-left-radius: horizontal vertical */
border-top-left-radius: 0.5em 1em;
```

With one value:

- the value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the radius of the circle to use for the border in that corner.

With two values:

- the first value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the horizontal semi-major axis of the ellipse to use for the border in that corner.
- the second value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the vertical semi-major axis of the ellipse to use for the border in that corner.

### Values

`<length-percentage>`

Denotes the size of the circle radius or the semi-major and semi-minor axes of the ellipse. As absolute length it can be expressed in any unit allowed
by the CSS [`<length>`](/api/css/data-type/length.md) data type. Percentages for the horizontal axis refer to the width of the box, percentages for the vertical
axis refer to the height of the box. Negative values are invalid.

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
border-top-left-radius =
  <length-percentage [0,∞]>{1,2}

<length-percentage> =
  <length>      |
  <percentage>
```

Examples:

```css
/* the corner is a circle */
/* border-top-left-radius: radius */
border-top-left-radius: 3px;

/* the corner is an ellipsis */
/* border-top-left-radius: horizontal vertical */
border-top-left-radius: 0.5em 1em;
```

## Difference from Web

- [mdn:border-top-left-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-left-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-left-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-left-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-left-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-right-radius.md
---

# border-top-right-radius

APISummary
## Introduction

The border-top-right-radius CSS property rounds the bottom-left corner of an element by specifying the radius (or the radius of the semi-major and semi-minor axes) of the ellipse defining the curvature of the corner.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top-right-radius`
**Bundle:** `dist/border-top-right-radius.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTopRightRadius = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["2em", "2em 5em"],
    ["100px 500px", "50px 15px"],
    ["200px", "200em 100em"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`same-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`same-${rowIndex}-${colIndex}`}
                  className={`box size0 styleDiff${colIndex} colorWidthSame`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`diff-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`diff-${rowIndex}-${colIndex}`}
                  className={`box size0 colorWidthDiff${colIndex}`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`mixed-${rowIndex}`}>
            <view className="row">
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed1-${rowIndex}-${colIndex}`}
                  className={`box size1 styleDiff${colIndex} colorWidthDiff${colIndex}`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
              {row.map((radius, colIndex) => (
                <view
                  key={`mixed2-${rowIndex}-${colIndex}`}
                  className={`box size2 colorWidthSame styleDiff2`}
                  style={{ borderTopRightRadius: radius }}
                >
                  <text className="text">{radius}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopRightRadius />);

```



## Syntax

```css
/* the corner is a circle */
/* border-top-right-radius: radius */
border-top-right-radius: 3px;

/* Percentage values */

/* circle if box is a square or ellipse if box is a rectangle */
border-top-right-radius: 20%;

/* same as above: 20% of horizontal(width) and vertical(height) */
border-top-right-radius: 20% 20%;

/* 20% of horizontal(width) and 10% of vertical(height) */
border-top-right-radius: 20% 10%;

/* the corner is an ellipse */
/* border-top-right-radius: horizontal vertical */
border-top-right-radius: 0.5em 1em;
```

With one value:

- the value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the radius of the circle to use for the border in that corner.

With two values:

- the first value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the horizontal semi-major axis of the ellipse to use for the border in that corner.
- the second value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md) denoting the vertical semi-major axis of the ellipse to use for the border in that corner.

### Values

`<length-percentage>`

Denotes the size of the circle radius or the semi-major and semi-minor axes of the ellipse. As absolute length it can be expressed in any unit allowed
by the CSS [`<length>`](/api/css/data-type/length.md) data type. Percentages for the horizontal axis refer to the width of the box, percentages for the vertical
axis refer to the height of the box. Negative values are invalid.

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
border-top-right-radius =
  <length-percentage [0,∞]>{1,2}

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference from Web

- [mdn:border-top-right-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-right-radius)

Global values are not supported, (inherit, initial, revert, unset, etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-right-radius`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-right-radius](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-right-radius)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-style.md
---

# border-top-style

APISummary
## Introduction

The `border-top-style` CSS property sets the line style of an element's top [`border`](/api/css/properties/border.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top-style`
**Bundle:** `dist/border-top-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTopStyle = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["solid", "dashed", "dotted"],
    ["double", "groove", "ridge"],
    ["inset", "outset", "hidden"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal1-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal1-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`normal2-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`normal2-${rowIndex}-${colIndex}`}
                  className="box colorWidth1"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-same-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-same-${rowIndex}-${colIndex}`}
                  className="box colorWidth2 radiusSame"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-diff-${rowIndex}`}>
            <view className="row">
              {row.map((style, colIndex) => (
                <view
                  key={`radius-diff-${rowIndex}-${colIndex}`}
                  className="box colorWidth1 radiusDiff"
                  style={{ borderStyle: style }}
                >
                  <text className="text">{style}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopStyle />);

```



## Syntax

```css
border-top-style: none;
border-top-style: hidden;
border-top-style: dotted;
border-top-style: dashed;
border-top-style: solid;
border-top-style: double;
border-top-style: groove;
border-top-style: ridge;
border-top-style: inset;
border-top-style: outset;
```

### Values

- `none`
  Like the `hidden` keyword, displays no border.

- `hidden`
  Like the `none` keywork, displays no border.

- `dotted`
  Displays a series of rounded dots. The spacing of the dots is not defined by the specification and is implementation-specific. The radius of the dots is half the computed value of the same side's [`border-width`](/api/css/properties/border-width.md).

- `dashed`
  Displays a series of short square-ended dashes or line segments. The exact size and length of the segments are not defined by the specification and are implementation-specific.

- `solid`
  Displays a single, straight, solid line.

- `double`
  Displays two straight lines that add up to the pixel size defined by [`border-width`](/api/css/properties/border-width.md).

- `groove`
  Displays a border with a carved appearance. It is the opposite of ridge.

- `ridge`
  Displays a border with an extruded appearance. It is the opposite of groove.

- `inset`
  Displays a border that makes the element appear embedded. It is the opposite of outset.

- `outset`
  Displays a border that makes the element appear embossed. It is the opposite of inset.

## Formal definition

| Initial value | solid |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<line-style>
where
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Differences from web

- [mdn:border-top-style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-style)

Global values are not supported (inherit, initial, revert, unset, etc).

When value is 'none' or 'hidden', the `border-width` value is not 0.

Default value is 'solid'.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top-width.md
---

# border-top-width

APISummary
## Introduction

The border-top-width CSS property sets the width of the left border of an element.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top-width`
**Bundle:** `dist/border-top-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTopWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "medium", "thick"],
    ["1px", "10px", "2rpx"],
    ["1em", "0.1em", "0.3rem"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderTopWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTopWidth />);

```



## Syntax

```css
/* Keyword values */
border-top-width: thin;
border-top-width: medium;
border-top-width: thick;

/* <length> values */
border-top-width: 10rem;
border-top-width: 6px;
```

### Values

`<line-width>`

Defines the width of the border, either as an explicit nonnegative [`<length>`](/api/css/data-type/length.md) or a keyword. If it's a keyword, it must be one of the following values:

- thin
- medium
- thick

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
border-top-width =
  <line-width>

<line-width> =
  <length [0,∞]>  |
  thin            |
  medium          |
  thick
```

## Difference from Web

- [mdn:border-top-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width)

Global values are not supported (inherit, initial, revert, unset, etc).

Default value is 0, different to 'medium' in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-top.md
---

# border-top

APISummary
## Introduction

The border-top shorthand CSS property sets all the properties of an element's right border.

## Examples

**This is an example below: css-api**

**Entry:** `src/border-top`
**Bundle:** `dist/border-top.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderTop = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px dashed orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`normal-${rowIndex}-${colIndex}`}
                  className="box"
                  style={{ borderTop: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ borderTop: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderTop />);

```



## Syntax

```css
.border {
  border-top: 1px;
}
```

It is actually the same as this one:

```css
.border {
  border-top: 1px solid black;
}
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-top-width`](/api/css/properties/border-top-width.md)
  width of the border

- [`border-top-style`](/api/css/properties/border-top-style.md)
  style of the border

- [`border-top-color`](/api/css/properties/border-top-color.md)
  color of the border

As with all shorthand properties, border-top always sets the values of all the properties that it can set,
even if they are not specified. It sets those that are not specified to their default values. Consider the following code:

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset
```

## Difference from Web

- [mdn:border-top](https://developer.mozilla.org/en-US/docs/Web/CSS/border-top)

Global values are not supported. (inherit, initial, revert, unset, etc)

Default style value is `solid`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border-width.md
---

# border-width

APISummary
## Introduction

A shorthand property for setting the width of all four borders of an element. It corresponds to [`border-top-width`](/api/css/properties/border-top-width.md), [`border-right-width`](/api/css/properties/border-right-width.md), [`border-bottom-width`](/api/css/properties/border-bottom-width.md), and [`border-left-width`](/api/css/properties/border-left-width.md).

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/border-width`
**Bundle:** `dist/border-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BorderWidth = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const widthOptions = [
    ["thin", "thin medium"],
    ["thin medium thick", "thin medium thick 10px"],
    ["5px 1px 0px 15px", "0.5px 0.2em 5rpx"],
    ["0.2em 0.4em 0.5rem 3rpx", "thick 1px"],
  ];

  const widthOptions2 = [
    ["thick", "thick thin"],
    ["medium thick 1px", "thick 10px"],
    ["5px 0px 15px", "0.5px 5rpx 1rem"],
    ["0.2em 0.5rem 3rpx", "thick 6px"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        {widthOptions.map((row, rowIndex) => (
          <view key={`solid-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`solid-${rowIndex}-${colIndex}`}
                  className="box solid"
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions2.map((row, rowIndex) => (
          <view key={`style-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`style-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex}`}
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {widthOptions.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((width, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box styleDiff${colIndex} radiusStyle${colIndex}`}
                  style={{ borderWidth: width }}
                >
                  <text className="text">{width}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<BorderWidth />);

```



## Syntax

```css
border-width: thin medium thick 10px;
```

### Values

- thin | medium | thick | [`<length>`](/api/css/data-type/length.md)
- Supports 1-4 value syntax (top → right → bottom → left).

## Formal Definition

| Initial value | 0 |
| Applies to | All elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```css
border-width = [ <line-width> ]{1,4}
<line-width> = <length> | thin | medium | thick
```

## Differences from the Web

- [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width)
- Default value is different (Web default is `medium`).
- Does not support global values.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/border.md
---

# border

APISummary
## Introduction

The border shorthand CSS property sets an element's border. It sets the values of [border-width](/api/css/properties/border-width.md), [border-style](/api/css/properties/border-style.md), and [border-color](/api/css/properties/border-color.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/border`
**Bundle:** `dist/border.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Border = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const styles = [
    ["thick double red", "thin dotted blue"],
    ["10px solid orange", "medium solid #0000ff"],
    ["5px groove rgba(0,255,0,0.6)", "10rpx ridge hsl(89,43%,51%)"],
    ["thick outset hsla(89,43%,51%,0.3)", "16px inset #ab0"],
  ];

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      s
      <view className="fixed_area" style={fixedAreaStyle}>
        {styles.map((row, rowIndex) => (
          <view key={`normal-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view key={`normal-${rowIndex}-${colIndex}`} className="box" style={{ border: borderStyle }}>
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}

        {styles.map((row, rowIndex) => (
          <view key={`radius-${rowIndex}`}>
            <view className="row">
              {row.map((borderStyle, colIndex) => (
                <view
                  key={`radius-${rowIndex}-${colIndex}`}
                  className={`box radiusStyle${colIndex}`}
                  style={{ border: borderStyle }}
                >
                  <text className="text">{borderStyle}</text>
                </view>
              ))}
            </view>
          </view>
        ))}
      </view>
    </scroll-view>
  );
};

root.render(<Border />);

```



## Syntax

```css
/* style */
border: solid;

/* width | style */
border: 2px dotted;

/* style | color */
border: outset #f33;

/* width | style | color */
border: medium dashed green;
```

### Values

This property is a shorthand for the following CSS properties:

- [`border-width`](/api/css/properties/border-width.md)
  Sets the thickness of the border.

- [`border-style`](/api/css/properties/border-style.md)
  Sets the style of the border.

- [`border-color`](/api/css/properties/border-color.md)
  Sets the color of the border.

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<line-width> || <line-style> || <color>
where
<line-width> = <length> | thin | medium | thick
<line-style> = none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset

```

## Difference between web

- [mdn:border](https://developer.mozilla.org/en-US/docs/Web/CSS/border)

Lynx does not support inherit, initial, revert, or unset.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.border`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/border](https://developer.mozilla.org/zh-CN/docs/Web/CSS/border)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/bottom.md
---

# bottom

APISummary
## Introduction

The `bottom` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `bottom` depends on how the element is positioned (i.e., the value of the position property):

- When position is set to `absolute` or `fixed`, the `bottom` property specifies the distance between the outer edge of the element's bottom margin and the outer edge of the containing block's bottom padding.

- When `position` is set to `relative`, the `bottom` property specifies the distance the element's bottom edge is moved above its normal position.

When both `top` and `bottom` are specified, position is set to `absolute` or `fixed`, and `height` is unspecified (either `auto` or 100%) both the `top` and `bottom` distances are respected. In all other situations, if `height` is constrained in any way or `position` is set to `relative`, the top property takes precedence and the `bottom` property is ignored.

## Examples

**This is an example below: css-api**

**Entry:** `src/bottom`
**Bundle:** `dist/bottom.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Bottom = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    bottom: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    bottom: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    bottom: "10px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <view style={containerStyle}>
      <view style={firstBoxStyle}></view>
      <view style={secondBoxStyle}></view>
      <view style={thirdBoxStyle}></view>
      <view style={fourthBoxStyle}></view>
    </view>
  );
};

root.render(<Bottom />);

```



## Syntax

```css
/* <length> values */
bottom: 3px;
bottom: 2rpx;
bottom: 2.4em;
bottom: 3rem;

bottom: 10%;

/* Keyword value */
bottom: auto;

/* calc */
bottom: calc(1px + 1px);
```

### Values

- [`<length>`](/api/css/data-type/length.md)

  A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

  - for absolutely positioned elements, the distance to the bottom edge of the containing block.
  - for relatively positioned elements, the distance that the element is moved above its normal position.

- [`<percentage>`](/api/css/data-type/percentage.md)

  Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

- `auto`

  **Default value**.

## Formal definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the height of the containing block |


## Formal syntax

```
bottom =
  auto                |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/box-shadow.md
---

# box-shadow

APISummary
## Introduction

The `box-shadow` CSS property is used to add a shadow effect on the frame of the element. The values that can be set by this property include X-axis offset, Y-axis offset, shadow blur radius, shadow diffusion radius and shadow color, which are separated by multiple commas. `box-shadow` describes one or more shadow effects in a comma-separated list. This property allows the borders of almost all elements to be shaded. If the element is set `border-radius` at the same time, shadows will also have rounded corners. Order of multiple shadows in z-axis is the same rule as multiple `text shadows` (the first shadow is at the top).

## Syntax

```css
/* Keyword values */
box-shadow: none;

/* offset-x | offset-y | color */
box-shadow: 60px -16px teal;

/* offset-x | offset-y | blur-radius | color */
box-shadow: 10px 5px 5px black;

/* offset-x | offset-y | blur-radius | spread-radius | color */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);

/* inset | offset-x | offset-y | color */
box-shadow: inset 5em 1em gold;

/* Any number of shadows, separated by commas */
box-shadow:
  3px 3px red,
  -1em 0 0.4em olive;
```

### Values

- A case where two, three, or four numeric values are given.
  - If only two values are given, these two values will be interpreted by the browser as an offset on the x-axis`<offset-x>`And`y`Offset on axis`<offset-y>`。
  - If a third value is given, this third value will be interpreted as the size of the blur radius`<blur-radius>`。
  - If the fourth value is given, this fourth value will be interpreted as the size of the extended radius`<spread-radius>`。

- Optional, insert (shadow inward)`inset`。

- Optional, color value`<color>`。

## Formal Definition

| Initial value | `none` |
| Applies to | All elements |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
box-shadow =
  <box-shadow-position> &&
  [ <'box-shadow-offset'> [ <'box-shadow-blur'> <'box-shadow-spread'>? ]? ] &&
  <box-shadow-color>

<box-shadow-postion> =
  inset?

<box-shadow-offset> =
  <length>{2}

<box-shadow-blur> =
  <length [0, ∞]>

```

## Difference from Web

- [mdn: box-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow)

Temporarily not support values like inherit、initial、revert、unset、inset.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.box-shadow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-shadow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-shadow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/box-sizing.md
---

# box-sizing

APISummary
## Introduction

The `box-sizing` property defines whether fixed sizes (such as `<length>`s and `<percentage>`s) are assigned to the content box or to the border box. It affects the interpretation of all sizing properties, including [`width`](/api/css/properties/width.md), [`height`](/api/css/properties/height.md), [`min-width`](/api/css/properties/min-width.md), [`min-height`](/api/css/properties/min-height.md), [`max-width`](/api/css/properties/max-width.md), [`max-height`](/api/css/properties/max-height.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/box-sizing`
**Bundle:** `dist/box-sizing.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const BoxSizing = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <view className="div1">
          <text>FL</text>
        </view>
        <view className="div2">
          <text>FR</text>
        </view>

        <view className="div3">
          <text>BL</text>
        </view>
        <view className="div4">
          <text>BR</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<BoxSizing />);

```



## Syntax

```css
box-sizing: border-box;
box-sizing: content-box;
```

### Values

- `border-box`

  **Default value**. The [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md) properties include the content, padding, and border, but do not include the margin.

  Size calculation formula:

  width = border + padding + content

  height = border + padding + content

- `content-box`

  The [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md) properties include the content, but does not include the padding, border, or margin.

  Size calculation formula:

  width = content

  height = content

## Formal definition

| Initial value | `border-box` |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
box-sizing = border-box | content-box
```

## Difference with the web

- Default value is `border-box` in Lynx, while `content-box` in web.
- It will not affect the interpretation of [`flex-basis`](/api/css/properties/flex-basis.md), while Web will.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.box-sizing`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-sizing](https://developer.mozilla.org/zh-CN/docs/Web/CSS/box-sizing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/clip-path.md
---

# clip-path

APISummary

## Introduction

The `clip-path` CSS property creates a clipping region that sets what part of an element should be shown. Parts that are inside the region are shown, while those outside are hidden.

:::warning

- `clip-path` takes effect only on `<view>` elements.

- <span className="material-symbols-outlined">android</span> If this property is
  not work on Android，try to add a transparent background `background-color:
  transparent` to avoid the clipping process from being skipped by system.

:::

## Examples

### **inset**

 
**This is an example below: css-api**

**Entry:** `src/clip_path/inset`
**Bundle:** `dist/clip_path_inset.lynx.bundle`

```tsx {10}
import { root } from "@lynx-js/react";

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        clipPath: "inset(30px super-ellipse 3 3 50px/50px)",
      }}
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### **circle**

 
**This is an example below: css-api**

**Entry:** `src/clip_path/circle`
**Bundle:** `dist/clip_path_circle.lynx.bundle`

```tsx {10}
import { root } from "@lynx-js/react";

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        clipPath: "circle(50% at 50% top)",
      }}
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### **ellipse**

 
**This is an example below: css-api**

**Entry:** `src/clip_path/ellipse`
**Bundle:** `dist/clip_path_ellipse.lynx.bundle`

```tsx {11}
import { root } from "@lynx-js/react";

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        background: "linear-gradient(to bottom right, rgb(255,53,26), rgb(0,235,235) 50%)",
        clipPath: "ellipse(50px 60px at 10% 20%)",
      }}
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### **path**

 
**This is an example below: css-api**

**Entry:** `src/clip_path/path`
**Bundle:** `dist/clip_path_path.lynx.bundle`

```tsx {11,12}
import { root } from "@lynx-js/react";

import "../common.css";

function App() {
  return (
    <view
      className="container"
      style={{
        background: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235) 50%)",
        clipPath:
          "path('M36.9273 55.6337C35.2784 54.9693 33.3921 55.354 32.1351 56.611L31.9808 56.7653C30.3346 58.4116 27.6654 58.4116 26.0191 56.7653C24.803 55.5492 22.9701 55.1938 21.3876 55.8672C19.2453 56.7789 16.7696 55.7813 15.8579 53.639L15.7725 53.4383C15.0764 51.8026 13.4706 50.7408 11.6929 50.7408H11.4748C9.14659 50.7408 7.25919 48.8534 7.25919 46.5252C7.25919 44.8053 6.21441 43.2579 4.61919 42.6151C2.45972 41.745 1.41453 39.289 2.28469 37.1295L2.3662 36.9272C3.0306 35.2784 2.64593 33.3921 1.38892 32.1351L1.23471 31.9809C-0.411583 30.3346 -0.411564 27.6654 1.23473 26.0191C2.45085 24.803 2.80627 22.97 2.1328 21.3875C1.22113 19.2453 2.21872 16.7695 4.36099 15.8579L4.56168 15.7725C6.1974 15.0764 7.25919 13.4705 7.25919 11.6929V11.4747C7.25919 9.14657 9.14655 7.25922 11.4747 7.25922C13.1946 7.25922 14.742 6.21442 15.3848 4.61921C16.2549 2.45972 18.711 1.41448 20.8705 2.28466L21.0728 2.36618C22.7217 3.03059 24.6079 2.64592 25.8649 1.38891L26.0191 1.23471C27.6654 -0.411569 30.3346 -0.41157 31.9808 1.23471C33.197 2.45083 35.0299 2.80623 36.6124 2.13277C38.7547 1.22109 41.2305 2.21868 42.1422 4.36097L42.2276 4.5617C42.9237 6.19742 44.5295 7.25921 46.3072 7.25921H46.5253C48.8535 7.25921 50.7408 9.14656 50.7408 11.4747C50.7408 13.1946 51.7856 14.742 53.3808 15.3847C55.5402 16.2549 56.5854 18.7109 55.7153 20.8704L55.6337 21.0727C54.9693 22.7216 55.354 24.6079 56.611 25.8649L56.7653 26.0192C58.4116 27.6654 58.4116 30.3346 56.7653 31.9808C55.5492 33.1969 55.1938 35.0299 55.8672 36.6124C56.7789 38.7547 55.7813 41.2304 53.6391 42.1421L53.4384 42.2275C51.8026 42.9236 50.7408 44.5294 50.7408 46.3071V46.5252C50.7408 48.8534 48.8534 50.7408 46.5252 50.7408C44.8053 50.7408 43.2579 51.7856 42.6151 53.3808C41.745 55.5402 39.289 56.5854 37.1296 55.7153L36.9273 55.6337Z')",
      }}
    >
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Syntax

```css
/* Keyword values */
clip-path: none;

/* <basic-shape> values */
clip-path: inset(30px super-ellipse 3 3 50px/50px);
clip-path: circle(50px at 0 100px);
clip-path: ellipse(50px 60px at 10% 20%);
clip-path: path(
  'M0.5,1 C0.5,1,0,0.7,0,0.3 A0.25,0.25,1,1,1,0.5,0.3 A0.25,0.25,1,1,1,1,0.3 C1,0.7,0.5,1,0.5,1 Z'
);
```

### Values

The `clip-path` property is specified as one of the values listed below.

`none`

No clipping path is created.

`<basic-shape>`

A shape whose size and position is defined by its `border-box`. One of:

- `inset()`

Defines an inset rectangle.

```
inset( <length-percentage>{1, 4} [ round | (super-ellipse <exponents>) <border-radius>]?)

<length-percentage> =
  <length>
  <percentage>

<exponents> = <number>{2}

<border-radius> =
  <length-percentage [0,∞]>{1,4} [ / <length-percentage [0,∞]>{1,4} ]?
```

`<length-percentage>{1, 4}`

They represent the top, right, bottom, and left offsets from the `border-box` that defines the positions of the edges of the inset rectangle. These arguments follow the syntax of the margin shorthand, which let
you set all four insets with one, two or four values.

`round | (super-ellipse <exponents>) <border-radius>`

Optional arguments to define the rounded corners for the inset rectangle. When the shape is `round`, the corner radius acts like `<border-radius>`. When the shapes is `super-ellipse <exponent>`, the corner curve will be an [lame curve](https://en.wikipedia.org/wiki/Superellipse) 。`<border-radius>` using the border-radius shorthand syntax.

`<exponent>`

The two number are the exponents on the two dimensions, first is for x-axis and next for y-axis.

- `circle()`

Defines a circle using a radius and a position.

```
circle(<length-percentage> [at <position>]?)

<length-percentage> =
  <length [0,∞]>                |
  <percentage [0,∞]>

<position> =
  [ left | center | right | top | bottom | <length-percentage> ]  |
  [ left | center | right ] && [ top | center | bottom ]  |
  [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]
```

`<length-percentage>`

This may be a `<length>`, or a `<percentage>` defining the radius of the circle.

`<position>`

Moves the center of the circle. May be a `<length>`, or a `<percentage>`, or a values such as `left`. The `<position>` value defaults to center if omitted.

- `ellipse()`

Defines an ellipse using two radii and a position.

An ellipse is essentially a squashed circle and so ellipse() acts in a very similar way to circle() except that we have to specify two radii x and y.

```
<ellipse()> =
  ellipse( <radial-size>? [ at <position> ]? )

<radial-size> =
  <length-percentage [0,∞]>{2}

<position> =
  [ left | center | right | top | bottom | <length-percentage> ]  |
  [ left | center | right ] && [ top | center | bottom ]  |
  [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]  |
  [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]

<length-percentage> =
  <length>      |
  <percentage>
```

`<radial-size>`

Two radii, x and y in that order. These may be a `<length>`, or a `<percentage>`.

`<position>`

Moves the center of the ellipse. May be a `<length>`, or a `<percentage>`, or a values such as left. The `<position>` value defaults to center if omitted.

- `path()`

Defines a shape using an SVG path definition.

```
  <path()> =
    path(<string> )
```

`path()`

The `path()` function takes [SVG path string](https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute/d) as argument.

## Formal definition

| Initial value | none |
| Applies to | view |
| Inherited | no |
| Animatable | no |


## Difference with the Web

1. `inset()` function accepts `super-ellipse` as corner shape.
2. `polygon()` function is not supported.
3. `<clip-rule>` for `path()` function is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.clip-path`

**Specifications:**
- [https://drafts.fxtf.org/css-masking/#the-clip-path](https://drafts.fxtf.org/css-masking/#the-clip-path)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/color.md
---

# color

APISummary
## Introduction

The `color` CSS property sets the foreground [`color value`](/api/css/data-type/color.md) of an element's text

## Examples

**This is an example below: css-api**

**Entry:** `src/color`
**Bundle:** `dist/color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Color = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="fixed_area" style={fixedAreaStyle}>
        <text className="container text2 font_style">Hello World</text>
        <text className="container text3 font_style">Hello World</text>
        <text className="container text4 font_style">Hello World</text>
        <text className="container text5 font_style">Hello World</text>
        <text className="container text6 font_style">Hello World</text>
        <text className="container text7 font_style">Hello World</text>
        <text className="container text8 font_style">Hello World</text>
        <text className="container text9 font_style">Hello 😄 😄 World</text>
      </view>
    </scroll-view>
  );
};

root.render(<Color />);

```



## Syntax

```css
/* <named-color> values */
color: red;
color: orange;
color: tan;

/* <hex-color> values */
color: #090;
color: #009900;
color: #090a;
color: #009900aa;

/* <rgb()> values */
color: rgb(34, 12, 64, 0.6);
color: rgba(34, 12, 64, 0.6);
color: rgb(34 12 64 / 0.6);
color: rgba(34 12 64 / 0.3);
color: rgb(34 12 64 / 60%);
color: rgba(34.6 12 64 / 30%);

/* <hsl()> values */
color: hsl(30, 100%, 50%, 0.6);
color: hsla(30, 100%, 50%, 0.6);
color: hsl(30 100% 50% / 0.6);
color: hsla(30 100% 50% / 0.6);
color: hsl(30 100% 50% / 60%);
color: hsla(30.2 100% 50% / 60%);
```

### Values

- [`<color>`](/api/css/data-type/color.md)

- [`<gradient>`](/api/css/data-type/gradient.md)

## Formal definition

| Initial value | transparent |
| Applies to | text |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
<color> | <gradient>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/column-gap.md
---

# column-gap (grid-column-gap)

APISummary
## Introduction

The `column-gap`/`grid-column-gap` CSS property sets the size of the gap (gutter) between an element's columns in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and grid layout.

For compatibility, `column-gap` or `grid-column-gap` can be used both.

## Examples

**This is an example below: css-api**

**Entry:** `src/column-gap`
**Bundle:** `dist/column-gap.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const ColumnGap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    columnGap: "15px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    columnGap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using column-gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using column-gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<ColumnGap />);

```



## Syntax

```css
/* <length> values */
column-gap: 20px;
column-gap: 1em;

/* <percentage> value */
column-gap: 10%;

/* calc() values */
column-gap: calc(10% + 20px);
```

### Values

- `<length>`

Is the width of the gutter separating the columns.

- `<percentage>`

The size of the gap between columns, defined as a `percentage`. The `percentage` property's value must be non-negative.

## Formal definition

| Initial value | `0` |
| Applies to | flex containers, grid containers |
| Inherited | no |
| Animatable | no |
| Percentages | refer to row dimension of its own content area |


## Formal syntax

```
column-gap = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- `normal` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.column-gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/column-gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/column-gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |

**Description:** <code>column-gap</code>




---
url: /api/css/properties/css-variable.md
---

# Custom properties (`--*`): CSS variables

APISummary
## Introduction

CSS variables, are defined with a specific syntax (e.g., `--main-color: black;`) and their values are accessed using the`var()`function (e.g., `color: var(--main-color);`). Custom properties store a value in one place and allow it to be referenced in multiple other places throughout the stylesheet, promoting reusability and maintainability.

## Examples

**This is an example below: css**

**Entry:** `src/css_variable_theme`
**Bundle:** `dist/css_variable_theme.lynx.bundle` | Web: `dist/css_variable_theme.web.bundle`

```tsx {23-43}
import { root } from "@lynx-js/react";
import { useState } from "react";
import "./index.scss";

export default function App() {
  const [isDark, setIsDark] = useState(false);
  const [useJS, setUseJS] = useState(false);
  const [showError, setShowError] = useState(false);
  const themeClass = isDark ? "theme-dark" : "theme-light";

  const toggleTheme = () => {
    if (useJS) {
      setShowError(true);
      setTimeout(() => setShowError(false), 3000);
      return;
    }

    setIsDark(prev => !prev);
  };

  const toggleThemeByJS = () => {
    setUseJS(true);
    const rootElement = lynx.getElementById("root");
    const newTheme = isDark ? "light" : "dark";

    if (rootElement) {
      if (isDark) {
        rootElement.setProperty({
          "--bg-primary": "#ffffff",
          "--bg-secondary": "#f5f5f5",
          "--text-primary": "#1a1a1a",
          "--text-secondary": "#666666",
          "--shadow": "rgba(0, 0, 0, 0.1)",
        });
      } else {
        rootElement.setProperty({
          "--bg-primary": "#2d2d2d",
          "--bg-secondary": "#1a1a1a",
          "--text-primary": "#ffffff",
          "--text-secondary": "#cccccc",
          "--shadow": "rgba(0, 0, 0, 0.3)",
        });
      }
      setIsDark(prev => !prev);
    }
  };

  return (
    <view id="root" className={themeClass}>
      <view className="container">
        <view className="theme-switchers">
          <view className="theme-card" bindtap={toggleTheme}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme by className</text>
          </view>
          <view className="theme-card" bindtap={toggleThemeByJS}>
            <text className="theme-icon">{isDark ? "🌙" : "☀️"}</text>
            <text className="title">{isDark ? "Dark Mode" : "Light Mode"}</text>
            <text className="subtitle">Tap to switch theme through JS</text>
          </view>
        </view>
        <view className="content-cards">
          <view className="card">
            <text className="card-title">Card Sample 1</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 2</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 3</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
          <view className="card">
            <text className="card-title">Card Sample 4</text>
            <text className="card-text">This is a demo card showing theme switching effects.</text>
          </view>
        </view>
      </view>
      {showError && (
        <view className="error-message-container">
          <text className="error-message">
            Cannot change variables through the class after modifying them in JS!
          </text>
        </view>
      )}
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Syntax

```css
/* Declare css variables */
--somekeyword: left;
--somecolor: #0000ff;

/* Reference css variables */
background: var(--somecolor);
```

## Basic Usage

### Declaration

CSS Variable is a property whose name starts with two hyphens (`-`), such as `--foo`, which can be referenced with `var()` after it is defined.

```css
:root {
  --main-bg-color: yellow;
}

.two {
  --main-height: 200px;
  color: white;
  background-color: black;
  width: 100%;
  height: 100%;
}
```

You can delcare CSS variables in `style`
 attribute as well.
```tsx
<view
  style={{
    '--main-bg-color': 'yellow', // [!code highlight]
    '--main-height': '200px', // [!code highlight]
    color: 'white',
    width: '100%',
  }}
/>
```

:::info
CSS Variables can be defined in the `:root` selector to take effect globally, or in a separate selector to take effect on the applied element and its child elements.
:::

### How To Reference CSS variables

You use CSS variable by referencing the property in a `var()` function in place of a standard property value

```css
.three {
  /* --main-bg-color: blue; */
  color: white;
  background-color: var(--main-bg-color);
  width: 50%;
  border: 1px blue solid;
}
```

You can use them in `style`
 attributes as well:
```tsx
<view
  style={{
    color: 'var(--main-bg-color)', // [!code highlight]
    width: '100%',
  }}
/>
```

And a CSS variable is able to be a value of another:

```css
.nested-variables {
  --first-var: blue;

  /* Nested reference */
  --nested-reference: var(--first-var); /* [!code highlight] */
}
```

#### Default Values

When a CSS variable cannot find a defined CSS variable value, a preset default value can be used:

```css
.two {
  width: var(--view-width, 100px);
}
```

:::info
The part of the `var()` function after the first comma is returned as a whole and used as an alternate value for `var()`.
:::

#### CSS Variable With Calc expressions

In the CSS Variable declaration, the property value cannot be directly mathematically operated, and needs to use the `calc()` function, similar to:

```css
.four {
  background-color: var(--main-bg-color);
  width: 25%;
  height: calc(var(--main-height) - 100px);
}
```

#### CSS Variable Scope

Like ordinary properties, the inheritance and priority of CSS variables also follow the CSS cascading rules.
If no CSS variable is defined on an element, the value of that variable is inherited from its parent element. Look up according to the cascading relationship. Finally, the root element is found, which is the variable defined by the :root selector used in the previous example. Therefore, the scope of a variable is the valid scope of the selector it is in.

:::info
Since CSS Variable is defined in the selector, the scope is the same as that of the selector. When the selector is applied to an element, the CSS variable on the selector will also be applied to the element.
:::

```html
<view className="one" bindtap="tap1">
  <view className="two">
    <view className="three"></view>
    <view className="four"></view>
    <comp></comp>
  </view>
</view>
```

```css
:root {
  --main-bg-color: yellow;
}

.one {
  color: white;
  width: 100%;
  height: 100%;
}

.two {
  --main-bg-color: red;
  --main-height: 200px;
  color: white;
  background-color: black;
  width: 100%;
  height: 100%;
}

.three {
  --main-bg-color: blue;
  color: white;
  background-color: var(--main-bg-color);
  width: 50%;
  border: 1px blue solid;
}

.four {
  background-color: var(--main-bg-color);
  width: 25%;
  height: calc(var(--main-height) - 100px);
}
```

For the above example, the values of the `var(--main-bg-color)` variable are:

- For elements with `class="three"`: blue;
- For elements with `class="four"`: red;

### Modifying the Value of CSS Variables

#### Modifying CSS Variables via JavaScript API

You can modify the value of `css-variable` by using the API on the JS side:
Get an element node through the [`lynx.getElementById().setProperty`](/api/lynx-api/lynx/lynx-get-element-by-id.md) method, and modify the value of `css-var` on the node:

```javascript
// Modify a css variable at a time
lynx.getElementById('test').setProperty('--main-height', '300px');

// Batch modify css variables
lynx.getElementById('test').setProperty({
  '--main-height1': '300px',
  '--main-height2': '400px',
});
```

:::warning

`setProperty` method's params must be `Object` or `String`.

:::

#### Modifying the Selector that Declares CSS Variables

In a selector, you can declare the value of CSS variables. By switching the selector applied to the corresponding ancestor node, you can modify the corresponding value of the CSS variables.

```css
.a {
  --main-bg-color: red;
}

.b {
  --main-bg-color: blue;
}

.child {
  background-color: var(--main-bg-color);
  width: 25%;
}
```

```jsx
<view className={flag ? 'a' : 'b'}>
  <view>
    <view className="child"></view>
  </view>
</view>
```

In the example above, by toggling the class 'a' or 'b', you can achieve the effect of modifying the corresponding variable --main-bg-color.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.custom-property`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/--](https://developer.mozilla.org/en-US/docs/Web/CSS/--)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/cursor.md
---

# cursor

APISummary
## Introduction

The `cursor` CSS property controls the mouse pointer displayed when the pointer hovers over an element.

## Examples

**This is an example below: desktop**

**Entry:** `src/cursor`
**Bundle:** `dist/cursor.lynx.bundle` | Web: `dist/cursor.web.bundle`

```tsx
import { useResponsiveScale } from "../useResponsiveScale";
import "./App.css";

const cursorPresets = [
  "default",
  "pointer",
  "text",
  "grab",
  "grabbing",
  "not-allowed",
] as const;

export function App() {
  const { handleLayoutChange, scale } = useResponsiveScale({
    baseWidth: 640,
    baseHeight: 420,
    minScale: 0.58,
  });
  const pageStyle = {
    padding: `${32 * scale}px`,
  };
  const panelStyle = {
    padding: `${28 * scale}px`,
    gap: `${18 * scale}px`,
    borderRadius: `${28 * scale}px`,
  };
  const eyebrowStyle = {
    fontSize: `${14 * scale}px`,
    letterSpacing: `${scale}px`,
  };
  const titleStyle = {
    fontSize: `${34 * scale}px`,
  };
  const subtitleStyle = {
    fontSize: `${16 * scale}px`,
  };
  const buttonsStyle = {
    gap: `${12 * scale}px`,
  };
  const buttonStyle = {
    minWidth: `${96 * scale}px`,
    padding: `${14 * scale}px ${16 * scale}px`,
    borderRadius: `${16 * scale}px`,
  };
  const buttonTextStyle = {
    fontSize: `${16 * scale}px`,
  };

  return (
    <view className="Page" style={pageStyle} bindlayoutchange={handleLayoutChange}>
      <view className="Panel" style={panelStyle}>
        <text className="Eyebrow" style={eyebrowStyle}>CSS cursor</text>
        <text className="Title" style={titleStyle}>Hover the buttons to preview cursor keywords.</text>
        <text className="Subtitle" style={subtitleStyle}>Each button applies its own cursor value.</text>

        <view className="Buttons" style={buttonsStyle}>
          {cursorPresets.map(cursor => (
            <view
              key={cursor}
              className="Button"
              style={{ ...buttonStyle, cursor }}
            >
              <text className="ButtonText" style={buttonTextStyle}>{cursor}</text>
            </view>
          ))}
        </view>
      </view>
    </view>
  );
}

```



## Syntax

```css
cursor: pointer;
```

### Values

Lynx currently supports keyword values only, such as `pointer`, `text`, `grab`, and other standard cursor keywords.

## Lynx Mini App Syntax

You can declare `cursor` the same way as other CSS properties.

```html
<view class="clickable">
  <text>Hover me</text>
</view>
```

```css
.clickable {
  cursor: pointer;
}
```

If your compiler pipeline does not apply `cursor` as expected, prefer declaring it in a stylesheet selector or class.

## React Syntax

```tsx
<view style={{ cursor: 'pointer' }}>
  <text>Hover me</text>
</view>
```

## Formal Definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | yes |
| Animatable | no |


## Formal Syntax

```css
cursor: <cursor-keyword>;
```

## Differences from Web

- Only keyword values are supported.
- URL-based cursors, local image cursors, and custom hotspot positions are not supported.

## Notes

- To allow `cursor` to inherit in Lynx, enable CSS inheritance in your front-end configuration.
- You can also explicitly add `cursor` to `customCSSInheritanceList`.
- See [`enableCSSInheritance`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) and [`customCSSInheritanceList`](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md) for more details.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.cursor`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/cursor](https://developer.mozilla.org/en-US/docs/Web/CSS/cursor)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | 3.7 | Keyword values only. URL-based cursors, local image cursors, and custom hotspot positions are not supported.; ⚠️ Partial implementation |
| Clay Windows | 3.7 | Keyword values only. URL-based cursors, local image cursors, and custom hotspot positions are not supported.; ⚠️ Partial implementation |
| Web | ✅ Yes | - |

**Description:** The cursor CSS property controls the mouse pointer displayed when the pointer hovers over an element.




---
url: /api/css/properties/direction.md
---

# direction

APISummary
## Introduction

The `direction` CSS property sets the direction of text. Use `rtl` for languages written from right to left (like Hebrew or Arabic), and `ltr` for those written from left to right (like English and most other languages).

## Examples

**This is an example below: css-api**

**Entry:** `src/direction`
**Bundle:** `dist/direction.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Direction = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">rtl|ltr</text>
      </view>
      <text>current: {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<Direction />);

```



## Syntax

```css
direction: normal;
direction: ltr;
direction: rtl;
```

### Values

- `normal`

  **Default value**.

  The [`text-align:start`](/api/css/properties/text-align.md) will align the text according to the direction of text content and the direction of text will be inferred from the text content. All other behaviors are same as `ltr`.

  For example:
  For:

  ```html
  <text> abc 1234 </text>
  ```

  The text will be left aligned. And the direction of the will be left to right.

  For:

  ```html
  <text> العاشر ليونيكود 1234</text>
  ```

  The text will be right aligned. And the direction of the will be right to left.

- `ltr`

  Text direction will be left-to-right, the horizontal logical properties "inline-start"(e.g. margin-inline-start) will be mapped to "left", and "inline-end" will be mapped to "right".

- `rtl`

  Text direction will be right-to-left, the horizontal logical properties "inline-start"(e.g. margin-inline-start) will be mapped to "right", and "inline-end" will be mapped to "left".

- `lynx-rtl` <Deprecated />

  Not recommended. **lynx only, designed for make ltr only pages compatible for rtl**, Text direction will be right-to-left, properties "left", "inline-start" (e.g. margin-left) will be mapped to right, and "right", "inline-end" will be mapped to "left".

## Formal definition

| Initial value | `normal` |
| Applies to | all elements |
| Inherited | yes |
| Animatable |  |


## Formal syntax

```
direction = normal | ltr | rtl
```

## Difference with the web

- Value `normal`, `lynx-rtl` are introduced to improve page compatibility for `rtl`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.direction`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | direction:rtl is as powerful as direction:lynx-rtl; ⚠️ Partial implementation |




---
url: /api/css/properties/display.md
---

# display

APISummary
## Introduction

In Lynx, the `display` only determines the internal display type of the element (how to layout the child elements), and does not determine the external display type (whether the element is considered a [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content) or an [inline-level element](https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content)).

Lynx does not have [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout) and does not support the `display: block/inline` syntax. All Lynx elements are [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content), except for the elements inside the `<text>` component.

:::info
[Linear layout](/guide/ui/layout/linear-layout.md) is the default layout for elements in Lynx. You can set `defaultDisplayLinear: false` in the project configuration to change the default layout to \[flexible box layout].
:::

## Examples

**This is an example below: css-api**

**Entry:** `src/display`
**Bundle:** `dist/display.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Display = () => {
  const fixedAreaStyle = {
    width: "50%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical">
      <view className="fixed_area" style={fixedAreaStyle}>
        <text>flex</text>
        <view className="container" style={{ display: "flex" }}>
          <text className="item">1</text>
          <text className="item">2</text>
        </view>

        <text>linear</text>
        <view className="container" style={{ display: "linear", linearOrientation: "horizontal" }}>
          <text className="item">1</text>
          <text className="item">2</text>
        </view>

        <text>relative</text>
        <view className="container" style={{ display: "relative" }}>
          <text
            className="item"
            style={{
              // @ts-expect-error TODO(types): Support relativeId in `@lynx-js/types`
              relativeId: "1",
            }}
          >
            1
          </text>
          <text
            className="item"
            style={{
              // @ts-expect-error TODO(types): Support relativeRightOf in `@lynx-js/types`
              relativeRightOf: "1",
            }}
          >
            2
          </text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Display />);

```



## Syntax

```css
display: flex;
display: none;
display: linear;
display: relative;
display: grid;
```

### Values

- `flex`

  See more in [flexible box layout](/guide/ui/layout/flexible-box-layout.md).

- `linear`

  [linear layout](/guide/ui/layout/linear-layout.md) is the default Layout model developed by Lynx. It has best **performance** in all types of layout in Lynx.

  :::info
  `<scroll-view>` is forced to be a linear layout, in which case `<scroll-view>` is formatted as a normal linear view. Both the alignment attribute and [linear-weight](/api/css/properties/linear-weight.md) take effect. And `scroll-x`/`scroll-y` will change the main axis to horizontal and vertical respectively. (The actual conversion is determined by whether to set `scroll-x`/`scroll-y`.)
  :::

- `none`

  Element and its descents will be resized to 0x0.

  :::info
  If the parent element of the `<text>` element is set to `display:none` and the `<text>` element is still rendered visible, please add [`overflow:hidden`](/api/css/properties/overflow.md) to the corresponding parent element. We will fix this issue in the future.
  :::

- `grid`

  Element will layout according to the grid layout layout model.

- `relative`

  Relative layout is a Layout model developed by Lynx.

  Element will layout according to the relative layout model. Relative layout is a layout that displays children in relative positions, where each view's position can be specified relative to sibling elements (for example, to the left or below another view) or relative to the parent's area (e.g. align at bottom, left or center).

## Formal definition

| Initial value | `linear` |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
display = none | linear | flex | grid | relative
```

## Difference with the web

- In Lynx, the `display` only determines the internal display type of the element (how to layout the child elements), and does not determine the external display type (whether the element is considered a [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content) or an [inline-level element](https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content)).
- [relative layout](/guide/ui/layout/relative-layout.md) and [linear layout](/guide/ui/layout/linear-layout.md) are Layout models developed by Lynx.
- Lynx does not have [flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flow_layout) and does not support the `display: block/inline` syntax. All Lynx elements are [block-level element](https://developer.mozilla.org/en-US/docs/Glossary/Block-level_content), except for the elements inside the `<text>` component.
- `inline-block`, `inline-flex`, `inline-grid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.display`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/display](https://developer.mozilla.org/zh-CN/docs/Web/CSS/display)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


## FAQ

- `<scroll-view>` is forced to be a linear layout, in which case `<scroll-view>` is formatted as a normal linear view. Both the alignment attribute and [`linear-weight`](/api/css/properties/linear-weight.md) take effect. And `scroll-x`/`scroll-y` will change the main axis to horizontal and vertical respectively. (The actual conversion is determined by whether to set `scroll-x`/`scroll-y`.)



---
url: /api/css/properties/filter.md
---

# filter

APISummary
## Introduction

The `filter` CSS property applies graphical effects like blur or color shift to an element.

:::info

Currently only the `blur`, `grayscale`, `brightness`, `contrast` and `saturate` functions are supported.

If you use `opacity`, you can directly set properties for the view, [link](/api/css/properties/opacity.md)

Views with the `grayscale` attribute added on Android will create off-screen buffer on the GPU. A large number of off-screen buffer will cause rendering performance to decrease. It is recommended to replace `filter: grayscale(0)` with `filter: none` to remove off-screen caching when grayscale is not needed.

:::

:::info Android blur (OS Version \< 12)

When using blur, you can add `blur-sampling` property (an int value) to the node to set the downsampling ratio to improve performance.

Setting the blur area may cause performance issues if content is updated all the time.

For higher blur efficiency, it is recommended that the actual size of the blur-radius should not exceed 25, that is, the maximum write 25ppx or 25/density px.

:::

## Examples

**This is an example below: css-api**

**Entry:** `src/filter`
**Bundle:** `dist/filter.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";
import lynxImage from "../../resource/bg_flower.gif";

const Filter = () => {
  const blurStyle = {
    filter: "blur(10px)",
  };

  const grayscaleStyle = {
    filter: "grayscale(100%)",
  };

  const brightnessStyle = {
    filter: "brightness(0.3)",
  };

  const contrastStyle = {
    filter: "contrast(0.5)",
  };

  const saturateStyle = {
    filter: "saturate(0.7)",
  };

  const imageStyle = {
    width: "100px",
    height: "140px",
  };

  return (
    <scroll-view className="w-100 h-100" scroll-orientation="vertical">
      <view style={blurStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={grayscaleStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={brightnessStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={contrastStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
      <view style={saturateStyle}>
        <image style={imageStyle} src={lynxImage} />
      </view>
    </scroll-view>
  );
};

root.render(<Filter />);

```



## Syntax

```css
filter: grayscale(100%);
filter: blur(5px);
filter: brightness(0.6);
filter: contrast(0.7);
filter: saturate(0.8);
```

## Formal definition

| Initial value | none |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal Syntax

```
filter = <filter-function>

<filter-function> =
  <blur()>         |
  <grayscale()>    |

<blur()> =
  blur( <length>? )

<grayscale()> =
  grayscale( [ <percentage> ]? )

<brightness()> =
  brightness( [ <number> | <percentage> ]? )

<contrast()> =
  contrast( [ <number> | <percentage> ]? )

<saturate()> =
  saturate( [ <number> | <percentage> ]? )

```

## Differences from the Web

- Only one filter function is allowed per declaration
- Only supports `blur`, `grayscale`, `brightness`, `contrast` and `saturate` functions

## Compatibility

**Compatibility Table**
**Query:** `css.properties.filter`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter](https://developer.mozilla.org/zh-CN/docs/Web/CSS/filter)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


**Error:** No compatibility data found for `css.properties.filter-properties`


---
url: /api/css/properties/flex-basis.md
---

# flex-basis

APISummary
## Introduction

The `flex-basis` CSS property sets the initial main size of a flex item. In case both `flex-basis` (other than `auto`) and [`width`](/api/css/properties/width.md) or [`height`](/api/css/properties/height.md) in case of [`flex-direction: column`](/api/css/properties/flex-direction.md) are set for an element, `flex-basis` has priority.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-basis`
**Bundle:** `dist/flex-basis.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexBasis = () => {
  const itemStyle = {
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 1,
  };

  const autoStyle = {
    flexBasis: "auto" as const,
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  const zeroPxStyle = {
    flexBasis: "0px",
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  const px300Style = {
    flexBasis: "300px",
    backgroundColor: "rgba(255,0,200,0.2)" as const,
    flexGrow: 1,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view style={autoStyle}>
            <text>flex-basis:auto</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>

        <view className="container">
          <view style={zeroPxStyle}>
            <text>flex-basis:0px</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>

        <view className="container">
          <view style={px300Style}>
            <text>flex-basis:300px</text>
          </view>
          <view style={itemStyle}>
            <text>Item Two</text>
          </view>
          <view style={itemStyle}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexBasis />);

```



## Syntax

```css
/* Specify <'width'> */
flex-basis: 10em;
flex-basis: 3px;
flex-basis: 50%;
flex-basis: auto;
```

### Values

- `auto`

  **Default value**. refer to [`width`](/api/css/properties/width.md) and [`height`](/api/css/properties/height.md).

- `<length>`

  sets an absolute value.

- `<percentage>`

  sets a percentage of the width or height of a containing block's content area.

## Formal definition

| Initial value | `auto` |
| Applies to | flex items |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to containing block's content area |


## Formal syntax

```
flex-basis = auto | <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- Not under [`box-sizing`](/api/css/properties/box-sizing.md) influence.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-basis`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-basis](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-basis)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** <code>flex-basis</code>




---
url: /api/css/properties/flex-direction.md
---

# flex-direction

APISummary
## Introduction

The `flex-direction` CSS property sets how flex items are placed in the flex container defining the main axis and the direction.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-direction`
**Bundle:** `dist/flex-direction.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexDirection = () => {
  const greenStyle = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexGrow: 1,
  };

  const blueStyle = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 1,
  };

  const redStyle = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexGrow: 1,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="row">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="row-reverse">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="container column">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>

        <view className="container column-reverse">
          <view style={greenStyle}></view>
          <view style={blueStyle}></view>
          <view style={redStyle}></view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexDirection />);

```



Note that the values `row` and `row-reverse` are affected by the directionality of the flex container. If its [`dir`](/api/css/properties/direction.md) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right.

## Syntax

```css
/* The direction text is laid out in a line */
flex-direction: row;

/* Like <row>, but reversed */
flex-direction: row-reverse;

/* The direction in which lines of text are stacked */
flex-direction: column;

/* Like <column>, but reversed */
flex-direction: column-reverse;
```

### Values

- `row`

  **Default value**. The flex container's main-axis is defined to be the same as the text direction. The main-start and main-end points are the same as the content direction.

- `row-reverse`

  Behaves the same as `row` but the main-start and main-end points are opposite to the content direction.

- `column`

  The flex container's main-axis is the same as the vertical. The main-start and main-end points are the same as the before and after points of the writing-mode.

- `column-reverse`

  Behaves the same as `column` but the main-start and main-end are opposite to the content direction.

## Formal definition

| Initial value | row |
| Applies to | flex containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
flex-direction =
  row             |
  row-reverse     |
  column          |
  column-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-direction`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-direction](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-direction)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-flow.md
---

# flex-flow

APISummary
## Introduction

This property is a shorthand for the CSS properties: [`flex-direction`](/api/css/properties/flex-direction.md) and [`flex-wrap`](/api/css/properties/flex-wrap.md), specifies the direction of a flex container, as well as its wrapping behavior.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-flow`
**Bundle:** `dist/flex-flow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexFlow = () => {
  const flowStyle = {
    flexFlow: "row wrap" as const,
  };

  const flow2Style = {
    flexDirection: "row" as const,
    flexWrap: "wrap" as const,
  };

  const item1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 0,
    width: "50%",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item4Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text>flex-flow: row wrap</text>
      <view className="container" style={flowStyle}>
        <view className="height" style={item1Style}>
          <text>Item One</text>
        </view>
        <view className="height" style={item2Style}>
          <text>Item Two</text>
        </view>
        <view className="height" style={item3Style}>
          <text>Item Three</text>
        </view>
        <view className="height" style={item4Style}>
          <text>Item Four</text>
        </view>
      </view>
      <text>flex-direction: row; flex-wrap: wrap</text>
      <view className="container" style={flow2Style}>
        <view className="height" style={item1Style}>
          <text>Item One</text>
        </view>
        <view className="height" style={item2Style}>
          <text>Item Two</text>
        </view>
        <view className="height" style={item3Style}>
          <text>Item Three</text>
        </view>
        <view className="height" style={item4Style}>
          <text>Item Four</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexFlow />);

```



## Syntax

```css
/* flex-flow: <'flex-direction'> */
flex-flow: row;
flex-flow: row-reverse;
flex-flow: column;
flex-flow: column-reverse;

/* flex-flow: <'flex-wrap'> */
flex-flow: nowrap;
flex-flow: wrap;
flex-flow: wrap-reverse;

/* flex-flow: <'flex-direction'> and <'flex-wrap'> */
flex-flow: row nowrap;
flex-flow: column wrap;
flex-flow: column-reverse wrap-reverse;
```

### Values

This property is a shorthand for the following CSS properties: [`flex-direction`](/api/css/properties/flex-direction.md) and [`flex-wrap`](/api/css/properties/flex-wrap.md)。

## Formal definition

| Initial value | as each of the properties of the shorthand: 
- flex-direction: row
- flex-wrap: nowrap |
| Applies to | flex containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
flex-flow =
  <'flex-direction'>  ||
  <'flex-wrap'>

<flex-direction> =
  row             |
  row-reverse     |
  column          |
  column-reverse

<flex-wrap> =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-flow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-flow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-flow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-grow.md
---

# flex-grow

APISummary
## Introduction

The `flex-grow` CSS property sets the flex grow factor, which specifies how much of the flex container's remaining space should be assigned to the flex item's main size.

When the flex-container's main size is larger than the combined main sizes of the flex items, the extra space is distributed among the flex items, with each item growth being their growth factor value as a proportion of the sum total of all the container's items' flex grow factors.

The main size is either width or height of the item which is dependent on the [`flex-direction`](/api/css/properties/flex-direction.md) value.

`flex-grow` is used alongside the other flex properties [`flex-shrink`](/api/css/properties/flex-shrink.md) and [`flex-basis`](/api/css/properties/flex-basis.md), and normally defined using the [flex](/api/css/properties/flex.md) shorthand to ensure all values are set.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-grow`
**Bundle:** `dist/flex-grow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexGrow = () => {
  const grow1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexGrow: 1,
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexGrow: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexGrow: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view className="height" style={grow1Style}>
            <text>flex-grow:1</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexGrow />);

```



## Syntax

```css
/* <number> values */
flex-grow: 3;
flex-grow: 0.6;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid, **Defaults** to `0`。

## Formal definition

| Initial value | 0 |
| Applies to | flex items |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
flex-grow =
  <number [0,∞]>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-grow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-grow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-grow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-shrink.md
---

# flex-shrink

APISummary
## Introduction

Defines the shrink factor of the flex element on the main axis. After the flex container layout elements, if there is an element overflow, the corresponding element will be scaled according to the element's zoom factor ratio to ensure that the element will not overflow the container.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-shrink`
**Bundle:** `dist/flex-shrink.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexShrink = () => {
  const shrink1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 1,
  };

  const shrink2Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 2,
    marginLeft: "10px",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
    width: "30%",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
    width: "40%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view className="height" style={shrink1Style}>
            <text>flex-shrink:1</text>
          </view>
          <view className="height" style={shrink2Style}>
            <text>flex-shrink:2</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexShrink />);

```



## Syntax

```css
/* <number> values */
flex-shrink: 2;
flex-shrink: 0;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. Defaults to `1`.

## Formal definition

| Initial value | 1 |
| Applies to | flex items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
flex-shrink =
  <number [0,∞]>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-shrink`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-shrink](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-shrink)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex-wrap.md
---

# flex-wrap

APISummary
## Introduction

The `flex-wrap` CSS property sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked.

## Examples

**This is an example below: css-api**

**Entry:** `src/flex-wrap`
**Bundle:** `dist/flex-wrap.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FlexWrap = () => {
  const item1Style = {
    backgroundColor: "rgba(0,255,0,0.2)" as const,
    flexShrink: 0,
    width: "50%",
  };

  const item2Style = {
    backgroundColor: "rgba(0,0,255,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item3Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  const item4Style = {
    backgroundColor: "rgba(255,0,0,0.2)" as const,
    flexShrink: 0,
    marginLeft: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>flex-wrap:nowrap</text>
        <view className="container nowrap">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>

        <text>flex-wrap:nowrap</text>
        <view className="container wrap">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>

        <text>flex-wrap:wrap-reverse</text>
        <view className="container wrap-reverse">
          <view className="height" style={item1Style}>
            <text>Item One</text>
          </view>
          <view className="height" style={item2Style}>
            <text>Item Two</text>
          </view>
          <view className="height" style={item3Style}>
            <text>Item Three</text>
          </view>
          <view className="height" style={item4Style}>
            <text>Item Four</text>
          </view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<FlexWrap />);

```



## Syntax

```css
flex-wrap: nowrap; /* Default value */
flex-wrap: wrap;
flex-wrap: wrap-reverse;
```

### Values

- `nowrap`

  **Default value**. The flex items are laid out in a single line which may cause the flex container to overflow. The cross-start is either equivalent to start or before depending on the [`flex-direction`](/api/css/properties/flex-direction.md) value.

- `wrap`

  The flex items break into multiple lines. The cross-start is either equivalent to start or before depending [`flex-direction`](/api/css/properties/flex-direction.md) value and the cross-end is the opposite of the specified cross-start.

- `wrap-reverse`

  Behaves the same as `wrap` but cross-start and cross-end are permuted.

## Formal definition

| Initial value | nowrap |
| Applies to | flex containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
flex-wrap =
  nowrap        |
  wrap          |
  wrap-reverse
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex-wrap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-wrap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex-wrap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/flex.md
---

# flex

APISummary
## Introduction

The `flex` CSS shorthand property sets how a flex item will grow or shrink to fit the space available in its flex container. This property is a shorthand for the following CSS properties: [`flex-grow`](/api/css/properties/flex-grow.md), [`flex-shrink`](/api/css/properties/flex-shrink.md), [`flex-basis`](/api/css/properties/flex-basis.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/flex`
**Bundle:** `dist/flex.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Flex = () => {
  const firstBoxStyle = {
    flex: "1",
    backgroundColor: "rgba(255,0,200,0.2)",
  };

  const secondBoxStyle = {
    flex: "1 30px",
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)",
  };

  const thirdBoxStyle = {
    flex: "2 1 auto",
    marginLeft: "5px",
    backgroundColor: "rgba(0,0,255,0.2)",
  };

  return (
    <view className="container">
      <view className="height" style={firstBoxStyle}>
        <text>flex:1;</text>
      </view>
      <view className="height" style={secondBoxStyle}>
        <text>flex:1 30px;</text>
      </view>
      <view className="height" style={thirdBoxStyle}>
        <text>flex:2 1 auto;</text>
      </view>
    </view>
  );
};

root.render(<Flex />);

```



## Syntax

```css
flex: none;
flex: auto;

/* One value, unitless number: flex-grow
flex-basis is then equal to 0. */
flex: 2;

/* One value, width/height: flex-basis */
flex: 10em;
flex: 30%;

/* Two values: flex-grow | flex-basis */
flex: 1 30px;

/* Two values: flex-grow | flex-shrink */
flex: 2 2;

/* Three values: flex-grow | flex-shrink | flex-basis */
flex: 2 2 10%;
```

The `flex` property may be specified using one, two, or three values.

- **One-value syntax**:
  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-grow>`](/api/css/properties/flex-grow.md), then the shorthand expands to `flex: <flex-grow> 1 0`.
  - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md), then the shorthand expands to `flex: 1 1 <flex-basis>`.

- **Two-value syntax**:
  - The first value must be a valid value for [`<flex-grow>`](/api/css/properties/flex-grow.md).
  - The second value must be one of:
    - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-shrink>`](/api/css/properties/flex-shrink.md), then the shorthand expands to `flex: <flex-grow> <flex-shrink> 0`.
    - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md), then the shorthand expands to `flex: <flex-grow> 1 <flex-basis>`.

- Three-value syntax: the values must be in the following order:
  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-grow>`](/api/css/properties/flex-grow.md).
  - A unitless [`<number>`](/api/css/data-type/number.md), which will be used as the value of [`<flex-shrink>`](/api/css/properties/flex-shrink.md).
  - A valid [`<length>`](/api/css/data-type/length.md) or [`<percentage>`](/api/css/data-type/percentage.md) or key word `auto`, it will be used as the value of [`<flex-basis>`](/api/css/properties/flex-basis.md).

### Values

- `0 1 auto`

  **Default value**. The item is sized according to its width and height properties. It shrinks to its minimum size to fit the container, but does not grow to absorb any extra free space in the flex container.

- `auto`

  The item is sized according to its width and height properties, but grows to absorb any extra free space in the flex container, and shrinks to its minimum size to fit the container. This is equivalent to setting "`flex: 1 1 auto`".

- `none`

  The item is sized according to its width and height properties. It is fully inflexible: it neither shrinks nor grows in relation to the flex container. This is equivalent to setting "`flex: 0 0 auto`".

- `<flex-grow>`

  Defines the [`flex-grow`](/api/css/properties/flex-grow.md) of the flex item. Negative values are considered invalid. Defaults to 1 when omitted.

- `<flex-shrink>`

  Defines the [`flex-shrink`](/api/css/properties/flex-shrink.md) of the flex item. Negative values are considered invalid. Defaults to 1 when omitted.

- `<flex-basis>`

  Defines the [`flex-basis`](/api/css/properties/flex-basis.md) of the flex item. A preferred size of 0 must have a unit to avoid being interpreted as a flexibility. Defaults to `auto` when omitted. (initial is auto)

## Formal definition

| Initial value | as each of the properties of the shorthand: 
- `flex-grow: 0`
- `flex-shrink: 1`
- `flex-basis: auto` |
| Applies to | flex items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
flex =
  none                                                |
  [ <'flex-grow'> <'flex-shrink'>? || <'flex-basis'> ]

<flex-grow> =
  <number [0,∞]>

<flex-shrink> =
  <number [0,∞]>

<flex-basis> = <'width'>

<width> =
  auto                                      |
  <length-percentage [0,∞]>                 |
  max-content                               |
  fit-content( <length-percentage [0,∞]> )

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.flex`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex](https://developer.mozilla.org/zh-CN/docs/Web/CSS/flex)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-family.md
---

# font-family

APISummary
## Introduction

The `font-family` CSS property specifies a prioritized list of one or more font family names and/or generic family names for the selected element.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-family`
**Bundle:** `dist/font-family.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontFamily = () => {
  const fontStyle = {
    fontFamily: "icon-font",
    fontSize: "20px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={{ flexDirection: "column" }} className="container">
        <text style={fontStyle}>
          {"base64编码的字体\n&#xe61c;&#xe61d;&#xe61e;&#xe61f;&#xe620;&#xe621;&#xe622;&#xe623;&#xe624;"}
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<FontFamily />);

```



## Syntax

```css
font-family: font1, font2;
```

## Formal definition

| Initial value |  |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
font-family =
  [ <string> | <custom-ident> ]#
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-family`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-family](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-family)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-feature-settings.md
---

# font-feature-settings

APISummary
## Introduction

The `font-feature-settings` CSS property is used to control advanced typographic features in OpenType fonts.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-feature-settings`
**Bundle:** `dist/font-feature-settings.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontFeatureSettings = () => {
  return (
    <view style={{ display: "linear" }}>
      <text>normal</text>
      <text className="variable-font-normal">1234567890</text>
      <text>font-feature-settings:'onum'</text>
      <text className="variable-font-normal font-feature-settings">1234567890</text>
    </view>
  );
};

root.render(<FontFeatureSettings />);

```



## Syntax

```css
font-feature-settings: 'onum';
```

## Formal Definition

| Initial value | normal |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal Syntax

```
font-feature-settings =
  normal                |
  <feature-tag-value>#

<feature-tag-value> =
  <opentype-tag> [ <integer [0,∞]> | on | off ]?

<opentype-tag> =
  <string>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-feature-settings`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-feature-settings](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-feature-settings)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | iOS supports commonly used and registered OpenType tags: hlig, clig, c2sc, c2pc, smcp, pcap, ss01-ss20, onum, lnum, pnum, tnum, frac, afrc, zero, ordn, sups, subs, case, titl, sinf.; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-optical-sizing.md
---

# font-optical-sizing

APISummary
## Introduction

The `font-optical-sizing` CSS property sets whether text rendering is optimized for viewing at different sizes.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-optical-sizing`
**Bundle:** `dist/font-optical-sizing.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontOpticalSizing = () => {
  return (
    <view style={{ display: "linear", width: "300px" }}>
      <text>normal</text>
      <text className="variable-font-normal">
        On this particular Thursday, something was moving quietly through the ionosphere many miles above the surface of
        the planet; several somethings in fact, several dozen huge yellow chunky slablike somethings, huge as office
        blocks, silent as birds.
      </text>
      <view style={{ height: "10px" }}></view>
      <text>font-optical-sizing: auto</text>
      <text className="variable-font-normal font-optical-sizing">
        On this particular Thursday, something was moving quietly through the ionosphere many miles above the surface of
        the planet; several somethings in fact, several dozen huge yellow chunky slablike somethings, huge as office
        blocks, silent as birds.
      </text>
    </view>
  );
};

root.render(<FontOpticalSizing />);

```



## Syntax

```css
font-optical-sizing: auto;
```

## Formal Definition

| Initial value | none |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal Syntax

```
font-optical-sizing =
  auto | none
```

## Difference with Web

- Unlike the Web default value of `auto`, the default value in Lynx is `none`. The `font-optical-sizing` property is a supplement to the `font-variation-settings` property and the optical size variation axis is represented by `opsz` in `font-variation-settings`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-optical-sizing`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-size.md
---

# font-size

APISummary
## Introduction

`font-size` CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative `<length>` units, such as em, ex, and so forth.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-size`
**Bundle:** `dist/font-size.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontSize = () => {
  const fontStyle = {
    fontSize: "30px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>hello lynx, default font size</text>
        <text style={fontStyle}>hello lynx, font size 30px</text>
      </view>
    </scroll-view>
  );
};

root.render(<FontSize />);

```



## Syntax

```css
/* <length> */
font-size: 12px;
font-size: 0.8em;

/* <percentage> */
font-size: 80%;
```

### Values

- `<length>` <br />
  Positive `<length>` value. For most font-relative units (such as em and ex), the font size is relative to the parent element's font size.

- `<percentage>` <br />
  A positive `<percentage>` value, relative to the parent element's font size.

## Formal definition

| Initial value | 14px |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
font-size = <length> | <percentage>
```

## Difference with Web

- Only support `<length>` and `<percentage>`

- Default font-size is **14px** not **medium**.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-size`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-size](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-size)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-style.md
---

# font-style

APISummary
## Introduction

Set the font style.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-style`
**Bundle:** `dist/font-style.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontStyle = () => {
  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <text>
          font-style: 无
        </text>

        <text style={{ fontStyle: "normal" }}>
          font-style: normal 普通
        </text>

        <text style={{ fontStyle: "italic" }}>
          font-style: italic 斜体
        </text>

        <text style={{ fontStyle: "oblique" }}>
          font-style: oblique 倾斜
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<FontStyle />);

```



## Syntax

```css
font-style: italic;
font-style: oblique;
font-style: normal;
```

### Values

- **`normal`**
  Selects a font that is classified as normal within a font-family.

- `italic`
  Selects a font that is classified as `italic`.

- `oblique`
  Selects a font that is classified as `oblique`.

## Formal definition

| Initial value | normal |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
font-style = normal | italic | oblique
```

## Difference with Web

- Only support `normal`, `oblique` and `italic`

- [mdn:font-style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-style`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-style](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-style)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-variation-settings.md
---

# font-variation-settings

APISummary
## Introduction

The `font-variation-settings` CSS property provides low-level control over variable font characteristics by letting you specify the four letter axis names of the characteristics you want to vary along with their values.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-variation-settings`
**Bundle:** `dist/font-variation-settings.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontVariationSettings = () => {
  return (
    <view style={{ display: "linear" }}>
      <text>normal</text>
      <text className="variable-font-normal">1234567890</text>
      <text>font-variation-settings:'wght' 750</text>
      <text className="variable-font-normal font-variation-settings">1234567890</text>
    </view>
  );
};

root.render(<FontVariationSettings />);

```



## Syntax

```css
font-variation-settings: 'wght' 750;
```

## Formal Definition

| Initial value | normal |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal Syntax

```
font-variation-settings =
  normal                        |
  [ <opentype-tag> <number> ]#

<opentype-tag> =
  <string>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-variation-settings`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | ❌ No | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/font-weight.md
---

# font-weight

APISummary
## Introduction

The `font-weight` CSS property sets the weight (or boldness) of the font. The weights available depend on the font-family that is currently set.

## Examples

**This is an example below: css-api**

**Entry:** `src/font-weight`
**Bundle:** `dist/font-weight.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const FontWeight = () => {
  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={{ fontWeight: "100", fontSize: "30px" }}>font-weight: 100</text>
      <text style={{ fontWeight: "200", fontSize: "30px" }}>font-weight: 200</text>
      <text style={{ fontWeight: "300", fontSize: "30px" }}>font-weight: 300</text>
      <text style={{ fontWeight: "400", fontSize: "30px" }}>font-weight: 400</text>
      <text style={{ fontWeight: "500", fontSize: "30px" }}>font-weight: 500</text>
      <text style={{ fontWeight: "600", fontSize: "30px" }}>font-weight: 600</text>
      <text style={{ fontWeight: "700", fontSize: "30px" }}>font-weight: 700</text>
      <text style={{ fontWeight: "800", fontSize: "30px" }}>font-weight: 800</text>
    </scroll-view>
  );
};

root.render(<FontWeight />);

```



## Syntax

```css
/* Keyword values */
font-weight: normal;
font-weight: bold;

/* Numeric keyword values */
font-weight: 100;
font-weight: 200;
font-weight: 300;
font-weight: 400;
font-weight: 500;
font-weight: 600;
font-weight: 700;
font-weight: 800;
font-weight: 900;
font-weight: 1000;
```

### Values

- Default **normal** <br />
  Normal font weight. Same as `400`.

- `bold` <br />
  Bold font weight. Same as `700`

- `<number>` <br />
  A `<number>` value between 1 and 1000, inclusive. Higher numbers represent weights that are bolder than (or as bold as) lower numbers.

## Best Practices

- Do not using `font-weight` with `font-family`. Currently, lynx `font-family` is just a key-value mapping not a real 'family'. And using other font-weight may cause `font-family` not working.

## Formal definition

| Initial value | normal |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
<font-weight> = normal | bold | [100, 1000]
```

## Difference with Web

- Not support `border` and `lighter`

- Numeric types currently only support integer values from '100' to '1000'.

- The fallback logic of glyph mapping failure will vary on different platforms and system versions. In the worst case, the system default font may be fallback, resulting in the failure of custom fonts.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.font-weight`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-weight](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-weight)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/gap.md
---

# gap

APISummary
## Introduction

The `gap` CSS shorthand property sets the gaps (gutters) between rows and columns in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and [grid layout](/guide/ui/layout/grid-layout.md).

This property is a shorthand for the following CSS properties: [`row-gap`](/api/css/properties/row-gap.md) and [`column-gap`](/api/css/properties/column-gap.md), this property is specified as a value for `row-gap` followed optionally by a value for `column-gap`. If `column-gap` is omitted, it's set to the same value as `row-gap`. `row-gap` and `column-gap` are each specified as a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/gap`
**Bundle:** `dist/gap.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Gap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    gap: "15px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    gap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<Gap />);

```



## Syntax

```css
/* One <length> value */
gap: 20px;
gap: 1em;

/* One <percentage> value */
gap: 16%;
gap: 100%;

/* Two <length> values */
gap: 20px 10px;
gap: 1em 0.5em;

/* One or two <percentage> values */
gap: 16% 100%;
gap: 21px 82%;

/* calc() values */
gap: calc(10% + 20px);
gap: calc(20px + 10%) calc(10% - 5px);
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is the width of the gutter in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) or grid layout.

- `<percentage>`

  [`<percentage>`](/api/css/data-type/percentage.md) is the width of the gutter separating the lines, relative to the dimension of the element.

## Formal definition

| Initial value | as each of the properties of the shorthand: 
- `row-gap: 0`
- `column-gap: 0` |
| Applies to | flex containers, grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to corresponding dimension of the content area(e.g.,`row-gap` refer to column axis size) |


## Formal syntax

```
gap =
  <'row-gap'> <'column-gap'>?

<row-gap> = <length-percentage [0,∞]>

<column-gap> = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-columns.md
---

# grid-auto-columns

APISummary
## Introduction

The `grid-auto-columns` CSS property specifies the size of an implicitly-created grid column track or pattern of tracks.

If a grid item is positioned into a column that is not explicitly sized by [`grid-template-columns`](/api/css/properties/grid-template-columns.md), implicit grid tracks are created to hold it. This can happen either by explicitly positioning into a column that is out of range, or by the auto-placement algorithm creating additional columns.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-auto-columns`
**Bundle:** `dist/grid-auto-columns.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridAutoColumns = () => {
  const Container1Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoColumns: "100px",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const Container2Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoColumns: "1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const item1Style = {
    gridColumnStart: "1",
    gridColumnEnd: "3",
  };

  const item2Style = {
    gridColumnStart: "2",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-columns: 100px</text>
      <view style={Container1Style}>
        <text className="item" style={item1Style}>ONE</text>
        <text className="item" style={item2Style}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-columns: 1fr</text>
      <view style={Container2Style}>
        <text className="item" style={item1Style}>ONE</text>
        <text className="item" style={item2Style}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoColumns />);

```



## Syntax

```css
/* Keyword values */
grid-auto-columns: max-content;
grid-auto-columns: auto;

/* <length> values */
grid-auto-columns: 100px;

/* <percentage> values */
grid-auto-columns: 10%;
grid-auto-columns: 33.3%;

/* <flex> values */
grid-auto-columns: 0.5fr;
grid-auto-columns: 3fr;

/* minmax() values */
grid-auto-columns: minmax(100px, auto);
grid-auto-columns: minmax(max-content, 2fr);

/* fit-content() values */
grid-auto-columns: fit-content(400px);
grid-auto-columns: fit-content(20%);

/* multiple track-size values */
grid-auto-columns: 100px 150px 390px;
grid-auto-columns: 10% 33.3%;
grid-auto-columns: 0.5fr 3fr 1fr;
grid-auto-columns: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

### Values

- `auto`

  **Default value**.

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `<length>`

  Is a non-negative length.

- `<percentage>`

  Is a non-negative `<percentage>` value relative to the inline size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `max(minimum, min(limit, max-content))`, where minimum represents an `auto` minimum (which is often, but not always, equal to a `min-content` minimum), and limit is the track sizing function passed as an argument to fit-content(). This is essentially calculated as the smaller of `minmax(auto, max-content)` and `minmax(auto, limit)`.

## Formal definition

| Initial value | `auto` |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to corresponding dimension of the content area |


## Formal syntax

```
grid-auto-columns =
  <track-size>+

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines), `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-columns`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-columns](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-columns)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-flow.md
---

# grid-auto-flow

APISummary
## Introduction

The `grid-auto-flow` CSS property controls how the auto-placement algorithm works, specifying exactly how auto-placed items get flowed into the grid.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-auto-flow`
**Bundle:** `dist/grid-auto-flow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridAutoFlow = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-flow: row</text>
      <view className="container" style={{ gridAutoFlow: "row" }}>
        <text className="item" style={{ gridColumnStart: "span 2" }}>ONE</text>
        <text className="item" style={{ gridColumnStart: "span 2" }}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-flow: column</text>
      <view className="container" style={{ gridAutoFlow: "column" }}>
        <text className="item" style={{ gridColumnStart: "span 2" }}>ONE</text>
        <text className="item" style={{ gridColumnStart: "span 2" }}>TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoFlow />);

```



## Syntax

```css
grid-auto-flow: row;
grid-auto-flow: column;
grid-auto-flow: row dense;
grid-auto-flow: column dense;
grid-auto-flow: dense;
```

### Values

This property may take one of two forms:

a single keyword: one of row, column, or dense.

two keywords: row dense or column dense.

- `row`

  **Default value**. Items are placed by filling each row in turn, adding new rows as necessary. If neither row nor column is provided, row is assumed.

- `column`

  Items are placed by filling each column in turn, adding new columns as necessary.

- `dense`

  "dense" packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later. This may cause items to appear out-of-order, when doing so would fill in holes left by larger items.

  If it is omitted, a "sparse" algorithm is used, where the placement algorithm only ever moves "forward" in the grid when placing items, never backtracking to fill holes. This ensures that all of the auto-placed items appear "in order", even if this leaves holes that could have been filled by later items.

## Formal definition

| Initial value | row |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-auto-flow = [ row | column ] || dense
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-flow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-flow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-flow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-auto-rows.md
---

# grid-auto-rows

APISummary
## Introduction

The `grid-auto-rows` CSS property specifies the size of an implicitly-created grid row track or pattern of tracks.

If a grid item is positioned into a row that is not explicitly sized by [grid-template-rows](/api/css/properties/grid-template-rows.md), implicit grid tracks are created to hold it. This can happen either by explicitly positioning into a row that is out of range, or by the auto-placement algorithm creating additional rows.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-auto-rows`
**Bundle:** `dist/grid-auto-rows.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridAutoRows = () => {
  const Container1Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoRows: "50px",
    gridTemplateColumns: "1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    height: "300px",
  };

  const Container2Style = {
    display: "grid" as const,
    gap: "10px",
    gridAutoRows: "1fr",
    gridTemplateColumns: "1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
    height: "300px",
  };

  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-auto-rows: 50px</text>
      <view style={Container1Style}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-auto-rows: 1fr</text>
      <view style={Container2Style}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridAutoRows />);

```



## Syntax

```css
/* Keyword values */
grid-auto-rows: max-content;
grid-auto-rows: auto;

/* <length> values */
grid-auto-rows: 100px;

/* <percentage> values */
grid-auto-rows: 10%;
grid-auto-rows: 33.3%;

/* <flex> values */
grid-auto-rows: 0.5fr;
grid-auto-rows: 3fr;

/* minmax() values */
grid-auto-rows: minmax(100px, auto);
grid-auto-rows: minmax(max-content, 2fr);

/* multiple track-size values */
grid-auto-rows: 100px 150px 390px;
grid-auto-rows: 10% 33.3%;
grid-auto-rows: 0.5fr 3fr 1fr;
grid-auto-rows: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

### Values

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `<length>`

  Is a non-negative length.

- `<percentage>`

  Is a non-negative `<percentage>` value relative to the block size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at argument if it is greater than the `auto` minimum.

## Formal definition

| Initial value | `auto` |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to corresponding dimension of the content area |


## Formal syntax

```
/* Keyword values */
grid-auto-rows: max-content;
grid-auto-rows: auto;

/* <length> values */
grid-auto-rows: 100px;

/* <percentage> values */
grid-auto-rows: 10%;
grid-auto-rows: 33.3%;

/* <flex> values */
grid-auto-rows: 0.5fr;
grid-auto-rows: 3fr;

/* minmax() values */
grid-auto-rows: minmax(100px, auto);
grid-auto-rows: minmax(max-content, 2fr);

/* multiple track-size values */
grid-auto-rows: 100px 150px 390px;
grid-auto-rows: 10% 33.3%;
grid-auto-rows: 0.5fr 3fr 1fr;
grid-auto-rows: 100px minmax(100px, auto) 10% 0.5fr fit-content(400px);
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-auto-rows`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-rows](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-auto-rows)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-end.md
---

# grid-column-end

APISummary
## Introduction

The `grid-column-end` CSS property specifies a grid item's end position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-column-end`
**Bundle:** `dist/grid-column-end.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridColumnEnd = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-end: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-end: 3</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "3" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-end: -1</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnEnd: "-1" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnEnd />);

```



## Syntax

```css
/* <number> values */
grid-column-end: 2;
grid-column-end: 3;

/* span <number> values*/
grid-column-end: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Contributes the nth grid line to the grid item's placement. If a negative integer is given, it instead counts in reverse, starting from the end edge of the explicit grid. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement such that the column end edge of the grid item's grid area is n lines from the start edge.

## Formal definition

| Initial value | `auto` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-column-end = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-span.md
---

#Deprecated grid-column-span
APISummary
:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-column-start`](/api/css/properties/grid-column-start.md) and [`grid-column-end`](/api/css/properties/grid-column-end.md), this css property will be overridden.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-column-span`
**Bundle:** `dist/grid-column-span.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridColumnSpan = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-span: 1</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "1",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-span: 2</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "2",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-span: 3</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridColumnSpan in `@lynx-js/types`
            gridColumnSpan: "3",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnSpan />);

```



## Syntax

```css
/* <number> values */
grid-column-span: 1;
grid-column-span: 2;
```

### Values

- `<number>`

  Contributes a grid span to the grid item's placement.

## Formal definition

| Initial value | `1` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-column-span = <number>
```

## Difference between web

- There is no such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-span`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-column-start.md
---

# grid-column-start

APISummary
## Introduction

The `grid-column-start` CSS property specifies a grid item's start position within the grid column by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-column-start`
**Bundle:** `dist/grid-column-start.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridColumnStart = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-column-start: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-start: 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-column-start: -2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridColumnStart: "-2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridColumnStart />);

```



## Syntax

```css
/* <number> values */
grid-column-start: 1;
grid-column-start: 2;

/* span  <number> values*/
grid-column-start: span 1;
```

### Values

- `auto`

  **Default value**. A keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Contributes the nth grid line to the grid item's placement. If a negative integer is given, it counts in reverse, starting from the end edge of the explicit grid. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement, such that the column start edge of the grid item's grid area is n lines from the end edge.

## Formal definition

| Initial value | `auto` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-column-start = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-column-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-column-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-end.md
---

# grid-row-end

APISummary
## Introduction

The `grid-row-end` CSS property specifies a grid item's end position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-row-end`
**Bundle:** `dist/grid-row-end.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridRowEnd = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-end: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-end: span 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "span 2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-end: -1</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowEnd: "-1" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowEnd />);

```



## Syntax

```css
/* <number> values */
grid-row-end: 2;
grid-row-end: 3;

/* span  <number> values*/
grid-row-end: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Grid item's end position. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement such that the row end edge of the grid item's grid area is n lines from the start edge.

## Formal definition

| Initial value | `auto` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-row-end = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-span.md
---

#Deprecated grid-row-span
APISummary
:::warning
This API is deprecated.
:::

## Introduction

Contributes a grid span to the grid item's placement.
If there are [`grid-row-start`](/api/css/properties/grid-row-start.md) and [`grid-row-end`](/api/css/properties/grid-row-end.md), this css property will be overridden.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-row-span`
**Bundle:** `dist/grid-row-span.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridRowSpan = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-span: 1</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "1",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-span: 2</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "2",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-span: 3</text>
      <view className="container">
        <text
          className="item"
          style={{
            backgroundColor: "rgb(255,53,26)",
            // @ts-expect-error TODO(types): Support gridRowSpan in `@lynx-js/types`
            gridRowSpan: "3",
          }}
        >
          ONE
        </text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowSpan />);

```



## Syntax

```css
/* <number> values */
grid-row-span: 1;
grid-row-span: 2;
```

### Values

- `<number>`

  Contributes a grid span to the grid item's placement.

## Formal definition

| Initial value | `1` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-row-span = <number>
```

## Difference between web

- There is no such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-span`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-row-start.md
---

# grid-row-start

APISummary
## Introduction

The `grid-row-start` CSS property specifies a grid item's start position within the grid row by contributing a line, a span, or nothing (automatic) to its grid placement.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-row-start`
**Bundle:** `dist/grid-row-start.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridRowStart = () => {
  const titleStyle = {
    fontSize: "45rpx" as const,
    fontWeight: "900" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-row-start: auto</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "auto" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-start: 2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>

      <text style={titleStyle}>grid-row-start: -2</text>
      <view className="container">
        <text className="item" style={{ backgroundColor: "rgb(255,53,26)", gridRowStart: "-2" }}>ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
      </view>
    </>
  );
};

root.render(<GridRowStart />);

```



## Syntax

```css
/* <number> values */
grid-row-start: 1;
grid-row-start: 2;

/* span  <number> values*/
grid-row-start: span 1;
```

### Values

- `auto`

  **Default value**. Is a keyword indicating that the property contributes nothing to the grid item's placement, indicating auto-placement, an automatic span, or a default span of `1`.

- `<number>`

  Grid item's start position. An integer value of 0 is invalid.

- span && `<number>`

  Contributes a grid span to the grid item's placement; such that the row start edge of the grid item's grid area is n lines from the end edge.

## Formal definition

| Initial value | `auto` |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
grid-row-start = <number> | [span && <number>]
```

## Difference between web

- `<custom-ident>`, `span && <custom-ident>`, `<integer> && <custom-ident>?` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-row-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-row-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-template-columns.md
---

# grid-template-columns

APISummary
## Introduction

The `grid-template-columns` CSS property defines track sizing functions of the grid columns.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-template-columns`
**Bundle:** `dist/grid-template-columns.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridTemplateColumn = () => {
  const titleStyle = {
    fontSize: "17px" as const,
    fontWeight: "600" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-template-columns: 100px 200px</text>
      <view className="container" style={{ gridTemplateColumns: "100px 200px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns: 1fr 100px</text>
      <view className="container" style={{ gridTemplateColumns: "1fr 100px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns: 1fr 2fr</text>
      <view className="container" style={{ gridTemplateColumns: "1fr 2fr" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
      </view>

      <text style={titleStyle}>grid-template-columns:</text>
      <text style={titleStyle}>20% max-content minmax(50px, max-content)</text>
      <view
        className="container"
        style={{
          gridTemplateColumns: "20% max-content minmax(50px, max-content)",
          gridTemplateRows: "auto",
          height: "max-content",
        }}
      >
        <text className="item">20%</text>
        <text className="item" style={{ fontSize: "35px" }}>No Wrap</text>
        <text className="item">min-width:50px, will fit the container</text>
      </view>
    </>
  );
};

root.render(<GridTemplateColumn />);

```



## Syntax

```css
/* Keyword value */
grid-template-columns: none;

/* <track-list> values */
grid-template-columns: 100px 1fr;
grid-template-columns: minmax(100px, 1fr);
grid-template-columns: fit-content(40%);
grid-template-columns: repeat(3, 200px);
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is a non-negative length, giving the width of the column.

- `<percentage>`

  Is a non-negative [`<percentage>`](/api/css/data-type/percentage.md) value relative to the inline size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `max(minimum, min(limit, max-content))`, where minimum represents an `auto` minimum (which is often, but not always, equal to a `min-content` minimum), and limit is the track sizing function passed as an argument to fit-content(). This is essentially calculated as the smaller of `minmax(auto, max-content)` and `minmax(auto, limit)`.

- `repeat(<positive-integer>, [<length> | <percentage> | auto])`

  Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form.

## Formal definition

| Initial value | Indicates that there is no explicit grid. Any columns will be implicitly generated and their size will be determined by the[`grid-auto-columns`](/api/css/properties/grid-auto-columns)property |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to corresponding dimension of the content area |


## Formal syntax

```
grid-template-columns =
  <track-list>

<track-list> =
   <track-size> | <track-repeat>

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-repeat> =
  repeat([ <integer [1,∞]> ] , <track-size>)

<fixed-size> =
  <fixed-breadth>                                   |
  minmax( <fixed-breadth> , <track-breadth> )       |
  minmax( <inflexible-breadth> , <fixed-breadth> )

<fixed-repeat> =
  repeat( [ <integer [1,∞]> ] , <fixed-size>)

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>

<fixed-breadth> =
  <length-percentage [0,∞]>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.
- `none` is not supported.
- `masonry` and `subgrid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-template-columns`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-columns](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-columns)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/grid-template-rows.md
---

# grid-template-rows

APISummary
## Introduction

The `grid-template-rows` CSS property defines track sizing functions of the grid rows.

## Examples

**This is an example below: css-api**

**Entry:** `src/grid-template-rows`
**Bundle:** `dist/grid-template-rows.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const GridTemplateRow = () => {
  const titleStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "700" as const,
    alignSelf: "center" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>grid-template-rows: 40px 40px 40px;</text>
      <view className="container" style={{ gridTemplateRows: "40px 40px 40px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-template-rows: 1fr 60px 1fr;</text>
      <view className="container" style={{ gridTemplateRows: "1fr 60px 1fr" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>

      <text style={titleStyle}>grid-template-rows: 1fr max-content 2fr;</text>
      <view className="container" style={{ gridTemplateRows: "1fr max-content 2fr", height: "220px" }}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">max-content: will take the maximum size of the items as the row size</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
      </view>
    </>
  );
};

root.render(<GridTemplateRow />);

```



## Syntax

```css
/* auto values*/
grid-template-rows: auto auto;
/* <length> values */
grid-template-rows: 120px auto;
/* repeat func */
grid-template-rows: repeat(2, 100px) auto;
grid-template-rows: repeat(2, 100px auto) 200px;
```

### Values

- `<length>`

  [`<length>`](/api/css/data-type/length.md) is a non-negative length, giving the width of the row.

- `<percentage>`

  Is a non-negative [`<percentage>`](/api/css/data-type/percentage.md) value relative to the block size of the grid container.

- `<flex>`

  Is a non-negative dimension with the unit `fr` specifying the track's flex factor. Each `<flex>`-sized track takes a share of the remaining space in proportion to its flex factor.

  When appearing outside a `minmax()` notation, it implies an automatic minimum (i.e. `minmax(auto, <flex>)`).

- `max-content`

  Is a keyword representing the largest maximal content contribution of the grid items occupying the grid track.

- `auto`

  As a maximum represents the largest `max-content` size of the items in that track.

  As a minimum represents the largest minimum size of items in that track (specified by the [`min-width`](/api/css/properties/min-width.md)/[`min-height`](/api/css/properties/min-height.md) of the items). This is often, though not always, the [`min-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/min-content) size.

  If used outside of [`minmax()`](https://developer.mozilla.org/en-US/docs/Web/CSS/minmax) notation, `auto` represents the range between the minimum and maximum described above.

  :::info
  `auto` track sizes (and only `auto` track sizes) can be stretched by the [`align-content`](/api/css/properties/align-content.md) and [`justify-content`](/api/css/properties/justify-content.md) properties. Therefore by default, an `auto` sized track will take up any remaining space in the grid container.
  :::

- `minmax(min, max)`

  Is a functional notation that defines a size range, greater than or equal to min, and less than or equal to max. If max is smaller than min, then max is ignored and the function is treated as min. As a maximum, a `<flex>` value sets the track's flex factor. It is invalid as a minimum.

- `fit-content( [ <length> | <percentage> ] )`

  Represents the formula `min(max-content, max(auto, argument))`, which is calculated similar to `auto` (i.e. `minmax(auto, max-content)`), except that the track size is clamped at argument if it is greater than the `auto` minimum.

- `repeat(<positive-integer>, [<length> | <percentage> | auto])`

  Represents a repeated fragment of the track list, allowing a large number of columns that exhibit a recurring pattern to be written in a more compact form.

## Formal definition

| Initial value | Is a keyword meaning that there is no explicit grid. Any rows will be implicitly generated and their size will be determined by the[`grid-auto-rows`](/api/css/properties/grid-auto-rows)property |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to corresponding dimension of the content area |


## Formal syntax

```
grid-template-rows =
  <track-list>

<track-list> =
   <track-size> | <track-repeat>

<track-size> =
  <track-breadth>                                   |
  minmax( <inflexible-breadth> , <track-breadth> )  |
  fit-content( <length-percentage [0,∞]> )

<track-repeat> =
  repeat([ <integer [1,∞]> ] , <track-size>)

<fixed-size> =
  <fixed-breadth>                                   |
  minmax( <fixed-breadth> , <track-breadth> )       |
  minmax( <inflexible-breadth> , <fixed-breadth> )

<fixed-repeat> =
  repeat( [ <integer [1,∞]> ] , <fixed-size>)

<track-breadth> =
  <length-percentage [0,∞]>  |
  <flex [0,∞]>               |
  max-content                |
  auto

<inflexible-breadth> =
  <length-percentage [0,∞]>  |
  max-content                |
  auto

<length-percentage> =
  <length>      |
  <percentage>

<fixed-breadth> =
  <length-percentage [0,∞]>
```

## Difference between web

- [`[line-names]`](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_using_named_grid_lines) is not supported.
- `none` is not supported.
- `masonry` and `subgrid` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.grid-template-rows`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-rows](https://developer.mozilla.org/zh-CN/docs/Web/CSS/grid-template-rows)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/height.md
---

# height

APISummary
## Introduction

The `height` CSS property specifies the height of an element. By default, the property defines the height of the border area. If [`box-sizing`](/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the height of the content area.

The [`min-height`](/api/css/properties/min-height.md) and [`max-height`](/api/css/properties/max-height.md) properties override `height`.

## Examples

**This is an example below: css-api**

**Entry:** `src/height`
**Bundle:** `dist/height.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Height = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view style={{ display: "linear", linearOrientation: "horizontal" }}>
        <text
          style={{
            height: "100px",
            border: "20px solid orange",
          }}
        >
          border-box
        </text>

        <text
          style={{
            height: "100px",
            border: "20px solid orange",
            boxSizing: "content-box",
          }}
        >
          content-box
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<Height />);

```



## Syntax

```css
/* <length> values */
height: 300px;
height: 25em;

/* <percentage> value */
height: 75%;

/* Keyword values */
height: max-content;
height: fit-content;
height: fit-content(20em);
height: auto;
```

### Values

- `auto`

  **Default value**. lynx will calculate and select a height for the specified element.

- `<length>`

  [`<length>`](/api/css/data-type/length.md) defines the height as a distance value.

- `<percentage>`

  Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

- `max-content`

  The intrinsic preferred height.

- `fit-content`

  [`fit-content`](/api/css/data-type/fit-content.md) uses the computed size with the available space replaced by the specified argument.

## Formal definition

| Initial value | `auto` |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | The percentage is calculated with respect to the height of the generated box's containing block |


## Formal syntax

```
height =
  auto                                      |
  <length-percentage [0,∞]>                 |
  max-content                               |
  fit-content( <length-percentage [0,∞]> )

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- By default, the property defines the height of the border area, while Web is `content area`.
- `min-content` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/image-rendering.md
---

# image-rendering

APISummary
## Introduce

`image-rendering`

Used to set the image scaling algorithm. Currently only works with `<image>` and `background-image`
Currently it only applies to the element itself and will not take effect on child elements.

The image will be scaled when the dimensions specified by the front end are not the original dimensions of the image. For example, if there is an image with a physical pixel size of 100×100, but the actual width and height dimensions are set to 200×200px (or 50×50px), then the image will be reduced or reduced according to the algorithm specified by image-rendering. Enlarge to new size. This property has no effect on unscaled images.

## Examples

**This is an example below: css-api**

**Entry:** `src/image-rendering`
**Bundle:** `dist/image-rendering.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const ImageRendering = () => {
  const url =
    "data:image/bmp;base64,Qk12BQAAAAAAADYAAAAoAAAAFQAAAOv///8BABgAAAAAAEAFAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA////AAAAAAAA////////AAAA////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////wAAAP///////wAAAP///////////////wAAAP///////////////////wAAAAAAAAD///8AAAAAAAAAAAD///8AAAD///8AAAAAAAAAAAD///////////8AAAD///8AAAAAAAAAAAD///8AAAAAAAAA////AAAAAAAAAAAA////AAAA////AAAAAAAA////////AAAA////AAAA////AAAAAAAAAAAA////AAAAAAAAAP///wAAAAAAAAAAAP///wAAAP///////wAAAAAAAP///////////wAAAP///wAAAAAAAAAAAP///wAAAAAAAAD///////////////////8AAAD///8AAAD///8AAAD///////////8AAAD///////////////////8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA////AAAA////AAAA////AAAA////AAAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////////////////wAAAP///wAAAP///////////////////////////////////////wAAAAAAAAD///8AAAD///////8AAAAAAAD///////8AAAAAAAAAAAAAAAAAAAAAAAD///8AAAAAAAD///8AAAAAAAAAAAAA////AAAAAAAA////////////////////AAAA////////AAAAAAAA////AAAAAAAA////AAAAAAAAAP///wAAAP///wAAAAAAAAAAAAAAAAAAAAAAAAAAAP///////////////////wAAAP///////////wAAAAAAAAD///////8AAAAAAAD///////////////////////////////8AAAD///////8AAAAAAAD///8AAAAAAAAAAAAA////AAAAAAAAAAAA////////AAAA////////AAAAAAAAAAAA////////////AAAA////////////AAAAAAAAAP///////////////////////////////////////wAAAAAAAAAAAAAAAAAAAAAAAP///wAAAAAAAP///////wAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8AAAD///8AAAD///////////8AAAAAAAAAAAD///////8AAAD///8AAAAA////////////////////AAAA////////AAAAAAAA////////AAAA////////////////////////AAAAAAAAAP///wAAAAAAAAAAAP///wAAAP///////////wAAAP///wAAAP///wAAAP///////wAAAAAAAAAAAP///wAAAAD///8AAAAAAAAAAAD///8AAAD///8AAAAAAAD///8AAAAAAAAAAAAAAAAAAAD///8AAAD///8AAAD///8AAAAA////AAAAAAAAAAAA////AAAA////////AAAA////////////////AAAAAAAAAAAA////AAAA////////AAAAAP///////////////////wAAAP///wAAAP///wAAAAAAAAAAAAAAAP///////wAAAAAAAP///////////wAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8AAAAAAAAAAAD///////////////////8AAAD///////8AAAD///8A";

  const verticalStyle = {
    linearOrientation: "vertical" as const,
  };

  const pixelatedStyle = {
    imageRendering: "pixelated" as const,
  };

  const autoStyle = {
    imageRendering: "auto" as const,
  };

  const crispEdgesStyle = {
    imageRendering: "crisp-edges" as const,
  };

  return (
    <scroll-view>
      <view style={verticalStyle}>
        <view className="image size" style={pixelatedStyle}></view>
        <view className="image size" style={autoStyle}></view>
        <view className="image size" style={crispEdgesStyle}></view>
      </view>

      <view style={verticalStyle}>
        <image src={url} className="size" style={pixelatedStyle}></image>
        <image src={url} className="size" style={autoStyle}></image>
        <image src={url} className="size" style={crispEdgesStyle}></image>
      </view>
    </scroll-view>
  );
};

root.render(<ImageRendering />);

```



## Syntax

```css
image-rendering: auto;
image-rendering: crisp-edges;
image-rendering: pixelated;
```

### Values

#### `auto`

Default value, platform layer default setting. Generally implemented as bilinear interpolation

#### `crisp-edges`

The image must be scaled using an algorithm that effectively preserves contrast and edges in the image, and that does not smooth the colors or introduce blur into the image during processing. This attribute value is suitable for pixel art works, such as images in some web games.
This is designed for pixel games (refer to Pixel-art scaling algorithms), and is not implemented by mainstream browsers.
Currently, lynx does not support it, and the effect is the same as auto.

#### `pixelated`

When zooming in and out of an image, the nearest neighbor algorithm is used, so the image appears to be made up of large blocks of pixels.

## Formal definition

| Initial value | auto |
| Applies to | `image`, view's `background-image` |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
image-rendering = auto | crisp-edges | pixelated
```

## The difference from the web

1. Only takes effect on the element itself, not on child elements.
2. Global attribute values ​​such as inherit, unset, etc. are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.image-rendering`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/image-rendering](https://developer.mozilla.org/zh-CN/docs/Web/CSS/image-rendering)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| iOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay Android | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay iOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay macOS | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Clay Windows | 2.14 | only <image> and  background-image supports, it only applies to an element itself.; ⚠️ Partial implementation |
| Web | ✅ Yes | it applies to an element itself, to any images set in its other properties, and to its descendants.; ⚠️ Partial implementation |

**Description:** The image-rendering CSS property sets an image scaling algorithm. The property applies to an element itself.




---
url: /api/css/properties/inset-inline-end.md
---

# inset-inline-end

APISummary
## Introduction

The `inset-inline-end` CSS property defines the logical inline end inset of an element, which maps to a physical offset depending on the element's directionality. It corresponds to the [`right`](/api/css/properties/right.md) or [`left`](/api/css/properties/left.md) property depending on the values defined for [`direction`](/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`right`](/api/css/properties/right.md) property.
In `RTL`, it corresponds to the [`left`](/api/css/properties/left.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/inset-inline-end`
**Bundle:** `dist/inset-inline-end.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const InsetInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    insetInlineStart: "20px",
    insetInlineEnd: "50px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <view className="intro" style={introStyle}></view>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<InsetInlineEnd />);

```



## Syntax

```css
/* <length> values */
inset-inline-end: 3px;
inset-inline-end: 2rpx;
inset-inline-end: 2.4em;
inset-inline-end: 3rem;

inset-inline-end: 10%;

/* Keyword value */
inset-inline-end: auto;

/* calc */
inset-inline-end: calc(1px + 1px);
```

### Values

The `inset-inline-end` property takes the same values as the [`left`](/api/css/properties/left.md) property.

## Formal definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | logical-width of containing block |


## Formal syntax

```
inset-inline-end =
  auto                 |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- In Lynx, `writing-mode` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.inset-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |

**Description:** The inset-inline-end CSS property defines the logical inline end inset of an element, which maps to a physical offset depending on the element's directionality.




---
url: /api/css/properties/inset-inline-start.md
---

# inset-inline-start

APISummary
## Introduction

The `inset-inline-start` CSS property defines the logical inline start inset of an element, which maps to a physical offset depstarting on the element's directionality. It corresponds to the [`right`](/api/css/properties/right.md) or [`left`](/api/css/properties/left.md) property depstarting on the values defined for [`direction`](/api/css/properties/direction.md).

In `LTR`, it corresponds to the [`left`](/api/css/properties/left.md) property.
In `RTL`, it corresponds to the [`right`](/api/css/properties/right.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/inset-inline-start`
**Bundle:** `dist/inset-inline-start.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const InsetInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    insetInlineStart: "50px",
    insetInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <view className="intro" style={introStyle}></view>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<InsetInlineStart />);

```



## Syntax

```css
/* <length> values */
inset-inline-start: 3px;
inset-inline-start: 2rpx;
inset-inline-start: 2.4em;
inset-inline-start: 3rem;

inset-inline-start: 10%;

/* Keyword value */
inset-inline-start: auto;

/* calc */
inset-inline-start: calc(1px + 1px);
```

### Values

The `inset-inline-start` property takes the same values as the [`left`](/api/css/properties/left.md) property.

## Formal definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | logical-width of containing block |


## Formal syntax

```
inset-inline-start =
  auto                 |
  <length-percentage>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the web

- In Lynx, `writing-mode` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.inset-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/inset-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |

**Description:** The inset-inline-start CSS property defines the logical inline start inset of an element, which maps to a physical offset depending on the element's directionality.




---
url: /api/css/properties/justify-content.md
---

# justify-content

APISummary
## Introduction

The CSS `justify-content` property defines how distributes space between and around content items along the main-axis of a flexible box layout, [linear](/guide/ui/layout/linear-layout.md) container, and the inline axis of a grid layout container.

## Examples

**This is an example below: css-api**

**Entry:** `src/justify-content`
**Bundle:** `dist/justify-content.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const JustifyContent = () => {
  const boxStyle = {
    width: "30px",
    height: "30px",
  };

  const redBoxStyle = {
    ...boxStyle,
    backgroundColor: "red",
  };

  const yellowBoxStyle = {
    ...boxStyle,
    backgroundColor: "yellow",
  };

  const greenBoxStyle = {
    ...boxStyle,
    backgroundColor: "green",
  };

  const blueBoxStyle = {
    ...boxStyle,
    backgroundColor: "blue",
  };

  const flexStartStyle = {
    justifyContent: "flex-start" as const,
  };

  const flexEndStyle = {
    justifyContent: "flex-end" as const,
  };

  const centerStyle = {
    justifyContent: "center" as const,
  };

  const spaceBetweenStyle = {
    justifyContent: "space-between" as const,
  };

  const spaceAroundStyle = {
    justifyContent: "space-around" as const,
  };

  const spaceEvenlyStyle = {
    justifyContent: "space-evenly" as const,
  };

  return (
    <>
      <text>justify-content:flex-start;</text>
      <view className="container" style={flexStartStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:flex-end;</text>
      <view className="container" style={flexEndStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:center;</text>
      <view className="container" style={centerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-between;</text>
      <view className="container" style={spaceBetweenStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-around;</text>
      <view className="container" style={spaceAroundStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>

      <text>justify-content:space-evenly;</text>
      <view className="container" style={spaceEvenlyStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
        <view style={blueBoxStyle} />
      </view>
    </>
  );
};

root.render(<JustifyContent />);

```



## Syntax

```css
/* Positional alignment */
justify-content: center; /* Pack items around the center */
justify-content: start; /* Pack items from the start */
justify-content: end; /* Pack items from the end */
justify-content: flex-start; /* Pack flex items from the start */
justify-content: flex-end; /* Pack flex items from the end */

/* Distributed alignment */
justify-content: space-between; /* Distribute items evenly
                                   The first item is flush with the start,
                                   the last is flush with the end */
justify-content: space-around; /* Distribute items evenly
                                   Start and end gaps are half the size of the space
                                   between each item */
justify-content: space-evenly; /* Distribute items evenly
                                   Start, in-between, and end gaps have equal sizes */
justify-content: stretch; /* Distribute items evenly
                                   Stretch 'auto'-sized items to fit
                                   the container */
```

### Values

#### `stretch`

**Default value**.If the combined size of the items along the main axis is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container along the main axis.

:::info
For flex boxes, the `stretch` value behaves as `flex-start` or `start`. This is because, in flex boxes, stretching is controlled using the [`flex-grow`](/api/css/properties/flex-grow.md) property.

In [linear](/guide/ui/layout/linear-layout.md), the `stretch` value behaves as `flex-start` or `start`.
:::

#### `start`

The items are packed flush to each other toward the start edge of the alignment container in the main axis.

#### `end`

The items are packed flush to each other toward the end edge of the alignment container in the main axis.

#### `flex-start`

The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-start side. This only applies to flexible box layout items. For items that are not children of a flex container, this value is treated like `start`.

#### `flex-end`

The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-end side. This only applies to flexible box layout items. For items that are not children of a flex container, this value is treated like `end`.

#### `center`

The items are packed flush to each other toward the center of the alignment container along the main axis.

#### `space-between`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The first item is flush with the main-start edge, and the last item is flush with the main-end edge.

#### `space-around`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The empty space before the first and after the last item equals half of the space between each pair of adjacent items.

:::info
In [linear](/guide/ui/layout/linear-layout.md), the `space-around` value behaves as `flex-start` or `start`.
:::

#### `space-evenly`

The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

:::info
In [linear](/guide/ui/layout/linear-layout.md), the `space-evenly` value behaves as `flex-start` or `start`.
:::

## Formal definition

| Initial value | stretch |
| Applies to | flex/grid/linear containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
justify-content = <content-distribution> | <content-position>

<content-distribution> =
  space-between  |
  space-around   |
  space-evenly   |
  stretch

<content-position> =
  center      |
  start       |
  end         |
  flex-start  |
  flex-end
```

## Difference with the web

- `normal` is not supported. Default value is `stretch`.
- `left` and `right` are not supported.
- `baseline`, `first baseline` and `last baseline` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-content`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-content](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/justify-items.md
---

# justify-items

APISummary
## Introduction

The CSS `justify-items` property defines the default [`justify-self`](/api/css/properties/justify-self.md) for all items of the box, giving them all a default way of justifying each box along the appropriate axis. It aligns the items inside their grid areas on the inline axis.

## Examples

**This is an example below: css-api**

**Entry:** `src/justify-items`
**Bundle:** `dist/justify-items.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const JustifyItems = () => {
  const getGridStyle = (justifyItems: string) => ({
    display: "grid" as const,
    gridTemplateColumns: "auto",
    justifyItems: justifyItems,
  });

  return (
    <>
      <text>justify-items:stretch</text>
      <view style={getGridStyle("stretch")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:start</text>
      <view style={getGridStyle("start")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:end</text>
      <view style={getGridStyle("end")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
      <text>justify-items:center</text>
      <view style={getGridStyle("center")}>
        <text className="item">Item</text>
        <text className="item">Item</text>
      </view>
    </>
  );
};

root.render(<JustifyItems />);

```



## Syntax

```css
justify-items: stretch;
justify-items: center;
justify-items: start;
justify-items: end;
```

### Values

#### `stretch`

**Default value**. If the combined size of the items is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container.

#### `center`

The items are packed flush to each other toward the center of the alignment container.

#### `start`

The item is packed flush to each other toward the start edge of the alignment container in the appropriate axis.

#### `end`

The item is packed flush to each other toward the end edge of the alignment container in the appropriate axis.

## Formal definition

| Initial value | stretch |
| Applies to | grid containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
justify-items = stretch | center | start | end
```

## Difference with the web

[mdn: justify-items](https://developer.mozilla.org/en/docs/Web/CSS/justify-items)

1. `normal` is not supported. Initial value is `stretch`.
2. `self-start`, `self-end`, `left`, `right`, `flex-start`, `flex-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-items`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-items](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-items)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |

**Description:** defines the default justify-self for all items of the box, giving them all a default way of justifying each box along the appropriate axis.




---
url: /api/css/properties/justify-self.md
---

# justify-self

APISummary
## Introduction

The CSS `justify-self` property sets the way a box is justified inside its alignment container along the appropriate axis. It aligns the items inside their grid areas on the inline axis.

## Examples

**This is an example below: css-api**

**Entry:** `src/justify-self`
**Bundle:** `dist/justify-self.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const JustifySelf = () => {
  const containerStyle = {
    display: "grid" as const,
    gridTemplateColumns: "auto",
  };

  const getJustifySelfStyle = (justify: string) => ({
    justifySelf: justify,
  });

  return (
    <view style={containerStyle}>
      <text className="item" style={getJustifySelfStyle("stretch")}>justify-self:stretch</text>
      <text className="item" style={getJustifySelfStyle("center")}>justify-self:center</text>
      <text className="item" style={getJustifySelfStyle("start")}>justify-self:start</text>
      <text className="item" style={getJustifySelfStyle("end")}>justify-self:end</text>
    </view>
  );
};

root.render(<JustifySelf />);

```



## Syntax

```css
justify-self: auto;
justify-self: stretch;
justify-self: center;
justify-self: start;
justify-self: end;
```

### Values

#### `auto`

**Default value**. The value used is the value of the [`justify-items`](/api/css/properties/justify-items.md) property of the parents box.

#### `stretch`

If the combined size of the items is less than the size of the alignment container, any auto-sized items have their size increased equally (not proportionally), while still respecting the constraints imposed by [`max-height`](/api/css/properties/max-height.md)/[`max-width`](/api/css/properties/max-width.md) (or equivalent functionality), so that the combined size exactly fills the alignment container.

#### `center`

The items are packed flush to each other toward the center of the alignment container.

#### `start`

The item is packed flush to each other toward the start edge of the alignment container in the appropriate axis.

#### `end`

The item is packed flush to each other toward the end edge of the alignment container in the appropriate axis.

## Formal definition

| Initial value | auto |
| Applies to | grid items |
| Inherited | no |
| Animatable |  |


## Formal syntax

justify-self =
auto |
stretch |
center |
start |
end

## Difference with the web

[mdn: justify-self](https://developer.mozilla.org/en/docs/Web/CSS/justify-self)

1. `normal` is not supported. Initial value is `stretch`.
2. `self-start`, `self-end`, `left`, `right`, `flex-start`, `flex-end` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.justify-self`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-self](https://developer.mozilla.org/zh-CN/docs/Web/CSS/justify-self)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.1 | - |
| Clay iOS | 2.1 | - |
| Clay macOS | 2.1 | - |
| Clay Windows | 2.1 | - |
| Web | ✅ Yes | - |

**Description:** The CSS justify-self property sets the way a box is justified inside its alignment container along the appropriate axis.




---
url: /api/css/properties/left.md
---

# left

APISummary
## Introduction

The `left` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `left` depends on how the element is positioned (i.e., the value of the position property):

- When `position` is set to `absolute` or `fixed`, the `left` property specifies the distance between the element's outer margin of left edge and the inner border of left edge of its containing block. (The containing block is the ancestor to which the element is relatively positioned.)

- When `position` is set to `relative`, the `left` property specifies the distance the element's left edge is moved to the right from its normal position.

When both `left` and `right` are defined, and `width` constraints don't prevent it, the element will stretch to satisfy both. If the element cannot stretch to satisfy both, the `position` of the element is overspecified. When this is the case, the `left` value has precedence when the container is left-to-right; the `right` value has precedence when the container is right-to-left.

## Examples

**This is an example below: css-api**

**Entry:** `src/left`
**Bundle:** `dist/left.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Left = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view
        style={{
          width: "210px",
          height: "210px",
          border: "5px",
          borderColor: "black",
        }}
      >
        <view
          style={{
            position: "absolute",
            left: "80px",
            width: "50px",
            height: "50px",
            backgroundColor: "red",
          }}
        >
        </view>
        <view
          style={{
            position: "fixed",
            left: "155px",
            width: "50px",
            height: "50px",
            backgroundColor: "green",
          }}
        >
        </view>
        <view
          style={{
            position: "relative",
            left: "155px",
            width: "50px",
            height: "50px",
            backgroundColor: "yellow",
          }}
        >
        </view>
        <view
          style={{
            width: "50px",
            height: "50px",
            backgroundColor: "blue",
          }}
        >
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Left />);

```



## Syntax

```css
/* <length> values */
left: 3px;
left: 2rpx;
left: 2.4em;
left: 3rem;

left: 10%;

/* Keyword value */
left: auto;

/* calc */
left: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the left edge of the containing block.

- for relatively positioned elements, the distance that the element is moved to the right of its normal position.

#### `<percentage>`

A `<percentage>` of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

## Formal definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
left =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the horizontal position of a positioned element. It has no effect on non-positioned elements.




---
url: /api/css/properties/letter-spacing.md
---

# letter-spacing

APISummary
## Introduction

The `letter-spacing` CSS property sets the horizontal spacing behavior between text characters.

## Examples

**This is an example below: css-api**

**Entry:** `src/letter-spacing`
**Bundle:** `dist/letter-spacing.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const LetterSpacing = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const text1Style = {
    fontSize: "16px",
    letterSpacing: "0px",
  };

  const text2Style = {
    fontSize: "16px",
    letterSpacing: "1px",
  };

  const text3Style = {
    fontSize: "16px",
    letterSpacing: "3rpx",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>Letter Spacing Test</text>
          <text style={text1Style}>letter-spacing:0px</text>
          <text style={text2Style}>letter-spacing:1px</text>
          <text style={text3Style}>letter-spacing:3rpx</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LetterSpacing />);

```



## Syntax

```css
/* <length> values */
letter-spacing: 0.3em;
letter-spacing: 3px;
letter-spacing: 0.3px;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Specifies extra inter-character space in addition to the default space between characters.

## Formal definition

| Initial value | empty value |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
<length>
```

## Difference with Web

- Only support `<length>`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.letter-spacing`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/letter-spacing](https://developer.mozilla.org/zh-CN/docs/Web/CSS/letter-spacing)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/line-height.md
---

# line-height

APISummary
## Introduction

The `line-height` CSS property sets the height of a line box. It's commonly used to set the distance between lines of text.

## Syntax

**This is an example below: css-api**

**Entry:** `src/line-height`
**Bundle:** `dist/line-height.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const LineHeight = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const text1Style = {
    lineHeight: "30px",
  };

  const text2Style = {
    fontSize: "16px",
    lineHeight: "3",
  };

  const text3Style = {
    fontSize: "16px",
    lineHeight: "50px",
  };

  const inlineText1Style = {
    fontSize: "30px",
  };

  const inlineText2Style = {
    fontSize: "40px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text className="item" style={text1Style}>XX{"\n"}XX{"\n"}XX</text>
          <text className="item" style={text2Style}>XX{"\n"}XX{"\n"}XX</text>
          <text className="item" style={text3Style}>
            XX
            <text style={inlineText1Style}>XX</text>
            <text style={inlineText2Style}>XX</text>
          </text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<LineHeight />);

```



### Values

- normal <br />
  Default value.

- `<number>` <br />
  The used value is this unitless `<number>` multiplied by the element's own font size.

- `<length>` <br />
  The specified `<length>` is used in the calculation of the line box height.

## Formal definition

| Initial value | normal |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
normal | <length> | <number>
```

## Difference with web

- `line-height` only effect `<text>` element.

## Best Practices

- `line-height` in lynx will clip text content, so the value must be greater than element's font-size

- `line-height` is **paragraph style** . set in inline text has no effect.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.line-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/line-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/line-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/linear-cross-gravity.md
---

#Deprecated linear-cross-gravity
APISummary
:::warning
This API is deprecated.
:::

## Introduction

Set the position of the child element on the cross axis of the parent container in [linear layout](/guide/ui/layout/linear-layout.md), is an style on the parent container. Similar to [`align-items`](/api/css/properties/align-items.md) in [flexible box layout](/guide/ui/layout/flexible-box-layout.md).

When using [`linear-layout-gravity`](/api/css/properties/linear-layout-gravity.md), [`align-self`](/api/css/properties/align-self.md), [`linear-cross-gravity`](/api/css/properties/linear-cross-gravity.md), and [`align-items`](/api/css/properties/align-items.md) simultaneously in a linear layout, the priority decreases from the first to the last. A higher-priority style will override a lower-priority style.

## Examples

**This is an example below: css-api**

**Entry:** `src/linear-cross-gravity`
**Bundle:** `dist/linear-cross-gravity.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const LinearCrossGravity = () => {
  const [linearDirection, setLinearDirection] = useState(false);
  const container1Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "none" as const,
  };
  const container2Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "start" as const,
  };
  const container3Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "end" as const,
  };
  const container4Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "center" as const,
  };
  const container5Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearCrossGravity: "stretch" as const,
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const view1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearDirection(!linearDirection)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearDirection ? "row" : "column"}"</text>
      <text className="title">linear-cross-gravity:none;(default)</text>
      <view className="linear_container" style={container1Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:start;</text>
      <view className="linear_container" style={container2Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:end;</text>
      <view className="linear_container" style={container3Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:center;</text>
      <view className="linear_container" style={container4Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-cross-gravity:stretch;</text>
      <view className="linear_container" style={container5Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearCrossGravity />);

```



## Syntax

```css
linear-cross-gravity: none;
linear-cross-gravity: start;
linear-cross-gravity: end;
linear-cross-gravity: center;
linear-cross-gravity: stretch;
```

### Values

- `none`

  **Default value**. When the size of the parent element cross axis size(such as the [`width`](/api/css/properties/width.md) when [`linear-direction: column`](/api/css/properties/linear-direction.md)) is fixed, and the size of the child element in this direction is auto, `none` will be equivalent to `stretch`. In other cases it is equivalent to `start`.

- `start`

  Align the beginning of the parent element's cross axis.

- `end`

  Align the end of the parent element's cross axis.

- `center`

  Align the center of the parent element's cross axis.

- `stretch`

  Fill the container's cross axis.

## Formal definition

| Initial value | none |
| Applies to | linear containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
linear-cross-gravity = none | start | end | center | stretch
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-cross-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.6 | - |
| Clay iOS | 1.6 | - |
| Clay macOS | 1.6 | - |
| Clay Windows | 1.6 | - |
| Web | ✅ Yes | - |

**Description:** Set the position of the child element on the cross axis of the parent container in linear layout.




---
url: /api/css/properties/linear-direction.md
---

# linear-direction

APISummary
## Introduction

The `linear-direction` CSS property sets how linear items are placed in the linear container defining the main axis and the direction.

Note that the values `row`, `row-reverse` are affected by the directionality of the linear container. If its [`dir`](/api/css/properties/direction.md) attribute is `ltr`, `row` represents the horizontal axis oriented from the left to the right, and `row-reverse` from the right to the left; if the `dir` attribute is `rtl`, `row` represents the axis oriented from the right to the left, and `row-reverse` from the left to the right.

## Examples

**This is an example below: css-api**

**Entry:** `src/linear-direction`
**Bundle:** `dist/linear-direction.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const LinearDirection = () => {
  const verticalContainerStyle = {
    display: "linear" as const,
    alignSelf: "center" as const,
    justifyContent: "center" as const,
    linearDirection: "column" as const,
  };

  const horizontalContainerStyle = {
    display: "linear" as const,
    alignSelf: "center" as const,
    justifyContent: "center" as const,
    linearDirection: "row" as const,
  };

  const redBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "red",
  };

  const yellowBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "yellow",
  };

  const greenBoxStyle = {
    width: "70px",
    height: "70px",
    backgroundColor: "green",
  };

  const textStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };

  return (
    <>
      <text style={textStyle}>linear-direction: column</text>
      <view style={verticalContainerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
      </view>
      <view style={{ height: "50px" }} />
      <text style={textStyle}>linear-direction: row</text>
      <view style={horizontalContainerStyle}>
        <view style={redBoxStyle} />
        <view style={yellowBoxStyle} />
        <view style={greenBoxStyle} />
      </view>
    </>
  );
};

root.render(<LinearDirection />);

```



## Syntax

```css
linear-direction: column;

/* Like <column>, but reversed */
linear-direction: column-reverse;

linear-direction: row;

/* Like <row>, but reversed */
linear-direction: row-reverse;
```

### Values

- `column`

  **Default value**. The linear container's main-axis is defined to be the same as vertical direction.

- `row`

  The linear container's main-axis is defined to be the same as the text direction. The main-start and main-end points are the same as the content direction.

- `column-reverse`

  Behaves the same as `column` but the main-start and main-end are opposite to the content direction.

- `row-reverse`

  Behaves the same as `row` but the main-start and main-end points are opposite to the content direction.

- `vertical` <Deprecated />

  Equivalent to `column`.

- `horizontal` <Deprecated />

  Equivalent to `row`.

- `horizontal-reverse` <Deprecated />

  Equivalent to `row-reverse`.

- `vertical-reverse` <Deprecated />

  Equivalent to `column-reverse`.

## Formal definition

| Initial value | column |
| Applies to | linear containers |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
linear-direction = column | row | column-reverse | row-reverse
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-direction`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets how linear items are placed in the linear container defining the main axis and the direction.




---
url: /api/css/properties/linear-gravity.md
---

#Deprecated linear-gravity
APISummary
:::warning
This API is deprecated.
:::

## Introduction

The CSS `linear-gravity` property defines how distributes space between and around content items along the main-axis of a [linear](/guide/ui/layout/linear-layout.md) container. Similar to [flexible box layout](/guide/ui/layout/flexible-box-layout.md) [`justify-content`](/api/css/properties/justify-content.md).

:::info
When using `justify-content` and `linear-gravity` both, `linear-gravity` will override `justify-content`.
:::

## Examples

**This is an example below: css-api**

**Entry:** `src/linear-gravity`
**Bundle:** `dist/linear-gravity.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const LinearGravity = () => {
  const [linearDirection, setLinearDirection] = useState(false);
  const container1Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "none" as const,
  };
  const container2Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "start" as const,
  };
  const container3Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "end" as const,
  };
  const container4Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "center" as const,
  };
  const container5Style = {
    linearDirection: linearDirection ? "row" : "column" as "row" | "column",
    linearGravity: "space-between" as const,
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const view1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearDirection(!linearDirection)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearDirection ? "row" : "column"}"</text>
      <text className="title">linear-gravity:none;(default)</text>
      <view className="linear_container" style={container1Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:start;</text>
      <view className="linear_container" style={container2Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:end;</text>
      <view className="linear_container" style={container3Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:center;</text>
      <view className="linear_container" style={container4Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-gravity:space-between;</text>
      <view className="linear_container" style={container5Style}>
        <view style={view1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearGravity />);

```



## Syntax

```css
linear-gravity: none;
linear-gravity: start;
linear-gravity: end;
linear-gravity: center;
linear-gravity: space-between;
```

### Values

- `none`

  **Default value**. It is equivalent to `start`.

- `start`

  Align the beginning of the parent element main axis.

- `end`

  Align the end of the parent element main axis.

- `center`

  Align the center of the parent element's main axis.

- `space-between`

In the corresponding layout direction, the two ends are aligned and the middle interval is equal.

- `top` <Deprecated />

  Not recommended, it is recommended to use `start`. Align up, vertical layout takes effect.

- `bottom` <Deprecated />

  Not recommended, it is recommended to use `end`. Align down, vertical layout takes effect.

- `left` <Deprecated />

  Not recommended, it is recommended to use `start`. Align left, horizontal layout takes effect.

- `right` <Deprecated />

  Not recommended, it is recommended to use `end`. Align right, horizontal layout takes effect.

- `center-vertical` <Deprecated />

  Not recommended, it is recommended to use `center`. Centered vertically, vertical layout takes effect.

- `center-horizontal` <Deprecated />

  Not recommended, it is recommended to use `center`. Centered horizontally, horizontal layout takes effect.

## Formal definition

| Initial value | none |
| Applies to | linear containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
linear-gravity = none | start | end | center | space-between
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** defines how distributes space between and around content items along the main-axis of a linear container.




---
url: /api/css/properties/linear-layout-gravity.md
---

#Deprecated linear-layout-gravity
APISummary
:::warning
This API is deprecated.
:::

## Introduction

The position of the child element in the linear container, perpendicular to the layout direction, is a property of the child element's layout, similar to [`align-self`](/api/css/properties/align-self.md) in flexible box layout.

When using [`linear-layout-gravity`](/api/css/properties/linear-layout-gravity.md), [`align-self`](/api/css/properties/align-self.md), [`linear-cross-gravity`](/api/css/properties/linear-cross-gravity.md), and [`align-items`](/api/css/properties/align-items.md) simultaneously in a linear layout, the priority decreases from the first to the last. A higher-priority style will override a lower-priority style.

## Examples

**This is an example below: css-api**

**Entry:** `src/linear-layout-gravity`
**Bundle:** `dist/linear-layout-gravity.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const LinearLayoutGravity = () => {
  const [linearOrientation, setLinearOrientation] = useState(false);
  const containerStyle = {
    linearOrientation: linearOrientation ? "horizontal" : "vertical" as "horizontal" | "vertical",
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const Container1View1Style = {
    width: "20px",
    height: "20px",
    linearLayoutGravity: "none" as const,
    backgroundColor: "red" as const,
  };
  const Container2View1Style = {
    width: "20px",
    height: "20px",
    linearLayoutGravity: "start" as const,
    backgroundColor: "red" as const,
  };
  const Container3View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "end" as const,
  };
  const Container4View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "center" as const,
  };
  const Container5View1Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "red" as const,
    linearLayoutGravity: "stretch" as const,
  };
  const view2Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "yellow" as const,
  };
  const view3Style = {
    width: "20px",
    height: "20px",
    backgroundColor: "green" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearOrientation(!linearOrientation)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearOrientation ? "row" : "column"}"</text>
      <text className="title">linear-layout-gravity:none;(default)</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container1View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:start;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container2View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:end;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container3View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:center;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container4View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
      <text className="title">linear-layout-gravity:stretch;</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container5View1Style}></view>
        <view style={view2Style}></view>
        <view style={view3Style}></view>
      </view>
    </scroll-view>
  );
};

root.render(<LinearLayoutGravity />);

```



## Syntax

```css
linear-layout-gravity: none;
linear-layout-gravity: stretch;
linear-layout-gravity: start;
linear-layout-gravity: end;
linear-layout-gravity: center;
```

### Values

- `none`

  **Default value**。When the size of the parent element cross axis size(such as the [`width`](/api/css/properties/width.md) when [`linear-direction: column`](/api/css/properties/linear-direction.md)) is fixed, and the size of the child element in this direction is auto, `none` will be equivalent to `fill-horizontal` or `fill-vertical`. In other cases it is equivalent to `left` or `top`.

- `stretch`

  Fill the container's cross axis.

- `start`

  Align the beginning of the parent element's cross axis.

- `end`

  Align the end of the parent element's cross axis.

- `center`

  Align the center of the parent element's cross axis.

- `top` <Deprecated />

  Align the top of the parent element, the horizontal layout takes effect.

- `bottom` <Deprecated />

  Align the bottom of the parent element, the horizontal layout takes effect.

- `left` <Deprecated />

  Align the left side of the parent element, vertical layout takes effect.

- `right` <Deprecated />

  Align the right side of the parent element, vertical layout takes effect.

- `center-vertical` <Deprecated />

  Centered in the vertical direction, the horizontal layout of the parent element takes effect.

- `center-horizontal` <Deprecated />

  Centered in the horizontal direction, the vertical layout of the parent element takes effect.

- `fill-vertical` <Deprecated />

  Fill the entire container vertically, and the horizontal layout of the parent element takes effect.

- `fill-horizontal` <Deprecated />

  Fill up the container horizontally, and the vertical layout of the parent element takes effect.

## Formal definition

| Initial value | none |
| Applies to | linear items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
linear-layout-gravity = none | stretch | start | end | center
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-layout-gravity`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** The position of the child element in the linear container, perpendicular to the layout direction.


## FAQ

- `None` and `top`/`left` in `linear-layout-gravity` are not the same. The specific differences are as follows:

- When the parent's non-layout orientation is fixed size, none behaves the same as `fill-vertical`/`fill-horizontal`, i.e., fills the parent's non-layout orientation.
  `None` behaves the same as `top`/`right` when the parent's non-layout orientation is not a fixed size.



---
url: /api/css/properties/linear-weight-sum.md
---

#Deprecated linear-weight-sum
APISummary
:::warning
This API is deprecated.
:::

## Introduction

Child element's weight sum in [linear](/guide/ui/layout/linear-layout.md).

When `linear-weight-sum` property of the [linear](/guide/ui/layout/linear-layout.md) view is non-zero.

- The linear-layout first lays out all the child elements whose [`linear-weight:0`](/api/css/properties/linear-weight.md), and calculates the width of these child elements in the layout direction.
- The remaining `linear-weight` non-zero child elements will be allocated the remaining width(linear layout view width minus the width of all `linear-weight:0` child elements) in the main axis according to their `linear-weight`. For ease of presentation, we view "the sum of the children `linear-weight` " as symbol "S".
  - When `linear-weight-sum` \<= S:

    main size of child = corresponding linear-weight ÷ S ✖️ remaining main size width

  - When `linear-weight-sum` > S:

    main size of child = corresponding linear-weight ÷ linear-weight-sum ✖️ remaining main size width

:::tip
1.linear container's main axis size need set a fixed value;

2.It is not supported to use a fixed value and weight at the same time. If there is a `linear-weight`, the fixed value is automatically ignored (performance first);
:::

## Examples

In the figure, the width of the parent element is 400px, the first element is fixed at 100px, and the remaining width is 300px. The second and third elements specify the size, and are allocated according to the weight. The second element is 200px wide and the third element is 100px wide.

**This is an example below: css-api**

**Entry:** `src/linear-weight-sum`
**Bundle:** `dist/linear-weight-sum.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const LinearWeightSum = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "column" as const,
    height: "400px",
    linearWeightSum: "3",
    marginTop: "30px",
  };

  const textStyle = {
    fontSize: "40rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const text2Style = {
    fontSize: "40rpx" as const,
    fontWeight: "800" as const,
  };

  const redBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "red",
    height: "100px",
  };

  const yellowBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "yellow",
    linearWeight: 2,
  };

  const greenBoxStyle = {
    width: "100%",
    alignItems: "center" as const,
    justifyContent: "center" as const,
    backgroundColor: "green",
    linearWeight: 1,
  };

  return (
    <>
      <text style={textStyle}>linear-weight-sum: 3</text>
      <text style={textStyle}>height: 400px</text>
      <view style={containerStyle}>
        <view style={redBoxStyle}>
          <text style={text2Style}>height: 100px</text>
        </view>
        <view style={yellowBoxStyle}>
          <text style={text2Style}>linear-weight: 2</text>
        </view>
        <view style={greenBoxStyle}>
          <text style={text2Style}>linear-weight: 1</text>
        </view>
      </view>
    </>
  );
};

root.render(<LinearWeightSum />);

```



## Syntax

```css
linear-weight-sum: 2;
linear-weight-sum: 5.5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. **Default value is 0**.

## Formal definition

| Initial value | 0 |
| Applies to | linear containers |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
linear-weight-sum = <number>
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-weight-sum`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | Do not support this property on the inline style; ⚠️ Partial implementation |

**Description:** Child element's weight sum in linear layout.


## FAQ

- linear container's main axis size need set a fixed value;

- It is not supported to use a fixed value and weight at the same time. If there is a linear-weight, the fixed value is automatically ignored (performance first);



---
url: /api/css/properties/linear-weight.md
---

# linear-weight

APISummary
## Introduction

Child element's weight in [linear](/guide/ui/layout/linear-layout.md).
The parent container automatically allocates the length of the corresponding side of the child elements according to the weight value ratio of all child elements and the size of the remaining space.

## Examples

**This is an example below: css-api**

**Entry:** `src/linear-weight`
**Bundle:** `dist/linear-weight.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const LinearWeight = () => {
  const [linearOrientation, setLinearOrientation] = useState(false);
  const containerStyle = {
    linearOrientation: linearOrientation ? "horizontal" : "vertical" as "horizontal" | "vertical",
  };
  const buttonStyle = {
    width: "20%",
    height: "50px",
    backgroundColor: "red" as const,
  };
  const text1Style = {
    fontSize: "40rpx" as const,
    marginRight: "12rpx",
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };
  const text2Style = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg,#0095ff 30%,#42d392 100%)" as const,
  };
  const Container1View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "red" as const,
  };
  const Container1View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 2,
    backgroundColor: "yellow" as const,
  };
  const Container1View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "blue" as const,
  };

  const Container2View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "red" as const,
  };
  const Container2View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "yellow" as const,
  };
  const Container2View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 1,
    backgroundColor: "blue" as const,
  };

  const Container3View1Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "red" as const,
  };
  const Container3View2Style = {
    width: "30px",
    height: "30px",
    linearWeight: 0.5,
    backgroundColor: "yellow" as const,
  };
  const Container3View3Style = {
    width: "30px",
    height: "30px",
    linearWeight: 2,
    backgroundColor: "blue" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={buttonStyle} bindtap={() => setLinearOrientation(!linearOrientation)}></view>
      <text style={text1Style}>Click above red button to switch linear-direction</text>
      <text style={text2Style}>Current: "{linearOrientation ? "row" : "column"}"</text>
      <text className="title">linear-weight: 0.5 2 0.5</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container1View1Style} />
        <view style={Container1View2Style} />
        <view style={Container1View3Style} />
      </view>

      <text className="title">linear-weight: 1 1 1</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container2View1Style} />
        <view style={Container2View2Style} />
        <view style={Container2View3Style} />
      </view>

      <text className="title">linear-weight: 0.5 0.5 2</text>
      <view className="linear_container" style={containerStyle}>
        <view style={Container3View1Style} />
        <view style={Container3View2Style} />
        <view style={Container3View3Style} />
      </view>
    </scroll-view>
  );
};

root.render(<LinearWeight />);

```



## Syntax

```css
linear-weight: 3;
linear-weight: 5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

  Negative values are invalid. **Default value is 0**. When the linear-weight of a sub-element in linear layout is 0, the layout of the child element will not be affected by the linear-weight.

## Formal definition

| Initial value | `0` |
| Applies to | linear items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
linear-weight = <number>
```

## Difference between web

- No such style in Web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.linear-weight`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** Child element's weight in linear layout.


## FAQ

- It is not supported to use a fixed value and weight at the same time. If there is a `weight`, the fixed value is automatically ignored (performance first).



---
url: /api/css/properties/margin-bottom.md
---

# margin-bottom

APISummary
## Introduction

The `margin-bottom` CSS property sets the margin area on the bottom of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-bottom`
**Bundle:** `dist/margin-bottom.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MarginBottom = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginTop: "10px",
            marginBottom: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginBottom />);

```



## Syntax

```css
/* <length> values */
margin-bottom: 0.5em;
margin-bottom: 0;
margin-bottom: 2rpx;

/* <percentage> value */
margin-bottom: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal Definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-bottom =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-bottom](https://developer.mozilla.org/en/docs/Web/CSS/margin-bottom)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | ✅ Yes | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-inline-end.md
---

# margin-inline-end

APISummary
## Introduction

The `margin-inline-end` CSS property defines the logical inline end margin of an element.

In `LTR` direction, it corresponds to the [`margin-right`](/api/css/properties/margin-right.md) property.
In `RTL` direction, it corresponds to the [`margin-left`](/api/css/properties/margin-left.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-inline-end`
**Bundle:** `dist/margin-inline-end.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const MarginInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    marginInlineStart: "10px",
    marginInlineEnd: "50px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={introStyle}>1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<MarginInlineEnd />);

```



## Syntax

```css
/* <length> values */
margin-inline-end: 0.5em;
margin-inline-end: 0px;
margin-inline-end: 2rpx;

/* <percentage> value */
margin-inline-end: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value, can be positive, zero, or negative.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block). It can be positive, zero, or negative.

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-inline-end =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-inline-end](https://developer.mozilla.org/en/docs/Web/CSS/margin-inline-end)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
3. Lynx does not support writing mode.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-inline-start.md
---

# margin-inline-start

APISummary
## Introduction

The `margin-inline-start` CSS property defines the logical inline start margin of an element.

In `LTR` direction, it corresponds to the [`margin-left`](/api/css/properties/margin-left.md) property.
In `RTL` direction, it corresponds to the [`margin-right`](/api/css/properties/margin-right.md) property.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-inline-start`
**Bundle:** `dist/margin-inline-start.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const MarginInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
  };

  const introStyle = {
    marginInlineStart: "50px",
    marginInlineEnd: "10px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro" style={introStyle}>1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<MarginInlineStart />);

```



## Syntax

```css
/* <length> values */
margin-inline-start: 0.5em;
margin-inline-start: 0px;
margin-inline-start: 2rpx;

/* <percentage> value */
margin-inline-start: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value, can be positive, zero, or negative.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-inline-start =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-inline-start](https://developer.mozilla.org/en/docs/Web/CSS/margin-inline-start)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
3. Lynx does not support writing mode.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-left.md
---

# margin-left

APISummary
## Introduction

The `margin-left` CSS property sets the margin area on the left of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-left`
**Bundle:** `dist/margin-left.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MarginLeft = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  const fixedAreaStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginLeft: "10px",
            marginRight: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginLeft />);

```



## Syntax

```css
/* <length> values */
margin-left: 0.5em;
margin-left: 0;
margin-left: 2rpx;

/* <percentage> value */
margin-left: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-left =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-left](https://developer.mozilla.org/en/docs/Web/CSS/margin-left)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-right.md
---

# margin-right

APISummary
## Introduction

The `margin-right` CSS property sets the margin area on the right of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-right`
**Bundle:** `dist/margin-right.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MarginRight = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginLeft: "10px",
            marginRight: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginRight />);

```



## Syntax

```css
/* <length> values */
margin-right: 0.5em;
margin-right: 0;
margin-right: 2rpx;

/* <percentage> value */
margin-right: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-right =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-right](https://developer.mozilla.org/en/docs/Web/CSS/margin-right)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin-top.md
---

# margin-top

APISummary
## Introduction

The `margin-top` CSS property sets the margin area on the top of an element. A positive value places it farther from its neighbors, while a negative value places it closer.

## Examples

**This is an example below: css-api**

**Entry:** `src/margin-top`
**Bundle:** `dist/margin-top.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MarginTop = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text
          className="intro"
          style={{
            marginTop: "10px",
            marginBottom: "30px",
          }}
        >
          1
        </text>
        <text className="intro2">
          2
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<MarginTop />);

```



## Syntax

```css
/* <length> values */
margin-top: 0.5em;
margin-top: 0;
margin-top: 2rpx;

/* <percentage> value */
margin-top: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin-top =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin-top](https://developer.mozilla.org/en/docs/Web/CSS/margin-top)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/margin.md
---

# margin

APISummary
## Introduction

The margin CSS shorthand property sets the margin area on all four sides of an element.

This property is a shorthand for the following CSS properties: [margin-top](/api/css/properties/margin-top.md), [margin-right](/api/css/properties/margin-right.md), [margin-bottom](/api/css/properties/margin-bottom.md), [margin-left](/api/css/properties/margin-left.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/margin`
**Bundle:** `dist/margin.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Margin = () => {
  const scrollViewStyle = {
    height: "100%",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <text className="intro" style={{ margin: "20px" }}>
          margin: 20px; All sides
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 5px" }}>
          margin: 20px 5px; Top/Bottom | Left/Right
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 15px 10px" }}>
          margin: 20px 15px 10px; Top | Left/Right | Bottom
        </text>
      </view>

      <view className="con">
        <text className="intro" style={{ margin: "20px 15px 10px 5px" }}>
          margin: 20px 15px 10px 5px; Top | Right | Bottom | Left
        </text>
      </view>
    </scroll-view>
  );
};

root.render(<Margin />);

```



## Syntax

```css
/* Apply to all four sides */
margin: 1em;
margin: -3px;

/* top and bottom | left and right */
margin: 5% auto;

/* top | left and right | bottom */
margin: 1em auto 2em;

/* top | right | bottom | left */
margin: 2px 1em 0 auto;
```

The margin property may be specified using one, two, three, or four values. Each value is a [`<length>`](/api/css/data-type/length.md), a [`<percentage>`](/api/css/data-type/percentage.md), or the keyword `auto`. Negative values draw the element closer to its neighbors than it would be by default.

- When one value is specified, it applies the same margin to all four sides.

- When two values are specified, the first margin applies to the top and bottom, the second to the left and right.

- When three values are specified, the first margin applies to the top, the second to the right and left, the third to the bottom.

- When four values are specified, the margins apply to the top, right, bottom, and left in that order (clockwise).

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the margin as a fixed value.

#### `<percentage>`

The size of the margin as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

#### `auto`

Selects a suitable margin to use. For example, in certain cases this value can be used to center an element.

:::info
Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md).

Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.
:::

## Formal definition

| Initial value | as each of the properties of the shorthand: 
-  margin-bottom: 0
- margin-left: 0
- margin-right: 0
- margin-top: 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
margin =
  <length-percentage>  |
  auto                 |

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn: margin](https://developer.mozilla.org/en/docs/Web/CSS/margin)

1. In Lynx, margins will not collapse at any time.
2. Currently, Lynx supports using `auto` in flex, grid and [linear](/guide/ui/layout/linear-layout.md) children that are not with [`position:fixed/absolute/sticky`](/api/css/properties/position.md). Additionally, in linear layout, it only supports using `auto` on the cross axis. We plan to support using `auto` on the main axis in the future.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.margin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/margin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/mask-image.md
---

# mask-image

APISummary
## Introduction

The `mask-image
` CSS property sets the image that is used as mask layer for an element.
By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element.
## Syntax

```css
/* Keyword value */
mask-image: none;

/* <image> values */
mask-image: linear-gradient(rgba(0, 0, 0, 1), transparent);
mask-image: url(mask.png);

/* Multiple values */
mask-image: url(mask.png), linear-gradient(rgba(0, 0, 0, 1), transparent);
```

### Values

#### `none`

This keyword is interpreted as an opaque white image layer.

#### `<image>`

An image value used as mask image layer.

### Formal Definition

| Initial value | none |
| Applies to | `view` only |
| Inherited | no |
| Animatable |  |


## Formal Syntax

```
mask-image =
  <mask-reference>#

<mask-reference> =
  none       |
  <image>

<image> =
  <url()>    |
  <gradient>

<url()> =
  url( <string> )
```

## Difference with the Web

1. SVG element is not supported. Only bitmap url or gradient is supported.
2. image() function is not supported.
3. `<url()>` supports `url()` function only.
4. global value are not supported (e.g. inherit, unset, init and etc).

## Compatibility

**Compatibility Table**
**Query:** `css.properties.mask-image`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask-image](https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask-image)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | src(), image() functions and svg elements reference are not supported; ⚠️ Partial implementation |
| iOS | 2.13 | src(), image() functions and svg elements reference are not supported; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** The mask-image CSS property sets the image that is used as mask layer for an element. By default this means the alpha channel of the mask image will be multiplied with the alpha channel of the element. This can be controlled with the mask-mode property.




---
url: /api/css/properties/mask.md
---

# mask

APISummary
## Introduction

The `mask` CSS shorthand property hides an element (partially or fully) by masking or clipping the image at specific points.

## Constituent properties

This property is a shorthand for the following CSS properties:

- mask-clip
- mask-image
- mask-origin
- mask-position
- mask-repeat
- mask-size

## Syntax

```css
/* Keyword values */
mask: none;

/* Image values */
mask: url(mask.png); /* Pixel image used as mask */

/* Combined values */
mask: url(mask.png) 40px 20px; /* Pixel image used as mask positioned 40px from the top and 20px from the left */
mask: url(mask.png) 0 0/50px 50px; /* Pixel image used as mask with a width and height of 50px */
mask: url(mask.png) repeat-x; /* Pixel image used as horizontally repeated mask */
mask: url(mask.png) stroke-box; /* Pixel image used as mask extending to the box enclosed by the stroke */

/* Multiple masks */
mask:
  url(masks.png) left / 16px repeat-y,
  /* Pixel image is used as a mask on the left-hand side with a width of 16px */
  url(masks.png) right / 16px repeat-y; /* Pixel image is used as a mask on the right-hand side with a width of 16px */
```

### Values

#### `<mask-reference>`

Sets the mask image source. See [mask-image](/api/css/properties/mask-image.md).

#### `<position>`

Sets the position of the mask image. See [mask-position](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-position).

#### `<bg-size>`

Sets the size of the mask image. See [mask-size](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-size).

#### `<repeat-style>`

Sets the repetition of the mask image. See [mask-repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-repeat).

#### `<geometry-box>`

If only one `<geometry-box` value is given, it sets both [mask-origin](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-origin) and [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip). If two `<geometry-box>` values are present, then the first sets mask-origin and the second sets [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip).

#### `<geometry-box> | no-clip`

Sets the area that is affected by the mask image. See [mask-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/mask-clip).

## Formal definition

|                              |                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Initial values**           | as each of the properties of the shorthand: <br /> <ul style={{ listStyleType: "disc", paddingLeft: "1.5rem" }}> <li> [mask-image](/api/css/properties/mask-image.md): none</li> <li>mask-repeat: repeat</li><li>mask-position: center</li><li>mask-clip: border-box</li><li>mask-origin: border-box</li><li>mask-size: auto</li></ul> |
| **Applies to**               | Views only. It may work on some other elements, but it is recommended that only use it on <code>\<view></code>                                                                                                                                                                                                                         |
| **Inherited**                | No                                                                                                                                                                                                                                                                                                                                     |
| **Percentages**              | as each of the properties of the shorthand: <br /> <ul style={{ listStyleType:"disc", paddingLeft: "1.5rem"}}><li> mask-position: refer to size of mask painting area minus size of mask layer image (see the text for background-position)</li></ul>                                                                                  |
| **Creates stacking context** | yes                                                                                                                                                                                                                                                                                                                                    |

## Formal Syntax

```
mask =
  <mask-layer>#

<mask-layer> =
  <mask-reference>               ||
  <position> [ / <bg-size> ]?    ||
  <repeat-style>                 ||
  <box>                          ||
  <compositing-operator>         ||
  <masking-mode>

<mask-reference> =
  none       |
  <image>

<image> =
  <url()>   |
  <gradient>

<url()> =
  url( <string> )

<position> =
  [ left | center | right ] && [ top | center | bottom ]            |
  [ left | center | right | <length-percentage> ]
    [ top | center | bottom | <length-percentage> ]?                |
  [ [ left | right ] <length-percentage> ] &&
    [ [ top | bottom ] <length-percentage> ]

<bg-size> =
  [ <length-percentage> | auto ]{1,2}  |
  cover                                |
  contain

<repeat-style> =
  repeat-x                             |
  repeat-y                             |
  [ repeat | space | round | no-repeat ]{1,2}

<box> =
  border-box     |
  padding-box    |
  content-box

<compositing-operator> =
  add        |
  subtract   |
  intersect  |
  exclude

<masking-mode> =
  alpha         |
  luminance     |
  match-source

<length-percentage> =
  <length>      |
  <percentage>

```

## Difference with the Web

1. `mask-type` not supported in Lynx.
2. `mask-image` not support [SVG]() reference.
3. only support border-box, padding-box and content-box.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.mask`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask](https://developer.mozilla.org/zh-CN/docs/Web/CSS/mask)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | mask-type, mask-composite are not supported; ⚠️ Partial implementation |
| iOS | 2.13 | mask-type, mask-composite are not supported; ⚠️ Partial implementation |
| HarmonyOS | ❌ No | - |
| Clay Android | 3.4 | - |
| Clay iOS | 3.4 | - |
| Clay macOS | 3.4 | - |
| Clay Windows | 3.4 | - |
| Web | ✅ Yes | - |

**Description:** The mask CSS shorthand property hides an element (partially or fully) by masking or clipping the image at specific points.




---
url: /api/css/properties/max-height.md
---

# max-height

APISummary
## Introduction

To specify max height of a view. It prevents the applied value of [`height`](/api/css/properties/height.md) becoming larger than the specified value of `max-height`.
The priority of `max-height` is higher than [`height`](/api/css/properties/height.md) and [`min-height`](/api/css/properties/min-height.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/max-height`
**Bundle:** `dist/max-height.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MaxHeight = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "row" as const,
  };

  const firstBoxStyle = {
    height: "300px",
    backgroundColor: "green",
    width: "100px",
  };

  const secondBoxStyle = {
    height: "400px",
    backgroundColor: "yellow",
    width: "100px",
    maxHeight: "300px",
  };

  const thirdBoxStyle = {
    height: "300px",
    backgroundColor: "blue",
    width: "100px",
    minHeight: "400px",
    maxHeight: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>height: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>height: 400px; max-height: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>height: 300px; min-height: 400px; max-height: 200px</text>
      </view>
    </view>
  );
};

root.render(<MaxHeight />);

```



## Syntax

```css
/* <length> */
max-height: 120px;
max-height: 10em;

/* <percentage> */
max-height: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) Defines the max-height as an absolute value.

#### `<percentage>`

Defines the `max-height` as a percentage of the containing block's height.

## Formal definition

| Initial value | no limit |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | The percentage is calculated with respect to the height of the generated box's containing block |


## Formal syntax

```css
/* <length> */
max-height: 120px;
max-height: 10em;

/* <percentage> */
max-height: 75%;
```

## Difference with the Web

[mdn:max-height](https://developer.mozilla.org/en-US/docs/Web/CSS/max-height)

1. In Lynx, the priority of `max-height` is higher than `height` and `min-height`. While in Web, `max-height` overrides `height`, but `min-height` overrides `max-height`.
2. In Lynx, if `max-height` is specified smaller than `min-height`, `min-height` will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.max-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the maximum height of an element.




---
url: /api/css/properties/max-width.md
---

# max-width

APISummary
## Introduction

To specify max width of a view. It prevents the applied value of [`width`](/api/css/properties/width.md) becoming larger than the specified value of `max-width`.
The priority of `max-width` is higher than [`width`](/api/css/properties/width.md) and [`min-width`](/api/css/properties/min-width.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/max-width`
**Bundle:** `dist/max-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MaxWidth = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const firstBoxStyle = {
    width: "300px",
    backgroundColor: "green",
  };

  const secondBoxStyle = {
    width: "300px",
    backgroundColor: "yellow",
    maxWidth: "300px",
  };

  const thirdBoxStyle = {
    width: "300px",
    backgroundColor: "blue",
    minWidth: "400px",
    maxWidth: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>width: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>width: 400px; max-width: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>width: 300px; min-width: 400px; max-width: 200px</text>
      </view>
    </view>
  );
};

root.render(<MaxWidth />);

```



## Syntax

```css
/* <length> */
max-width: 120px;
max-width: 10em;

/* <percentage> */
max-width: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the max-width as an absolute value.

#### `<percentage>`

Defines the max-width as a percentage of the containing block's width.

## Formal definition

| Initial value | no limit |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
max-width = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:max-width](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width)

1. In Lynx, the priority of `max-width` is higher than `width` and `min-width`. While in Web, `max-width` overrides `width`, but `min-width` overrides `max-width`.
2. In Lynx, if `max-width` is specified smaller than `min-width`, `min-width` will be ignored.
3. `none`, `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.max-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/max-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the maximum width of an element.




---
url: /api/css/properties/min-height.md
---

# min-height

APISummary
## Introduction

To specify min height of a view. It prevents the applied value of [`height`](/api/css/properties/height.md) becoming larger than the specified value of `min-height`.
The priority of `min-height` is higher than [`height`](/api/css/properties/height.md) but lower than [`max-height`](/api/css/properties/max-height.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/min-height`
**Bundle:** `dist/min-height.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MinHeight = () => {
  const containerStyle = {
    display: "linear" as const,
    linearDirection: "row" as const,
  };

  const firstBoxStyle = {
    height: "300px",
    backgroundColor: "green",
    width: "100px",
  };

  const secondBoxStyle = {
    height: "0px",
    backgroundColor: "yellow",
    width: "100px",
    minHeight: "300px",
  };

  const thirdBoxStyle = {
    height: "0px",
    backgroundColor: "blue",
    width: "100px",
    minHeight: "300px",
    maxHeight: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>height: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>height: 0px; min-height: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>height: 0px; min-height: 300px; max-height: 200px</text>
      </view>
    </view>
  );
};

root.render(<MinHeight />);

```



## Syntax

```css
/* <length> */
min-height: 120px;
min-height: 10em;

/* <percentage> */
min-height: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the min-height as an absolute value. Default to `0px`.

#### `<percentage>`

Defines the `min-height` as a percentage of the containing block's height.

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | The percentage is calculated with respect to the height of the generated box's containing block |


## Formal syntax

```
min-height = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:min-height](https://developer.mozilla.org/en-US/docs/Web/CSS/min-height)

1. In Lynx, the priority of `max-height` is higher than `height` and `min-height`. While in Web, `max-height` overrides `height`, but `min-height` overrides `max-height`.
2. If `max-height` is specified smaller than `min-height`, `min-height` will be ignored.
3. `auto` is not supported, default value is `0px`.
4. `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.min-height`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-height](https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-height)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the minimum height of an element.




---
url: /api/css/properties/min-width.md
---

# min-width

APISummary
## Introduction

To specify min width of a view. It prevents the applied value of [`width`](/api/css/properties/width.md) becoming larger than the specified value of `min-width`.
The priority of `min-width` is higher than [`width`](/api/css/properties/width.md) but lower than [`max-width`](/api/css/properties/max-width.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/min-width`
**Bundle:** `dist/min-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const MinWidth = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const firstBoxStyle = {
    width: "300px",
    backgroundColor: "green",
  };

  const secondBoxStyle = {
    width: "0px",
    backgroundColor: "yellow",
    minWidth: "300px",
  };

  const thirdBoxStyle = {
    width: "0px",
    backgroundColor: "blue",
    minWidth: "300px",
    maxWidth: "200px",
  };

  return (
    <view className="intro" style={containerStyle}>
      <view style={firstBoxStyle}>
        <text>width: 300px</text>
      </view>
      <view style={secondBoxStyle}>
        <text>width: 0px; min-width: 300px</text>
      </view>
      <view style={thirdBoxStyle}>
        <text>width: 0px; min-width: 300px; max-width: 200px</text>
      </view>
    </view>
  );
};

root.render(<MinWidth />);

```



## Syntax

```css
/* <length> */
min-width: 120px;
min-width: 10em;

/* <percentage> */
min-width: 75%;
```

### Values

#### `<length>`

[`<length>`](/api/css/data-type/length.md) defines the min-width as an absolute value. Default to `0px`.

#### `<percentage>`

Defines the min-width as a percentage of the containing block's width.

## Formal definition

| Initial value | 0px |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
min-width = <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

[mdn:min-width](https://developer.mozilla.org/en-US/docs/Web/CSS/min-width)

1. In Lynx, the priority of `max-width` is higher than `width` and `min-width`. While in Web, `max-width` overrides `width`, but `min-width` overrides `max-width`.
2. If `max-width` is specified smaller than `min-width`, `min-width` will be ignored.
3. `auto` is not supported, default value is `0px`.
4. `max-content`, `min-content`, `fit-content`, `min-content` are not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.min-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/min-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** sets the minimum width of an element.




---
url: /api/css/properties/opacity.md
---

# opacity

APISummary
## Introduction

The opacity CSS property sets the opacity of an element. Opacity is the degree to which content behind an element is hidden, and is the opposite of transparency.

Opacity applies to the element as a whole, including its contents, even though the value is not inherited by child elements.
Thus, the element and its children all have the same opacity relative to the element's background, even if they have different opacities relative to one another.

:::caution
The group opacity on Android is true by default, while on iOS is false. Use `overlap` and `overlap-ios` to define how opacity affects the background and contents of the view.

Group opacity will force the system to use off-screen rendering to render the view, which has performance issues on both Android and iOS.
And, on Android, the `overflow: visible` will lose effect.
:::

## Examples

**This is an example below: css-api**

**Entry:** `src/opacity`
**Bundle:** `dist/opacity.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

import image from "../../resource/lynx.png";

const Opacity = () => {
  const heightStyle = {
    height: "10px",
  };

  const opacity1Style = {
    opacity: 1,
  };

  const opacity05Style = {
    opacity: 0.5,
  };

  const opacity0Style = {
    opacity: 0,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <image className="relative_image" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity1Style} src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity05Style} src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image" style={opacity0Style} src={image}></image>
      </view>
    </scroll-view>
  );
};

root.render(<Opacity />);

```



## Syntax

```css
opacity: 1;
opacity: 0.5;
opacity: 0;
```

### Values

A \<number> in the range `0.0` to `1.0`, inclusive, or a \<percentage> in the range `0%` to `100%`, inclusive, representing the opacity of the channel
(that is, the value of its alpha channel). Any value outside the interval, though valid, is clamped to the nearest limit in the range.

|                  Value                 |                                    Meaning                                    |
| :------------------------------------: | :---------------------------------------------------------------------------: |
|                    0                   |             The element is fully transparent (that is, invisible).            |
| Any \<number> strictly between 0 and 1 | The element is translucent (that is, content behind the element can be seen). |
|                    1                   |                 The element is fully opaque (visually solid).                 |

## Formal definition

| Initial value | 1 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

opacity: `<number>`;

## Difference from Web

Opacity will affect the background and contents as a whole. For Lynx iOS should set `overlap-ios={true}`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.opacity`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/opacity](https://developer.mozilla.org/zh-CN/docs/Web/CSS/opacity)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/order.md
---

# order

APISummary
## Introduction

The `order` CSS property sets the order to lay out an item in container. Items in a container are sorted by ascending order value and then by their source code order. Items not given an explicit order value are assigned the default value of `0`.

## Examples

**This is an example below: css-api**

**Entry:** `src/order`
**Bundle:** `dist/order.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Order = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const getOrderStyle = (order: number) => ({
    order: order,
  });

  return (
    <view className="intro" style={containerStyle}>
      <text className="intro-item" style={getOrderStyle(1)}>order: 1</text>
      <text className="intro-item" style={getOrderStyle(3)}>order: 3</text>
      <text className="intro-item" style={getOrderStyle(2)}>first order: 2</text>
      <text className="intro-item" style={getOrderStyle(2)}>second order: 2</text>
    </view>
  );
};

root.render(<Order />);

```



## Syntax

```css
/* Numerical value including negative numbers */
order: 5;
order: -5;
```

### Values

- [`<number>`](/api/css/data-type/number.md)

Represents the ordinal group to be used by the item. Default value is `0`.

## Formal definition

| Initial value | 0 |
| Applies to | child element with[`position: relative`](/api/css/properties/position) |
| Inherited | no |
| Animatable | no |


## Difference with the Web

1. It is not supported to use on [`position: absolute/fixed/sticky`](/api/css/properties/position.md) flex and grid container children.
2. Using `order` will not influence the element's painting order in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.order`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/order](https://developer.mozilla.org/zh-CN/docs/Web/CSS/order)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** The order CSS property sets the order to lay out an item.




---
url: /api/css/properties/overflow-x.md
---

# overflow-x

APISummary
## Introduction

The overflow-x property specifies whether to clip the content when it overflows at the left and right edges.

## Examples

**This is an example below: css-api**

**Entry:** `src/overflow-x`
**Bundle:** `dist/overflow-x.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const OverflowX = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<OverflowX />);

```



## Syntax

```css
overflow-x: visible;
overflow-x: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the left and right edges.

- `hidden` the overflow of the content and the descendants will be clipped at the left and right edges.

## Formal definition

| Initial value | visible |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow-x :visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow-x`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-x](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-x)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/overflow-y.md
---

# overflow-y

APISummary
## Introduction

The overflow-y property specifies whether to clip the content when it overflows at the top and bottom edges.

## Examples

**This is an example below: css-api**

**Entry:** `src/overflow-y`
**Bundle:** `dist/overflow-y.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const OverflowY = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<OverflowY />);

```



## Syntax

```css
overflow-y: visible;
overflow-y: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the top and bottom edges.

- `hidden` the overflow of the content and the descendants will be clipped at the top and bottom edges.

## Formal definition

| Initial value | visible |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow-y: visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow-y`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-y](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow-y)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/overflow.md
---

# overflow

APISummary
## Introduction

The overflow property specifies whether to clip the content when the content of an element is too big.

:::caution

- It's recommended to set `overflow: hidden` explicitly, if the node is not need to be overflow; On Android platform, the re-drawn region may become larger than view‘s rect when `overflow: visible`.

:::

## Examples

**This is an example below: css-api**

**Entry:** `src/overflow`
**Bundle:** `dist/overflow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Overflow = () => {
  const containerStyle = {
    height: "500px",
    flexDirection: "column" as const,
    justifyContent: "space-around" as const,
  };

  const firstBoxStyle = {
    overflowX: "visible",
    overflowY: "hidden",
  };

  const secondBoxStyle = {
    overflow: "hidden",
  };

  const thirdBoxStyle = {
    overflowX: "hidden",
    overflowY: "visible",
  };

  const fourthBoxStyle = {
    overflow: "hidden",
  };

  const fifthBoxStyle = {
    overflow: "visible",
  };

  return (
    <view style={containerStyle}>
      <view className="outer-box" style={firstBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={secondBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={thirdBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fourthBoxStyle}>
        <view className="inner-box"></view>
      </view>

      <view className="outer-box" style={fifthBoxStyle}>
        <view className="inner-box"></view>
      </view>
    </view>
  );
};

root.render(<Overflow />);

```



## Syntax

```css
overflow: visible;
overflow: hidden;
```

### Values

- `visible`(default) the content will not be clipped, the content and the descendants may render outside the element box

- `hidden` the overflow of the content and the descendants will be clipped, the reset of the content will be visible

## Formal definition

| Initial value | visible |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
hidden | visible
```

## Difference from Web

- `overflow` does not contain `scroll` and `auto`, for `scroll` please use [`<scroll-view>`](/api/elements/built-in/scroll-view.md) directly.

## Notes

- On Android platform, the Android view that has `opacity < 1` will be rendered in an offscreen buffer by default, the offscreen makes the `overflow: visible` not work correctly, you can add `overlap={false}` to disable the offscreen rendering. The property is linked to Android View `hasOverlappingRendering` property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.overflow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/overflow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-bottom.md
---

# padding-bottom

APISummary
## Introduction

Sets the height of the padding area on the bottom of an element. Negative values are not allowed for padding.

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-bottom`
**Bundle:** `dist/padding-bottom.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const PaddingBottom = () => {
  const containerStyle = {
    paddingTop: "10px",
    paddingBottom: "30px",
  };

  return (
    <view className="con" style={containerStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingBottom />);

```



## Syntax

```css
/* <length> values */
padding-bottom: 0.5em;
padding-bottom: 0;

/* <percentage> value */
padding-bottom: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding-bottom =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-bottom`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-bottom](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-bottom)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-inline-end.md
---

# padding-inline-end

APISummary
## Introduction

Defines the logical inline end padding of an element, which maps to a physical padding depending on the element's [`direction`](/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-end` taking the same values as the [`padding-right`](/api/css/properties/padding-right.md).
In `RTL` mode, `padding-inline-end` taking the same values as the [`padding-left`](/api/css/properties/padding-left.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-inline-end`
**Bundle:** `dist/padding-inline-end.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const PaddingInlineEnd = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
    paddingInlineStart: "10px",
    paddingInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<PaddingInlineEnd />);

```



## Syntax

```css
/* <length> values */
padding-inline-end: 0.5em;
padding-inline-end: 0px;
padding-inline-end: 2rpx;

/* <percentage> value */
padding-inline-end: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding-inline-end =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

1. `writing mode` is not supported in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-inline-end`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-end](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-end)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-inline-start.md
---

# padding-inline-start

APISummary
## Introduction

Defines the logical inline start padding of an element, which maps to a physical padding depending on the element's [`direction`](/api/css/properties/direction.md). Must be nonnegative.

In `LTR` mode, `padding-inline-start` taking the same values as the [`padding-left`](/api/css/properties/padding-left.md).
In `RTL` mode, `padding-inline-start` taking the same values as the [`padding-right`](/api/css/properties/padding-right.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-inline-start`
**Bundle:** `dist/padding-inline-start.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const PaddingInlineStart = () => {
  const [rtl, setRtl] = useState(false);

  const containerStyle = {
    direction: rtl ? "rtl" : "ltr" as "rtl" | "ltr",
    paddingInlineStart: "10px",
    paddingInlineEnd: "20px",
  };

  return (
    <>
      <view className="con" bindtap={() => setRtl(!rtl)} style={containerStyle}>
        <text className="intro">1</text>
        <text className="intro2">2</text>
      </view>
      <text>Click above to switch, current {rtl ? "rtl" : "ltr"}</text>
    </>
  );
};

root.render(<PaddingInlineStart />);

```



## Syntax

```css
/* <length> values */
padding-inline-start: 0.5em;
padding-inline-start: 0px;
padding-inline-start: 2rpx;

/* <percentage> value */
padding-inline-start: 10%;
```

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal syntax

```
padding-inline-start =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

1. `writing mode` is not supported in Lynx.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-inline-start`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-start](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-inline-start)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-left.md
---

# padding-left

APISummary
## Introduction

Sets the width of the padding area on the left of an element. Negative values are not allowed for padding.

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-left`
**Bundle:** `dist/padding-left.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const PaddingLeft = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  const contentStyle = {
    paddingLeft: "10px",
    paddingRight: "30px",
  };

  return (
    <view className="con" style={contentStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingLeft />);

```



## Syntax

```css
/* <length> values */
padding-left: 0.5em;
padding-left: 0;

/* <percentage> value */
padding-left: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding-left =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Difference with the Web

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-left`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-left](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-left)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-right.md
---

# padding-right

APISummary
## Introduction

Sets the width of the padding area on the right of an element. Negative values are not allowed for padding.

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-right`
**Bundle:** `dist/padding-right.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

import imageUrl from "../../resource/lynx.png";

const PaddingRight = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
    background: "white",
  };

  const contentStyle = {
    paddingLeft: "10px",
    paddingRight: "30px",
  };

  return (
    <view className="con" style={contentStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingRight />);

```



## Syntax

```css
/* <length> values */
padding-right: 0.5em;
padding-right: 0;

/* <percentage> value */
padding-right: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding-right =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding-top.md
---

# padding-top

APISummary
## Introduction

Sets the height of the padding area on the top of an element. Negative values are not allowed for padding.

## Examples

**This is an example below: css-api**

**Entry:** `src/padding-top`
**Bundle:** `dist/padding-top.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

import imageUrl from "../../resource/lynx.png";

const PaddingTop = () => {
  const containerStyle = {
    paddingTop: "10px",
    paddingBottom: "30px",
  };

  return (
    <view className="con" style={containerStyle}>
      <text className="intro2">2</text>
    </view>
  );
};

root.render(<PaddingTop />);

```



## Syntax

```css
/* <length> values */
padding-top: 0.5em;
padding-top: 0;

/* <percentage> value */
padding-top: 10%;
```

### Values

#### `0px`

**Default value**.

#### `<length>`

The size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding-top =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding-top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding-top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/padding.md
---

# padding

APISummary
## Introduction

Sets the padding area on all four sides of an element at once. An element's padding area is the space between its content and its border.

This property is a shorthand for the following CSS properties: [`padding-top`](/api/css/properties/padding-top.md), [`padding-right`](/api/css/properties/padding-right.md)、[`padding-bottom`](/api/css/properties/padding-bottom.md), [`padding-left`](/api/css/properties/padding-left.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/padding`
**Bundle:** `dist/padding.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Padding = () => {
  const scrollViewStyle = {
    flexDirection: "column" as const,
    width: "100%",
    height: "100%",
  };

  const firstBoxStyle = {
    padding: "20px",
  };

  const secondBoxStyle = {
    padding: "20px 5px",
  };

  const thirdBoxStyle = {
    padding: "20px 15px 10px",
  };

  const fourthBoxStyle = {
    padding: "20px 15px 10px 5px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical" style={scrollViewStyle}>
      <view className="con">
        <view className="intro" style={firstBoxStyle}>
          <text className="intro2">padding: 20px; All sides</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={secondBoxStyle}>
          <text className="intro2">padding: 20px 5px; Top/Bottom | Left/Right</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={thirdBoxStyle}>
          <text className="intro2">padding: 20px 15px 10px; Top | Left/Right | Bottom</text>
        </view>
      </view>

      <view className="con">
        <view className="intro" style={fourthBoxStyle}>
          <text className="intro2">padding: 20px 15px 10px 5px; Top | Right | Bottom | Left</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Padding />);

```



## Syntax

```css
/* Apply to all four sides */
padding: 1em;

/* top and bottom | left and right */
padding: 5% 10%;

/* top | left and right | bottom */
padding: 1em 2em 2em;

/* top | right | bottom | left */
padding: 5px 1em 0 2em;
```

The padding property may be specified using one, two, three, or four values. Each value is a [`<length>`](/api/css/data-type/length.md) or a [`<percentage>`](/api/css/data-type/percentage.md). Negative values are invalid.

When one value is specified, it applies the same padding to all four sides.
When two values are specified, the first padding applies to the top and bottom, the second to the left and right.
When three values are specified, the first padding applies to the top, the second to the right and left, the third to the bottom.
When four values are specified, the paddings apply to the top, right, bottom, and left in that order (clockwise).

### Values

#### `0px`

**Default value**.

#### `<length>`

[`<length>`](/api/css/data-type/length.md) means that the size of the padding as a fixed value. Must be nonnegative.

#### `<percentage>`

The size of the padding as a percentage, relative to the inline size (width) of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block).

## Formal definition

| Initial value | as each of the properties of the shorthand: 
- padding-bottom: 0
- padding-left: 0
- padding-right: 0
- padding-top: 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
padding =
  <'padding-top'>{1,4}

<padding-top> =
  <length-percentage [0,∞]>

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.padding`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding](https://developer.mozilla.org/zh-CN/docs/Web/CSS/padding)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/perspective.md
---

# perspective

APISummary
## Introduction

The perspective CSS property determines the distance between the z=0 plane and the user in order to give a 3D-positioned element some perspective.

## Examples

**This is an example below: css-api**

**Entry:** `src/perspective`
**Bundle:** `dist/perspective.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Perspective = () => {
  const [front, setFront] = useState(false);
  const [enableAni, setEnableAni] = useState(false);

  const handleKeyframe = () => {
    setFront(!front);
  };

  const handleAni = () => {
    setEnableAni(!enableAni);
  };

  const containerStyle = {
    display: "flex" as const,
    flexDirection: "column" as const,
    width: "100%",
    height: "1000px",
    background: "white",
  };

  const perspectiveStyle = {
    perspective: "750px",
  };

  return (
    <view style={containerStyle}>
      <text>Animation demo</text>

      <view className={front ? "container front" : "container back"} style={perspectiveStyle} bindtap={handleKeyframe}>
        <text>Front</text>
      </view>
      <view
        className={front ? "container1 back" : "container1 front"}
        style={perspectiveStyle}
        bindtap={handleKeyframe}
      >
        <view className="container2" />
        <text>Back</text>
      </view>
      <view className="anim-container">
        <view
          className={enableAni ? "anim-content anim-content-back backf0" : "anim-content anim-content-back backf1"}
          style={perspectiveStyle}
          bindtap={handleAni}
        >
          <text>Front</text>
          <text>Back</text>
        </view>
        <view
          className={enableAni ? "anim-content anim-content-front keyf0" : "anim-content anim-content-front keyf1"}
          style={perspectiveStyle}
          bindtap={handleAni}
        >
          <text>back</text>
        </view>
      </view>
    </view>
  );
};

root.render(<Perspective />);

```



## Syntax

```css
/* Keyword value */
perspective: auto;

/* <length> values */
perspective: 20px;
perspective: 3.5em;
```

### Values

- `auto`
  Default value

- `[<length>]`
  specifies the observer's distance from the `z=0` plane

```
perspective = auto | <length [0,∞]>
```

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
perspective = auto | <length [0,∞]>
```

## Differences from Web

- Different from Web, the Perspective property in Lynx takes effect on the current node, while in Web, the Perspective property takes effect on child nodes.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.perspective`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/perspective](https://developer.mozilla.org/zh-CN/docs/Web/CSS/perspective)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | It takes effect on all its descendants. |




---
url: /api/css/properties/pointer-events.md
---

# pointer-events

APISummary
## Introduction

The `pointer-events` CSS property specifies whether a component can respond to touch events.

## Usage Examples

**This is an example below: css-api**

**Entry:** `src/pointer-events`
**Bundle:** `dist/pointer-events.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";
import "./index.scss";

const PointerEvents = () => {
  const [bgColor, setBgColor] = useState("white");
  const [isShow, setIsShow] = useState(false);

  function handleControlTap(e: TouchEvent) {
    "background-only";
    setIsShow(isShow => !isShow);
  }

  function handleContentTap(e: TouchEvent) {
    "background-only";
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view className="container">
      <view className="control" bindtap={handleControlTap}>
        <text style={{ fontSize: "18px" }}>show or close popup</text>
      </view>
      {isShow
        && (
          <view className="popup" style={{ pointerEvents: "none" }}>
            <view className="mask">
              <view
                className="content"
                style={{ backgroundColor: bgColor, pointerEvents: "auto" }}
                bindtap={handleContentTap}
              />
            </view>
          </view>
        )}
    </view>
  );
};

root.render(<PointerEvents />);

```



## Syntax

```css
pointer-events: auto;
pointer-events: none;
```

### Values

- `auto`

  Default value. In this case, the node can respond to touch events.

- `none`

  The node cannot respond to touch events.

## Formal Definition

| Initial value | auto |
| Applies to | all elements that don't override hitTest |
| Inherited | no |
| Animatable | no |


## Formal Syntax

```
pointer-events: auto | none;
```

## Differences from Web

`inherit`, `initial`, and `unset` are not supported. There are no `SVG only` attribute values ​​such as `visiblePaintedroll` and `visibleFill`.

## Notes

- This property has an inheritance effect, that is, when the child node does not set `pointer-events`, it will inherit the `pointer-events` value of the parent node.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.pointer-events`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/pointer-events](https://developer.mozilla.org/zh-CN/docs/Web/CSS/pointer-events)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ❌ No | - |




---
url: /api/css/properties/position.md
---

# position

APISummary
## Introduction

The `position` CSS property sets how an element is positioned in a document. The [`top`](/api/css/properties/top.md), [`right`](/api/css/properties/right.md), [`bottom`](/api/css/properties/bottom.md), and [`left`](/api/css/properties/left.md) properties determine the final location of positioned elements.

## Types of positioning

- A positioned element is an element whose computed position value is either `relative`, `absolute`, `fixed`, or `sticky`.

- A relatively positioned element is an element whose computed position value is relative. The [`top`](/api/css/properties/top.md) and [`bottom`](/api/css/properties/bottom.md) properties specify the vertical offset from its normal position; the [`left`](/api/css/properties/left.md) and [`right`](/api/css/properties/right.md)properties specify the horizontal offset.

- An absolutely positioned element is an element whose computed position value is `absolute` or `fixed`. The `top`, `right`, `bottom`, and `left` properties specify offsets from the edges of the element's containing block. (The containing block is the ancestor relative to which the element is positioned.) If the element has margins, they are added to the offset. The element establishes a new block formatting context (BFC) for its contents.

- A stickily positioned element is an element whose computed position value is sticky. It's treated as relatively positioned until its containing block crosses a specified threshold (such as setting top to value other than auto) within its flow root (or the container it scrolls within), at which point it is treated as "stuck" until meeting the opposite edge of its containing block.

Most of the time, absolutely positioned elements that have [`height`](/api/css/properties/height.md) and [`width`](/api/css/properties/width.md) set to auto are sized so as to fit their contents. However, absolutely positioned elements can be made to fill the available vertical space by specifying both `top` and `bottom` and leaving `height` unspecified (that is, `auto`). They can likewise be made to fill the available horizontal space by specifying both `left` and `right` and leaving width as `auto`.

Except for the case just described (of absolutely positioned elements filling the available space):

If both `top` and `bottom` are specified (technically, not auto), `top` wins.
If both `left` and `right` are specified, `left` wins when direction is `ltr` (English, horizontal Japanese, etc.) and `right` wins when `direction` is `rtl` (Persian, Arabic, Hebrew, etc.).

## Examples

**This is an example below: css-api**

**Entry:** `src/position`
**Bundle:** `dist/position.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Position = () => {
  const boxStyles = {
    fixed1: {
      position: "fixed" as const,
      top: "5px",
      left: "5px",
      width: "50px",
      height: "50px",
      backgroundColor: "red",
    },
    absolute1: {
      position: "absolute" as const,
      top: "0px",
      left: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "brown",
    },
    fixed2: {
      position: "fixed" as const,
      top: "5px",
      left: "105px",
      width: "50px",
      height: "50px",
      backgroundColor: "pink",
    },
    absolute2: {
      position: "absolute" as const,
      right: "0px",
      width: "50px",
      height: "50px",
      backgroundColor: "coral",
    },
    fixed3: {
      position: "fixed" as const,
      left: "5px",
      top: "55px",
      width: "50px",
      height: "50px",
      backgroundColor: "Chocolate",
    },
    absolute3: {
      position: "absolute" as const,
      left: "100px",
      top: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkOrange",
    },
    absolute4: {
      position: "absolute" as const,
      top: "50px",
      left: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "yellow",
    },
    absolute5: {
      position: "absolute" as const,
      left: "150px",
      top: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "GoldenRod",
    },
    absolute6: {
      position: "absolute" as const,
      left: "0px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "GreenYellow",
    },
    absolute7: {
      position: "absolute" as const,
      left: "50px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "LightBlue",
    },
    absolute8: {
      position: "absolute" as const,
      left: "150px",
      top: "100px",
      width: "50px",
      height: "50px",
      backgroundColor: "DodgerBlue",
    },
    absolute9: {
      position: "absolute" as const,
      left: "0px",
      top: "150px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkTurquoise",
    },
    fixed4: {
      position: "fixed" as const,
      left: "55px",
      top: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkSlateBlue",
    },
    fixed5: {
      position: "fixed" as const,
      left: "105px",
      top: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "DarkSlateGrey",
    },
    absolute10: {
      position: "absolute" as const,
      bottom: "50px",
      right: "50px",
      width: "50px",
      height: "50px",
      backgroundColor: "green",
    },
    fixed6: {
      position: "fixed" as const,
      top: "155px",
      left: "155px",
      width: "50px",
      height: "50px",
      backgroundColor: "blue",
    },
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view className="container">
          <view style={boxStyles.fixed1}></view>
          <view style={boxStyles.absolute1}></view>
          <view style={boxStyles.fixed2}></view>
          <view style={boxStyles.absolute2}></view>
          <view style={boxStyles.fixed3}></view>
          <view style={boxStyles.absolute3}></view>
          <view style={boxStyles.absolute4}></view>
          <view style={boxStyles.absolute5}></view>
          <view style={boxStyles.absolute6}></view>
          <view style={boxStyles.absolute7}></view>
          <view style={boxStyles.absolute8}></view>
          <view style={boxStyles.absolute9}></view>
          <view style={boxStyles.fixed4}></view>
          <view style={boxStyles.fixed5}></view>
          <view style={boxStyles.absolute10}></view>
          <view style={boxStyles.fixed6}></view>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Position />);

```



## Syntax

```css
position: relative;
position: fixed;
position: absolute;
position: sticky;
```

### Values

#### `relative`

**default value**. The element is positioned according to the normal flow of the document, and then offset relative to itself based on the values of `top`, `right`, `bottom`, and `left`. The offset does not affect the position of any other elements.

#### `absolute`

The element is removed from the normal document flow, and no space is created for the element in the page layout. It is positioned relative to the containing block of its parent element. Its final position is determined by the values of `top`, `right`, `bottom`, and `left`.

#### `fixed`

The element is will be treated as a direct child of root node with the property `position` as `absolute`. Its final position is determined by the values of top, right, bottom, and left.

#### `sticky`

`sticky` is only supported on the children elements of a `scroll-view`. Is The element is positioned according to the normal flow of the document, and then offset relative to its parent scroll-view and containing block (nearest block-level ancestor), based on the values of top, right, bottom, and left. The offset does not affect the position of any other elements.

## Formal definition

| Initial value | `relative` |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

## Difference with the Web

[mdn:position](https://developer.mozilla.org/en-US/docs/Web/CSS/position)

1. Lynx does not support `static` and default value is `relative`.
2. `sticky` is only supported on the children elements of a `scroll-view`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.position`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/position](https://developer.mozilla.org/zh-CN/docs/Web/CSS/position)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |


## FAQ

1. If using [`z-index`](/api/css/properties/z-index.md) in `position: absolute` element, please set `z-index: 0` in parent element at the same time.



---
url: /api/css/properties/relative-align-bottom.md
---

# relative-align-bottom

APISummary
## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-bottom`
**Bundle:** `dist/relative-align-bottom.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignBottom = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeAlignBottom: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeAlignBottom: "parent" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-align-bottom: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
    </view>
  );
};

root.render(<RelativeAlignBottom />);

```



## Syntax

```css
relative-align-bottom: parent;
relative-align-bottom: none;

relative-align-bottom: 1;
relative-align-bottom: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the bottom edge.

- `parent`

  The bottom edge is aligned with the parent element.

- `<number>`

  `int` only. The bottom edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-bottom = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-bottom`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-inline-end.md
---

# relative-align-inline-end

APISummary
## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-align-inline-end` is equivalent to [`relative-align-right`](/api/css/properties/relative-align-right.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-end` is equivalent to [`relative-align-left`](/api/css/properties/relative-align-left.md);

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-inline-end`
**Bundle:** `dist/relative-align-inline-end.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignInlineEnd = () => {
  const container1Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "ltr" as const,
    marginBottom: "20px" as const,
  };
  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignInlineEnd: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignInlineEnd: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={container1Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-end: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-end: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-end: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-end: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignInlineEnd />);

```



## Syntax

```css
relative-align-inline-end: parent;
relative-align-inline-end: none;

relative-align-inline-end: 1;
relative-align-inline-end: 2;
```

### Values

The `relative-align-inline-end` property takes the same values as the [`relative-align-left`](/api/css/properties/relative-align-left.md) property.

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-inline-end = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-inline-end`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-inline-start.md
---

# relative-align-inline-start

APISummary
## Introduction

Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-align-inline-start` is equivalent to [`relative-align-left`](/api/css/properties/relative-align-left.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`,`relative-align-inline-start` is equivalent to [`relative-align-right`](/api/css/properties/relative-align-right.md);

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-inline-start`
**Bundle:** `dist/relative-align-inline-start.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignInlineStart = () => {
  const container1Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "ltr" as const,
    marginBottom: "20px" as const,
  };
  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignInlineStart: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignInlineStart: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={container1Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-start: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-start: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-inline-start: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-inline-start: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignInlineStart />);

```



## Syntax

```css
relative-align-inline-start: parent;
relative-align-inline-start: none;

relative-align-inline-start: 1;
relative-align-inline-start: 2;
```

### Values

The `relative-align-inline-start` property takes the same values as the [`relative-align-left`](/api/css/properties/relative-align-left.md) property.

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-inline-start = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-inline-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left/right edges of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-left.md
---

# relative-align-left

APISummary
## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the left edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-left`
**Bundle:** `dist/relative-align-left.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignLeft = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignLeft: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignLeft: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-left: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-left: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignLeft />);

```



## Syntax

```css
relative-align-left: parent;
relative-align-left: none;

relative-align-left: 1;
relative-align-left: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the left edge.

- `parent`

  The left edge is aligned with the parent element.

- `<number>`

  `int` only. The left edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-left = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-left`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the left edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-right.md
---

# relative-align-right

APISummary
## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the right edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-right`
**Bundle:** `dist/relative-align-right.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignRight = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
  };

  const view1Style = {
    relativeId: "1",
    display: "linear" as const,
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeAlignRight: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeAlignRight: "parent" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "40rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-align-right: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-align-right: parent</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeAlignRight />);

```



## Syntax

```css
relative-align-right: parent;
relative-align-right: none;

relative-align-right: 1;
relative-align-right: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the right edge.

- `parent`

  The right edge is aligned with the parent element.

- `<number>`

  `int` only. The right edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-right = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-right`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the right edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-align-top.md
---

# relative-align-top

APISummary
## Introduction

In [relative-layout](/guide/ui/layout/relative-layout.md), specifies that the current element is aligned with the top edge of the parent or sibling element corresponding to [`id`](/api/css/properties/relative-id.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-align-top`
**Bundle:** `dist/relative-align-top.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeAlignTop = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeAlignTop: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeAlignTop: "parent" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-align-top: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-align-top: parent</text>
      </view>
    </view>
  );
};

root.render(<RelativeAlignTop />);

```



## Syntax

```css
relative-align-top: parent;
relative-align-top: none;

relative-align-top: 1;
relative-align-top: 2;
```

### Values

- `none`

  **Default Value**. Does not align on the top edge.

- `parent`

  The top edge is aligned with the parent element.

- `<number>`

  `int` only. The top edge is aligned with the sibling element corresponding to this value(refer to [`relative-id`](/api/css/properties/relative-id.md)).

  :::info
  Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
  :::

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-align-top = none | parent | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-align-top`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the top edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-bottom-of.md
---

# relative-bottom-of

APISummary
## Introduction

The current element is to the below of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-bottom-of`
**Bundle:** `dist/relative-bottom-of.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeBottomOf = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeBottomOf: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeBottomOf: "1" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-bottom-of: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-bottom-of: 1</text>
      </view>
    </view>
  );
};

root.render(<RelativeBottomOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-bottom-of: none;
relative-bottom-of: 1;
relative-bottom-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-bottom-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-bottom-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the bottom of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-center.md
---

# relative-center

APISummary
## Introduction

Used to set the centering alignment of the current element in the [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-center`
**Bundle:** `dist/relative-center.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeCenter = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const view1Style = {
    relativeCenter: "horizontal" as const,
    backgroundColor: "lightgreen" as const,
  };

  const view2Style = {
    relativeCenter: "vertical" as const,
    backgroundColor: "lightblue" as const,
  };

  const view3Style = {
    relativeCenter: "both" as const,
    backgroundColor: "yellow" as const,
  };

  const view4Style = {
    relativeCenter: "none" as const,
    backgroundColor: "pink" as const,
  };

  const textStyle = {
    fontSize: "70rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>horizontal</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>vertical</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>both</text>
      </view>
      <view style={view4Style}>
        <text style={textStyle}>none</text>
      </view>
    </view>
  );
};

root.render(<RelativeCenter />);

```



## Value

### `none`

**Default Value**. Not centered.

### `both`

Centered vertically and horizontally.

### `vertical`

Center vertically.

### `horizontal`

Centered horizontally.

## Syntax

```css
relative-center: none;
relative-center: both;
relative-center: vertical;
relative-center: horizontal;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-center = none | both | vertical | horizontal
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-center`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Specifies that the current element is aligned with the bottom edge of the parent or sibling element corresponding to id.




---
url: /api/css/properties/relative-id.md
---

# relative-id

APISummary
## Introduction

Used to set the number of sibling elements in the [relative-layout](/guide/ui/layout/relative-layout.md). `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-id`
**Bundle:** `dist/relative-id.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeId = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const view1Style = {
    relativeId: "1",
    backgroundColor: "lightgreen",
  };

  const view2Style = {
    relativeRightOf: "1",
    relativeId: "2",
    backgroundColor: "lightblue",
  };

  const view3Style = {
    relativeId: "3",
    relativeCenter: "vertical" as const,
    backgroundColor: "yellow",
  };

  const view4Style = {
    relativeRightOf: "3",
    relativeId: "4",
    relativeCenter: "vertical" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "50rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-id: 2</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-id: 3</text>
      </view>
      <view style={view4Style}>
        <text style={textStyle}>relative-id: 4</text>
      </view>
    </view>
  );
};

root.render(<RelativeId />);

```



## Values

### `<number>`

`int` only. the number of the current element. **Default value** is `-1`.

`-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.

## Syntax

```css
relative-id: 1;
relative-id: 2;
```

## Formal definition

| Initial value | `-1` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-id = <integer [1,∞]>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-id`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Used to set the number of sibling elements in the relative layout.




---
url: /api/css/properties/relative-inline-end-of.md
---

# relative-inline-end-of

APISummary
## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-inline-end-of` is equivalent to [`relative-right-of`](/api/css/properties/relative-right-of.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-end-of` is equivalent to [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-inline-end-of`
**Bundle:** `dist/relative-inline-end-of.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeInlineEndOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
    direction: "ltr" as const,
  };

  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeCenter: "horizontal" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeInlineEndOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeInlineEndOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "23rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-end-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeInlineEndOf />);

```



## Values

The `relative-inline-end-of` property takes the same values as the [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Syntax

```css
relative-inline-end-of: none;
relative-inline-end-of: 1;
relative-inline-end-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-inline-end-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-inline-end-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left/right of the sibling element corresponding to the specified id.




---
url: /api/css/properties/relative-inline-start-of.md
---

# relative-inline-start-of

APISummary
## Introduction

The current element is to the left/right of the sibling element corresponding to the specified [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

When [`direction`](/api/css/properties/direction.md) is `ltr`, `relative-inline-start-of` is equivalent to [`relative-left-of`](/api/css/properties/relative-left-of.md);

When [`direction`](/api/css/properties/direction.md) is `rtl/lynx-rtl`, `relative-inline-start-of` is equivalent to [`relative-right-of`](/api/css/properties/relative-right-of.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-inline-start-of`
**Bundle:** `dist/relative-inline-start-of.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const RelativeInlineStartOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginBottom: "20px" as const,
    direction: "ltr" as const,
  };

  const container2Style = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    direction: "rtl" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeCenter: "horizontal" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeInlineStartOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeInlineStartOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "23rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <text style={titleStyle}>direction: ltr</text>
      <view className="container" style={containerStyle}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
      <text style={titleStyle}>direction: rtl</text>
      <view className="container" style={container2Style}>
        <view style={view1Style}>
          <text style={textStyle}>relative-id: 1</text>
          <text style={textStyle}>relative-center: horizontal</text>
        </view>
        <view style={view2Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-align-bottom: parent</text>
        </view>
        <view style={view3Style}>
          <text style={textStyle}>relative-inline-start-of: 1</text>
          <text style={textStyle}>relative-center: vertical</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<RelativeInlineStartOf />);

```



## Values

The `relative-inline-start-of` property takes the same values as the [`relative-left-of`](/api/css/properties/relative-left-of.md).

## Syntax

```css
relative-inline-start-of: none;
relative-inline-start-of: 1;
relative-inline-start-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-inline-start-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-inline-start-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.0 | - |
| iOS | 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.0 | - |
| Clay iOS | 2.0 | - |
| Clay macOS | 2.0 | - |
| Clay Windows | 2.0 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left/right of the sibling element corresponding to the specified id.




---
url: /api/css/properties/relative-layout-once.md
---

# relative-layout-once

APISummary
## Introduction

Used to set typesetting acceleration in [relative-layout](/guide/ui/layout/relative-layout.md).
When using positioning between elements at the same level, it is recommended to enable this property, and elements at the same level will only depend upwards.

When this property is false, the relative performance is poor, and it can support the vertical direction and handle the dependencies separately in the horizontal direction.
For example, if there are 1 and 2 elements in the page, the width of 1 is determined by 2, and the height of 2 is determined by 1. In this case, if relative-layout-once is true, it cannot be processed, and relative-layout-once is false. can be handled.

## Syntax

```css
relative-layout-once: true;
relative-layout-once: false;
```

### Values

- `true`

  **Default Value**. Turn on [relative-layout](/guide/ui/layout/relative-layout.md) acceleration.

- `false`

  Turn off [relative](/guide/ui/layout/relative-layout.md) layout acceleration.

## Formal definition

| Initial value | `true` |
| Applies to | relative container |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-layout-once = true | false
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-layout-once`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** Used to set typesetting acceleration. When using positioning between elements at the same level, it is recommended to enable this property, and elements at the same level will only depend upwards.




---
url: /api/css/properties/relative-left-of.md
---

# relative-left-of

APISummary
## Introduction

The current element is to the left of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-left-of`
**Bundle:** `dist/relative-left-of.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeLeftOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginTop: "20px" as const,
    marginBottom: "20px" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeAlignRight: "parent" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeLeftOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeLeftOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "25rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-left-of: 1</text>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-left-of: 1</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
    </view>
  );
};

root.render(<RelativeLeftOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-left-of: none;
relative-left-of: 1;
relative-left-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-left-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-left-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the left of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-right-of.md
---

# relative-right-of

APISummary
## Introduction

The current element is to the right of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-right-of`
**Bundle:** `dist/relative-right-of.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeRightOf = () => {
  const containerStyle = {
    display: "relative" as const,
    relativeLayoutOnce: true,
    marginTop: "20px" as const,
    marginBottom: "20px" as const,
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(120deg ,#0095ff 30% ,#42d392 100%)" as const,
  };

  const view1Style = {
    relativeId: "1",
    relativeAlignLeft: "parent" as const,
    display: "linear" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    textAlign: "center" as const,
  };

  const view2Style = {
    display: "linear" as const,
    relativeRightOf: "1",
    alignItems: "center" as const,
    relativeAlignBottom: "parent" as const,
    backgroundColor: "lightblue",
  };

  const view3Style = {
    display: "linear" as const,
    relativeRightOf: "1" as const,
    relativeCenter: "vertical" as const,
    alignItems: "center" as const,
    backgroundColor: "pink",
  };
  const textStyle = {
    fontSize: "25rpx" as const,
    fontWeight: "500" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={view1Style}>
        <text style={textStyle}>relative-id: 1</text>
        <text style={textStyle}>relative-align-left: parent</text>
      </view>
      <view style={view2Style}>
        <text style={textStyle}>relative-right-of: 1</text>
        <text style={textStyle}>relative-align-bottom: parent</text>
      </view>
      <view style={view3Style}>
        <text style={textStyle}>relative-right-of: 1</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
    </view>
  );
};

root.render(<RelativeRightOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-right-of: none;
relative-right-of: 1;
relative-right-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-right-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-right-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the right of the sibling element specified corresponding to id.




---
url: /api/css/properties/relative-top-of.md
---

# relative-top-of

APISummary
## Introduction

The current element is to the top of the sibling element specified corresponding to [`id`](/api/css/properties/relative-id.md) in [relative-layout](/guide/ui/layout/relative-layout.md).

## Examples

**This is an example below: css-api**

**Entry:** `src/relative-top-of`
**Bundle:** `dist/relative-top-of.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RelativeTopOf = () => {
  const containerStyle = {
    display: "relative" as const,
  };

  const firstViewStyle = {
    display: "linear" as const,
    relativeId: "1",
    relativeCenter: "vertical" as const,
    backgroundColor: "lightgreen",
    alignItems: "center" as const,
    width: "40%",
  };

  const secondViewStyle = {
    display: "linear" as const,
    relativeTopOf: "1",
    relativeAlignRight: "parent",
    backgroundColor: "lightblue",
    alignItems: "center" as const,
    width: "40%",
  };

  const thirdViewStyle = {
    relativeTopOf: "1" as const,
    backgroundColor: "pink",
  };

  const textStyle = {
    fontSize: "35rpx" as const,
    fontWeight: "600" as const,
    textAlign: "center" as const,
  };

  return (
    <view className="container" style={containerStyle}>
      <view style={firstViewStyle}>
        <text style={textStyle}>relative-id: 1;</text>
        <text style={textStyle}>relative-center: vertical</text>
      </view>
      <view style={secondViewStyle}>
        <text style={textStyle}>relative-top-of: 1;</text>
        <text style={textStyle}>relative-align-right: parent</text>
      </view>
      <view style={thirdViewStyle}>
        <text style={textStyle}>relative-top-of: 1</text>
      </view>
    </view>
  );
};

root.render(<RelativeTopOf />);

```



## Values

### `none`

**Default Value**. Act as not set this property.

### `<number>`

`int` only. Specifies the sibling element number.(refer to [`relative-id`](/api/css/properties/relative-id.md)).

:::info
Attention please when setting [`relative-id`](/api/css/properties/relative-id.md): `-1` and `0` are special values. `-1` is the default value, indicating that the current element will not be considered as the alignment reference standard for sibling elements. Using `0` as an element ID is not allowed, as it will result in unexpected behavior.
:::

## Syntax

```css
relative-top-of: none;
relative-top-of: 1;
relative-top-of: 2;
```

## Formal definition

| Initial value | `none` |
| Applies to | relative items |
| Inherited | no |
| Animatable |  |


## Formal syntax

```
relative-top-of = none | <number>
```

## Difference between web

- There is no such style in web.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.relative-top-of`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.4 | - |
| Clay iOS | 1.4 | - |
| Clay macOS | 1.4 | - |
| Clay Windows | 1.4 | - |
| Web | ❌ No | - |

**Description:** The current element is to the top of the sibling element specified corresponding to id.




---
url: /api/css/properties/right.md
---

# right

APISummary
## Introduction

The `right` CSS property participates in specifying the horizontal position of a positioned element. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `right` depends on how the element is positioned (i.e., the value of the position property):

- When `position` is set to `absolute` or `fixed`, the `right` property specifies the distance between the element's outer margin of `right` edge and the inner border of the `right` edge of its containing block.

- When `position` is set to `relative`, the `right` property specifies the distance the element's `right` edge is moved to the `left` from its normal position.

When both `left` and `right` are defined, and `width` constraints don't prevent it, the element will stretch to satisfy both. If the element cannot stretch to satisfy both, the `position` of the element is overspecified. When this is the case, the `left` value has precedence when the container is left-to-right; the `right` value has precedence when the container is right-to-left.

## Examples

**This is an example below: css-api**

**Entry:** `src/right`
**Bundle:** `dist/right.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Right = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    right: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    right: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    right: "40px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={containerStyle}>
        <view style={firstBoxStyle}></view>
        <view style={secondBoxStyle}></view>
        <view style={thirdBoxStyle}></view>
        <view style={fourthBoxStyle}></view>
      </view>
    </scroll-view>
  );
};

root.render(<Right />);

```



## Syntax

```css
/* <length> values */
right: 3px;
right: 2rpx;
right: 2.4em;
right: 3rem;

right: 10%;

/* Keyword value */
right: auto;

/* calc */
right: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the right edge of the containing block.

- for relatively positioned elements, the distance that the element is moved to the left of its normal position.

#### `<percentage>`

A `<percentage>` of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

## Formal definition

| Initial value | auto |
| Applies to | all elements |
| Inherited | no |
| Animatable |  |
| Percentages | refer to the width of the containing block |


## Formal syntax

```
right =
  auto                 |
  <length-percentage>  |

<length-percentage> =
  <length>      |
  <percentage>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.right`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/right](https://developer.mozilla.org/zh-CN/docs/Web/CSS/right)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the horizontal position of a positioned element. It has no effect on non-positioned elements.




---
url: /api/css/properties/row-gap.md
---

# row-gap (grid-row-gap)

APISummary
## Introduction

The `row-gap`/`grid-row-gap` CSS property sets the size of the gap (gutter) between an element's rows in [flexible box layout](/guide/ui/layout/flexible-box-layout.md) and grid layout.

For compatibility, `row-gap` or `grid-row-gap` can be used both.

## Examples

**This is an example below: css-api**

**Entry:** `src/row-gap`
**Bundle:** `dist/row-gap.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const RowGap = () => {
  const flexContainerStyle = {
    display: "flex" as const,
    flexWrap: "wrap" as const,
    rowGap: "15px",
    margin: "10px",
    border: "1px solid #000",
    borderRadius: "4px",
    marginBottom: "100rpx" as const,
  };

  const gridContainerStyle = {
    display: "grid" as const,
    rowGap: "10px",
    gridTemplateColumns: "1fr 1fr 1fr",
    margin: "10px",
    padding: "5px",
    border: "1px solid #000",
    borderRadius: "4px",
  };

  const titleStyle = {
    fontSize: "50rpx" as const,
    alignSelf: "center" as const,
    fontWeight: "900" as const,
    color: "linear-gradient(to right, rgb(255,53,26), rgb(0,235,235))" as const,
  };

  return (
    <>
      <text style={titleStyle}>using row-gap in flex layout</text>
      <view style={flexContainerStyle}>
        <text className="item">ONE</text>
        <text className="item">TWO</text>
        <text className="item">THREE</text>
        <text className="item">FOUR</text>
        <text className="item">FIVE</text>
        <text className="item">SIX</text>
        <text className="item">SEVEN</text>
        <text className="item">EIGHT</text>
        <text className="item">NINE</text>
        <text className="item">TEN</text>
      </view>

      <text style={titleStyle}>using row-gap in grid layout</text>
      <view style={gridContainerStyle}>
        <text className="item2">ONE</text>
        <text className="item2">TWO</text>
        <text className="item2">THREE</text>
        <text className="item2">FOUR</text>
        <text className="item2">FIVE</text>
        <text className="item2">SIX</text>
        <text className="item2">SEVEN</text>
        <text className="item2">EIGHT</text>
        <text className="item2">NINE</text>
        <text className="item2">TEN</text>
      </view>
    </>
  );
};

root.render(<RowGap />);

```



## Values

### `<length>`

[`<length>`](/api/css/data-type/length.md) is the width of the gutter separating the rows.

### `<percentage>`

[`<percentage>`](/api/css/data-type/percentage.md) values are relative to the dimension of the element.

## Formal syntax

```
row-gap = <length-percentage [0,∞]>

<length-percentage> = <length> | <percentage>
```

## Syntax

```css
/* <length> values */
row-gap: 20px;
row-gap: 1em;

/* <percentage> value */
row-gap: 10%;

/* calc() values */
row-gap: calc(10% + 20px);
```

## Formal definition

| Initial value | `0` |
| Applies to | flex containers, grid containers |
| Inherited | no |
| Animatable |  |
| Percentages | refer to vertical dimension of its own content area |


## Difference with the web

[mdn: row-gap](https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap)

1. `normal` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.row-gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/row-gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/row-gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |

**Description:** <code>row-gap</code>


## FAQ



---
url: /api/css/properties/text-align.md
---

# text-align

APISummary
## Introduction

The `text-align` CSS property sets the horizontal alignment of the inline-level content inside a block element.

## Examples

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-normal.jpeg)
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-ltr.jpeg)
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-rtl.jpeg)
![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/text-align-lynx-rtl.jpeg)
## Syntax

```css
/* Keyword values */
text-align: start;
text-align: end;
text-align: left;
text-align: right;
text-align: center;
```

### Values

- `left`
  The inline contents are aligned to the left edge of the line box.

- `right`
  The inline contents are aligned to the right edge of the line box.

- `center`
  The inline contents are centered within the line box.

- `start`
  The same as left if direction is left-to-right and right if direction is right-to-left.
  **When `direction` is `normal`, `start` is the nature direction of text。**

- `end`
  The same as right if direction is left-to-right and left if direction is right-to-left.

## Formal definition

| Initial value | start |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal syntax

```
left | right | center | start | end
```

## Difference with web

- Not support `justify-all` and `justify`.

- Not support `match-parent`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-decoration.md
---

# text-decoration

APISummary
## Introduction

The `text-decoration` shorthand CSS property sets the appearance of decorative lines on text.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-decoration`
**Bundle:** `dist/text-decoration.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextDecoration = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const noneStyle = {
    textDecoration: "none",
  };

  const underlineStyle = {
    textDecoration: "underline",
  };

  const lineThroughStyle = {
    textDecoration: "line-through",
  };

  const redSolidStyle = {
    textDecoration: "underline line-through red solid",
  };

  const greenDottedStyle = {
    textDecoration: "underline line-through green dotted",
  };

  const blueDashedStyle = {
    textDecoration: "underline line-through blue dashed",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>text-decoration</text>
          <text style={noneStyle}>None</text>
          <text style={underlineStyle}>Underline</text>
          <text style={lineThroughStyle}>Line Through</text>
          <text style={redSolidStyle}>Red Solid Line</text>
          <text style={greenDottedStyle}>Green Dotted Line</text>
          <text style={blueDashedStyle}>Blue Dashed Line</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<TextDecoration />);

```



## Syntax

```css
text-decoration: underline;
text-decoration: line-through red;
text-decoration: none;
```

### Values

#### **text-decoration-line**

The `text-decoration-line` CSS property sets the kind of decoration that is used on text in an element.

- `none` <br />
  **Default value**. Produces no text decoration.

- `underline`
  Each line of text has a decorative line beneath it.

- `line-through`
  Each line of text has a decorative line going through its middle.

#### **text-decoration-color**

The `text-decoration-color` CSS property sets the color of decorations.

- [`<color>`](/api/css/data-type/color.md)

#### **text-decoration-style**

The `text-decoration-style` CSS property sets the style of the lines specified by `text-decoration-line`.

- `solid`
  Draws a single line.

- `double`
  Draws a double line.

- `dotted`
  Draws a dotted line.

- `dashed`
  Draws a dashed line.

- `wavy`
  Draws a wavy line.

## Formal definition

| Initial value | empty value |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Differences from Web

- Not support [`text-decoration-thickness`](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-decoration-thickness)
- Not support multiple decoration lines.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-indent.md
---

# text-indent

APISummary
## Introduction

The text-indent attribute can define the indentation before the first line of text content of a text.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-indent`
**Bundle:** `dist/text-indent.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextIndent = () => {
  const textStyle = {
    textIndent: "10px",
  };

  return (
    <text style={textStyle}>
      hello world, Now we can use text-indent in the text node
    </text>
  );
};

root.render(<TextIndent />);

```



## Syntax

```css
/* <length> values */
text-indent: 40px;

/* <percentage> value
   relative to the containing block width */
text-indent: 15%;
```

### Values

- [`<length>`](/api/css/data-type/length.md)
  Length value, defaults to 0

- [`<percentage>`](/api/css/data-type/percentage.md)
  Percentage relative to the `text` width

## Formal definition

| Initial value | 0 |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<length> | <percentage>
```

## Difference with web

When writing **percentage**, you need to specify the width of the text element, otherwise, it will not take effect

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-indent`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-indent](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-indent)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-overflow.md
---

# text-overflow

APISummary
## Introduction

The `text-overflow` CSS property sets how hidden overflow content is signaled to users.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-overflow`
**Bundle:** `dist/text-overflow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextOverflow = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const sampleText = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

  return (
    <view style={containerStyle}>
      <text className="title">text-overflow: clip</text>
      <text className="item clip" text-maxline="2">
        {sampleText}
      </text>

      <text className="title">text-overflow: ellipsis</text>
      <text className="item overflow" text-maxline="2">
        {sampleText}
      </text>
    </view>
  );
};

root.render(<TextOverflow />);

```



## Syntax

```css
text-overflow: clip;
text-overflow: ellipsis;
```

### Values

- `clip` <br />
  **Default Value**。This keyword value will truncate the text at the limit of the content area.

- `ellipsis` <br />
  This keyword value will display an ellipsis (`…`, `U+2026 HORIZONTAL ELLIPSIS`) to represent clipped text.

## Formal definition

| Initial value | clip |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
clip | ellipsis
```

## Difference between web

- Not support `fade` 。

- Not support `<string>` with custom clip text.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-overflow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-overflow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-overflow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-shadow.md
---

# text-shadow

APISummary
## Introduction

The `text-shadow` CSS property adds shadows to text.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-shadow`
**Bundle:** `dist/text-shadow.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextShadow = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const headerStyle = {
    backgroundColor: "#ccc",
    marginTop: "10px",
  };

  const noneStyle = {
    textShadow: "none" as const,
  };

  const singleStyle = {
    textShadow: "1px 1px 2px #558abb" as const,
  };

  const multiStyle = {
    textShadow: "1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue" as const,
  };

  const rgbaStyle = {
    textShadow: "0 .005px .01rem rgba(70, 70, 70, .3)" as const,
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <view style={containerStyle}>
          <text style={headerStyle}>text-shadow</text>
          <text style={noneStyle}>text-shadow: none;</text>
          <text style={singleStyle}>text-shadow: 1px 1px 2px #558abb;</text>
          <text style={multiStyle}>text-shadow: 1px 1px 2px red, 0 0 1em blue, 0 0 0.2em blue;</text>
          <text style={rgbaStyle}>text-shadow: 0 .005px .01rem rgba(70, 70, 70, .3);</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<TextShadow />);

```



## Syntax

```css
/* offset-x | offset-y | blur-radius | color */
text-shadow: 1px 1px 2px black;

/* color | offset-x | offset-y | blur-radius */
text-shadow: #fc0 1px 0 10px;

/* offset-x | offset-y | color */
text-shadow: 5px 5px #558abb;

/* color | offset-x | offset-y */
text-shadow: white 2px 5px;

/* offset-x | offset-y
/* Use defaults for color and blur-radius */
text-shadow: 5px 10px;
```

## Formal definition

| Initial value | empty value |
| Applies to | text |
| Inherited | yes |
| Animatable | no |


## Formal Syntax

```
none | [ <length>{3} <color> ]
```

## Differences from Web

- Only support one shadow layer.

- For now both `offset-x`,`offset-y`,`blur-radius` and `color` are mandatory. And `color` must be the last value.

## Notes

- In some old version Android platform, `text-shadow` may not be rendered when `blur-radius` is 0.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-shadow`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-shadow](https://developer.mozilla.org/zh-CN/docs/Web/CSS/text-shadow)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke-color.md
---

# 

APISummary
## Introduction

`text-stroke-color` specifies the stroke color of characters of text.

## Example

**This is an example below: css-api**

**Entry:** `src/text-stroke-color`
**Bundle:** `dist/text-stroke-color.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextStokeColor = () => {
  const textStyleRed = {
    textStrokeWidth: "1px",
    textStrokeColor: "#ff0000",
  };
  const textStyleGreen = {
    textStrokeWidth: "1px",
    textStrokeColor: "green",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyleRed}>The stroke of this text is red</text>
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyleGreen}>The stroke of this text is green</text>
    </scroll-view>
  );
};

root.render(<TextStokeColor />);

```



## Syntax

```css
text-stroke-color: red;
text-stroke-color: #e08ab4;
text-stroke-color: rgb(200, 100, 0);
```

### Values

- [`<color>`](/api/css/properties/color.md)<br />
  The color of the stroke.

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
text-stroke-color = <color>
```

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke-color`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-color](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-color)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke-width.md
---

# 

APISummary
## Introduction

The `text-stroke-width` property specifies the width of the text stroke.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-stroke-width`
**Bundle:** `dist/text-stroke-width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextStokeColor = () => {
  const textStyle1 = {
    textStrokeWidth: "1px",
    textStrokeColor: "red",
  } as const;
  const textStyle2 = {
    textStrokeWidth: "0.5px",
    textStrokeColor: "red",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyle1}>The stroke width of this text is 1px</text>
      {/* @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types` */}
      <text style={textStyle2}>The stroke width of this text is 0.5px</text>
    </scroll-view>
  );
};

root.render(<TextStokeColor />);

```



## Syntax

```css
text-stroke-width: 2px;
text-stroke-width: 0.1em;
text-stroke-width: 5pt;
```

### Values

- [`<length>`](/api/css/data-type/length.md)<br />
  The width of the stroke.

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
text-stroke-width = <length[0,∞]>
```

## Differences from Web

- Does not support setting attribute values such as `thin`.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke-width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke-width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/text-stroke.md
---

# text-stroke

APISummary
## Introduction

The `text-stroke` CSS property specifies the width and color of strokes for text characters.

## Examples

**This is an example below: css-api**

**Entry:** `src/text-stroke`
**Bundle:** `dist/text-stroke.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TextStroke = () => {
  const textStyle = {
    textStroke: "1px red",
  } as const;

  return (
    // @ts-expect-error TODO(types): Support textStroke in `@lynx-js/types`
    <text style={textStyle}>
      The stroke of this text is red
    </text>
  );
};

root.render(<TextStroke />);

```



## Syntax

```css
text-stroke: 4px green;
```

### Values

- none <br />
  **Default value**

- [`<length>`](/api/css/data-type/length.md) <br />
  Set the width of the stroke

- [`<color>`](/api/css/properties/color.md) <br />
  Set the color of the stroke

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
text-stroke = none | <length [0,∞]> || <color>
```

## Differences from Web

- Does not support setting attribute values such as `thin` for stroke width.

## Notes

- Some fonts may have overlapping strokes.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.text-stroke`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke](https://developer.mozilla.org/zh-CN/docs/Web/CSS/-webkit-text-stroke)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/top.md
---

# top

APISummary
## Introduction

The `top` CSS property participates in specifying the vertical position. For more information, please refer to property [`position`](/api/css/properties/position.md).

The effect of `top` depends on how the element is positioned (i.e., the value of the position property):

- When position is set to `absolute` or `fixed`, the `top` property specifies the distance between the element's outer margin of top edge and the inner border of the top edge of its containing block.

- When `position` is set to `relative`, the `top` property specifies the distance the element's top edge is moved below its normal position.

When both `top` and `bottom` are specified, position is set to `absolute` or `fixed`, and `height` is unspecified (either `auto` or 100%) both the `top` and `bottom` distances are respected. In all other situations, if `height` is constrained in any way or `position` is set to `relative`, the top property takes precedence and the `bottom` property is ignored.

## Examples

**This is an example below: css-api**

**Entry:** `src/top`
**Bundle:** `dist/top.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Top = () => {
  const containerStyle = {
    width: "210px",
    height: "210px",
    border: "5px",
    borderColor: "black",
  };

  const firstBoxStyle = {
    position: "absolute" as const,
    top: "80px",
    width: "50px",
    height: "50px",
    backgroundColor: "red",
  };

  const secondBoxStyle = {
    position: "fixed" as const,
    top: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "green",
  };

  const thirdBoxStyle = {
    position: "relative" as const,
    top: "155px",
    width: "50px",
    height: "50px",
    backgroundColor: "yellow",
  };

  const fourthBoxStyle = {
    width: "50px",
    height: "50px",
    backgroundColor: "blue",
  };

  return (
    <view style={containerStyle}>
      <view style={firstBoxStyle}></view>
      <view style={secondBoxStyle}></view>
      <view style={thirdBoxStyle}></view>
      <view style={fourthBoxStyle}></view>
    </view>
  );
};

root.render(<Top />);

```



## Syntax

```css
/* <length> values */
top: 3px;
top: 2rpx;
top: 2.4em;
top: 3rem;

top: 10%;

/* Keyword value */
top: auto;

/* calc */
top: calc(1px + 1px);
```

### Values

#### `auto`

**Default value**.

#### `<length>`

A negative, null, or positive [`<length>`](/api/css/data-type/length.md) that represents:

- for absolutely positioned elements, the distance to the top edge of the containing block.

- for relatively positioned elements, the distance that the element is moved below its normal position.

#### `<percentage>`

Defines the height as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s height.

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Difference with the web

[mdn: top](https://developer.mozilla.org/en-US/docs/Web/CSS/bottom)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.top`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/top](https://developer.mozilla.org/zh-CN/docs/Web/CSS/top)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |

**Description:** participates in setting the vertical position of a positioned element. It has no effect on non-positioned elements.


## FAQ



---
url: /api/css/properties/transform-origin.md
---

# transform-origin

APISummary
## Introduction

The transform-origin CSS property sets the origin for an element's transformations.

## Examples

**This is an example below: css-api**

**Entry:** `src/transform-origin`
**Bundle:** `dist/transform-origin.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const TransformOrigin = () => {
  const emptyBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    border: "1px solid black",
  } as const;

  const redBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    backgroundColor: "red",
    transform: "rotate(45rad)",
  } as const;

  const greenBoxStyle = {
    position: "absolute",
    width: "100px",
    height: "100px",
    backgroundColor: "green",
    transformOrigin: "50% top",
    transform: "rotate(45rad)",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="intro">
        <view style={redBoxStyle} />
        <view style={emptyBoxStyle} />
      </view>
      <view className="intro">
        <view style={greenBoxStyle} />
        <view style={emptyBoxStyle} />
      </view>
    </scroll-view>
  );
};

root.render(<TransformOrigin />);

```



## Syntax

```scss
/* x-offset | default */
transform-origin: 2px;
transform-origin: bottom;

/* x-offset | y-offset */
transform-origin: 3cm 2px;

/* x-offset-keyword | y-offset */
transform-origin: left 2px;

/* x-offset-keyword | y-offset-keyword */
transform-origin: right top;

/* x-offset | y-offset */
transform-origin: 2px 30%;

/* x-offset-keyword | y-offset */
transform-origin: left 5px;

/* x-offset-keyword | y-offset-keyword */
transform-origin: right bottom;
```

### Values

The value of the `transform-origin` can be one or two. **The first value represents `x-offset`**, **the second value represents `y-offset`**, **separated by a space**.

#### x-offset

The value of `x-offset` can be length `<length>`, percentage `<x-percentage>`, keyword `<x-offset-keyword>`

- **length**
  Length value, the unit is px,rem,rpx, etc.

- **x-percentage**
  Percentage relative to parent View**Width**.

- **x-offset-keyword**

| Keyword | Value |
| ------- | ----- |
| left    | 0%    |
| center  | 50%   |
| right   | 100%  |

#### y-offset

The value of `y-offset` can be length `<length>`, percentage `<y-percentage>`, keyword `<y-offset-keyword>`

- **length**
  Length value, the unit is px,rem,rpx, etc.

- **y-percentage**
  Percentage relative to parent View**Height**.

- **y-offset-keyword**

| Keyword | Value |
| ------- | ----- |
| top     | 0%    |
| center  | 50%   |
| bottom  | 100%  |

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Difference from W3C

- Transform-origin is not supported for z-axis

## Note

- The first value of transform-origin always means `x-offset`, the second value always means `y-offset`, please do not write inverse.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transform-origin`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform-origin](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform-origin)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transform.md
---

# transform

APISummary
## Introduction

The transform CSS property lets you rotate, scale, skew, or translate an element.

## Examples

**This is an example below: css-api**

**Entry:** `src/transform`
**Bundle:** `dist/transform.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Transform = () => {
  const containerStyle = {
    flexDirection: "column" as const,
    alignItems: "center",
    padding: "20px",
    backgroundColor: "#f5f5f5",
  } as const;

  const boxBaseStyle = {
    width: "120px",
    height: "120px",
    backgroundColor: "#2196F3",
    margin: "25px",
    display: "flex",
    alignItems: "center",
    justifyContent: "center",
  } as const;

  const textStyle = {
    color: "white",
    fontSize: "16px",
    textAlign: "center" as const,
  } as const;

  const rotateStyle = {
    ...boxBaseStyle,
    transform: "rotate(45deg)",
    backgroundColor: "#4CAF50",
  } as const;

  const scaleStyle = {
    ...boxBaseStyle,
    transform: "scale(1.2)",
    backgroundColor: "#FF9800",
  } as const;

  const translateStyle = {
    ...boxBaseStyle,
    transform: "translate(50px, 0)",
    backgroundColor: "#9C27B0",
  } as const;

  const multipleStyle = {
    ...boxBaseStyle,
    transform: "rotate(45deg) scale(0.8) translate(50px, 0)",
    backgroundColor: "#E91E63",
  } as const;

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view style={containerStyle}>
        <view style={rotateStyle}>
          <text style={textStyle}>Rotate 45°</text>
        </view>

        <view style={scaleStyle}>
          <text style={textStyle}>Scale 1.2x</text>
        </view>

        <view style={translateStyle}>
          <text style={textStyle}>Move Right 50px</text>
        </view>

        <view style={multipleStyle}>
          <text style={textStyle}>Combined Effects</text>
        </view>
      </view>
    </scroll-view>
  );
};

root.render(<Transform />);

```



## Syntax

```scss
/* Function values */
transform: rotate(0.5turn);
transform: rotateX(10deg);
transform: rotateY(10deg);
transform: translate(12px, 50%);
transform: translate3d(12px, 50%, 3em);
transform: translateX(2em);
transform: translateY(3px);
transform: translateZ(2px);
transform: scale(2, 0.5);
transform: scaleX(2);
transform: scaleY(0.5);

// equal to transform: translate(50px, 100px);
transform: matrix(1, 0, 0, 1, 50, 100);
// equal to transform: translateX(100px);
transform: matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 100, 0, 0, 1);

/* Multiple function values */
transform: translateX(10px) rotate(10deg) translateY(5px);
transform: translate3d(10px, 0, 20px) rotateY(3deg);
```

The value of the `transform` can be one or more `<function>`, which are separated by spaces. For details, see [function standard syntax](#function-standard-syntax)

### function standard syntax

- **translate**

```
translate( <length> | <percentage> , <length> | <percentage>? )
```

- **translateX**

```
translateX( <length> | <percentage> )
```

- **translateY**

```
translateY( <length> | <percentage> )
```

- **translateZ**

```
translateZ( <length> )
```

:::info
When using translateZ, it is recommended to set `flatten={false}` on the parent node of the node, otherwise it may cause the `overflow:hidden` of the parent node to fail on Android.
At the same time, if translateZ does not take effect on Android, you can try to set other sibling nodes of the same parent node to `transform: translateZ(0)`.
:::

- **translate3d**

```
translate3d( <length> | <percentage> , <length> | <percentage> , <length> )
```

- **rotate**

```
rotate( [ <angle> | <zero> ] )
```

- **rotateZ**

```
rotateZ( [ <angle> | <zero> ] )
```

- **rotateX**

```
rotateX( [ <angle> | <zero> ] )
```

- **rotateY**

```
rotateY( [ <angle> | <zero> ] )
```

- **scale**

```
scale( <number> , <number>? )
```

- **scaleX**

```
scaleX( <number> )
```

- **scaleY**

```
scaleY( <number> )
```

- **skew**

```
skew( [ <angle> | <zero> ], [ <angle> | <zero> ] )
```

- **skewX**

```
skewX( [ <angle> | <zero> ] )
```

- **skewY**

```
skewY( [ <angle> | <zero> ] )
```

- **matrix**

```
matrix(a, b, c, d, tx, ty)
```

- **matrix3d**

```
matrix3d(a1, b1, c1, d1, a2, b2, c2, d2, a3, b3, c3, d3, a4, b4, c4, d4);
```

::: info

- `matrix(a, b, c, d, tx, ty)` is shorthand for `matrix3d(a, b, 0, 0, c, d, 0, 0, 0, 0, 1, 0, tx, ty, 0, 1)`.

- The `matrix3d()` function is specified with 16 arguments. These parameters are described in column-dominated order.
  - `a1`, `b1`, `c1`, `d1`
    define the first vector and are responsible for the X-axis scaling, rotation, and shear transformations;
  - `a2`, `b2`, `c2`, `d2`
    define the second vector and are responsible for the Y-axis scaling, rotation, and shear transformations;
  - `a3`, `b3`, `c3`, `d3`
    define the third vector and are responsible for the Z-axis scaling, rotation, and shear transformations;
  - `a4`, `b4`, `c4`, `d4`
    define the third vector, `a4`, `b4` and `c4` realize the translation transformation of x, y and z axes, and `d4` is generally set to 1, which is a value to keep the calculated weight stable.

:::

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Note

:::info

- If you want 3D effect when transform rotateX and rotateY rotate, you need to cooperate with [perspective property](/api/css/properties/perspective.md).

- On iOS, if there is jaggedness in rotate, anti-aliasing can be turned on by adding the `allow-edge-antialiasing` attribute to the node.

```jsx
<view allow-edge-antialiasing={true}></view>
```

- `iOS` will penetrate other sibling nodes in the same layer when rendering `rotateX/rotateY`. If you do not want this penetration effect, wrap the node with a Wrapper View so that it is not in the same layer as its sibling nodes. Since an empty Wrapper View will be optimized and deleted by layout only, without generating an actual node, please add a default `transform` property value to the Wrapper View (e.g. `transform: translate(0,0)`) to prevent it from being layout only.

:::

:::info

- The transform property is order-dependent, and the order of translate, rotate, and scale will affect the final rendering effect.

- The table below shows whether Lynx considers the order of transform in various scenarios:

| Scenario                    | Consideration of Transform Order |
| --------------------------- | -------------------------------- |
| Static transform in Android | Yes                              |
| Static transform in iOS     | Yes                              |
| Transform in Android        | Yes                              |
| Transform in iOS            | Yes                              |

- _What is a static transform: It refers to the transform property that is rendered directly without animation in CSS._

:::

## Difference from W3C

- not support rotate3d, scale3d

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transform`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transform)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-delay.md
---

# transition-delay

APISummary
## Introduction

The transition-delay CSS property specifies the duration to wait before starting a property's transition effect when its value changes.

## Examples

**This is an example below: css-api**

**Entry:** `src/transition-delay`
**Bundle:** `dist/transition-delay.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const TransitionDelay = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
        }}
      >
        <text>No delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "1s" as const,
        }}
      >
        <text>1s delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "2s" as const,
        }}
      >
        <text>2s delay animation</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDelay: "3s" as const,
        }}
      >
        <text>3s delay animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<TransitionDelay />);

```



## Syntax

```css
transition-delay: 2s;
transition-delay: 300ms;
```

### Values

- [`<time>`](/api/css/data-type/time.md)

- Default Value
  **0s**

## Formal definition

| Initial value | 0 |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
transition-delay:`<time>`;
```

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Note

:::info

- `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-delay`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-delay](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-delay)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-duration.md
---

# transition-duration

APISummary
## Introduction

The transition-duration CSS property sets the length of time a transition animation should take to complete. By default, the value is 0s, meaning that no animation will occur.

## Examples

**This is an example below: css-api**

**Entry:** `src/transition-duration`
**Bundle:** `dist/transition-duration.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "0.3s",
        }}
      >
        <text>0.3s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "1s",
        }}
      >
        <text>1s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "2s",
        }}
      >
        <text>2s duration transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionDuration: "3s",
        }}
      >
        <text>3s duration transition</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
transition-duration: 2s;
transition-duration: 300ms;
```

### Values

- [`<time>`](/api/css/data-type/time.md)

- Default Value
  **0s**

## Formal syntax

```css
transition-duration: <time>;
```

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-delay](/api/css/properties/transition-delay.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Note

:::info

- `duration` and `delay` require **units**, and it is strongly recommended to bring units.

:::

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-duration`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-duration](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-duration)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-property.md
---

# transition-property

APISummary
## Introduction

The transition-property CSS property sets the CSS properties to which a transition effect should be applied.

## Examples

**This is an example below: css-api**

**Entry:** `src/transition-property`
**Bundle:** `dist/transition-property.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view className="base opacityTransition" style={{ opacity: baseStyle.opacity }}>
        <text>Opacity animation</text>
      </view>
      <view className="base widthTransition" style={{ width: baseStyle.width }}>
        <text>Width animation</text>
      </view>
      <view className="base heightTransition" style={{ height: baseStyle.height }}>
        <text>Height animation</text>
      </view>
      <view className="base bgColorTransition" style={{ backgroundColor: baseStyle.backgroundColor }}>
        <text>Background color animation</text>
      </view>
      <view className="base transformTransition" style={{ transform: baseStyle.transform }}>
        <text>Transform animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
/* Keyword values */
transition-property: none;
transition-property: all;

/* <custom-ident> values */
transition-property: test_05;
transition-property: -specific;
transition-property: sliding-vertically;

/* Multiple values */
transition-property: test1, animation4;
transition-property: all, height, color;
```

### Values

- left
- right
- top
- bottom
- width
- height
- opacity
- background-color
- color
- transform
- transform-origin
- max-width
- min-width
- max-height
- min-height
- padding-left
- padding-right
- padding-top
- padding-bottom
- margin-left
- margin-right
- margin-top
- margin-bottom
- border-left-width
- border-right-width
- border-top-width
- border-bottom-width
- border-left-color
- border-right-color
- border-top-color
- border-bottom-color
- flex-basis
- flex-grow
- filter

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
transition-property =
  none                           |
  <single-transition-property>#

<single-transition-property> =
  all             |
  <custom-ident>
```

## More

- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-property`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-property](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-property)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition-timing-function.md
---

# transition-timing-function

APISummary
## Introduction

The transition-timing-function CSS property sets how intermediate values are calculated for CSS properties being affected by a transition effect.

## Examples

**This is an example below: css-api**

**Entry:** `src/transition-timing-function`
**Bundle:** `dist/transition-timing-function.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "linear",
        }}
      >
        <text>linear transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease",
        }}
      >
        <text>ease transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-in",
        }}
      >
        <text>ease-in transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-out",
        }}
      >
        <text>ease-out transition</text>
      </view>
      <view
        className="base allTransition"
        style={{
          opacity: baseStyle.opacity,
          width: baseStyle.width,
          height: baseStyle.height,
          backgroundColor: baseStyle.backgroundColor,
          transitionTimingFunction: "ease-in-out",
        }}
      >
        <text>ease-in-out transition</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
transition-timing-function: ease;
transition-timing-function: ease-in;
transition-timing-function: ease-out;
transition-timing-function: ease-in-out;
transition-timing-function: linear;
transition-timing-function: step-start;
transition-timing-function: step-end;

transition-timing-function: cubic-bezier(0.1, 0.7, 1, 0.1);
```

### Values

- `linear`

- `ease`

- `ease-in`

- `ease-out`

- `ease-in-out`

- `square-bezier()`

- `cubic-bezier()`

Default : **linear**

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
transition-timing-function:linear|ease|ease-in|ease-out|ease-in-out|square-bezier()|cubic-bezier();
```

## More

- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition](/api/css/properties/transition.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition-timing-function`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-timing-function](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-timing-function)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/transition.md
---

# transition

APISummary
## Introduction

The transition CSS property is a shorthand property for `transition-property`, `transition-duration`, `transition-timing-function`, and `transition-delay`.

## Example

**This is an example below: css-api**

**Entry:** `src/transition`
**Bundle:** `dist/transition.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const Transition = () => {
  const [flag, setFlag] = useState(false);

  const baseStyle = {
    opacity: flag ? "1" : "0.1" as const,
    width: flag ? "100px" : "200px",
    height: flag ? "100px" : "200px",
    backgroundColor: flag ? "blue" : "red",
    visibility: (flag ? "visible" : "hidden") as "visible" | "hidden",
    top: flag ? "0px" : "50px",
    right: flag ? "0px" : "50px",
    bottom: flag ? "0px" : "50px",
    left: flag ? "0px" : "50px",
    transform: flag ? "translateX(0px)" : "translateX(50px)" as const,
  };

  return (
    <scroll-view scroll-orientation="vertical" className="scroll">
      <view className="base" bindtap={() => setFlag(!flag)}>
        <text>Click to transition</text>
      </view>
      <view className="base opacityTransition" style={{ opacity: baseStyle.opacity }}>
        <text>opacity animation</text>
      </view>
      <view className="base widthTransition" style={{ width: baseStyle.width }}>
        <text>width animation</text>
      </view>
      <view className="base heightTransition" style={{ height: baseStyle.height }}>
        <text>height animation</text>
      </view>
      <view className="base bgColorTransition" style={{ backgroundColor: baseStyle.backgroundColor }}>
        <text>background-color animation</text>
      </view>
      <view className="base transformTransition" style={{ transform: baseStyle.transform }}>
        <text>transform animation</text>
      </view>
    </scroll-view>
  );
};

root.render(<Transition />);

```



## Syntax

```css
/* Apply to 1 property */
/* property name | duration */
transition: background-color 4s;

/* property name | duration | delay */
transition: opacity 4s 1s;

/* property name | duration | easing function */
transition: background-color 4s ease-in-out;

/* property name | duration | easing function | delay */
transition: background-color 4s ease-in-out 1s;

/* Apply to 2 properties */
transition:
  background-color 4s,
  opacity 4s;

/* Apply to all changed properties */
transition: all 0.5s ease-out;

/* Clear all transition animation.*/
transition: none;
```

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```css
transition: <transition-property> || <transition-duration> ||
  <transition-timing-function> || <transition-delay>;
```

## Transition Event

- [Transition Event](/api/lynx-api/event/animation-event.md)

## More

- [transition-property](/api/css/properties/transition-property.md)
- [transition-duration](/api/css/properties/transition-duration.md)
- [transition-delay](/api/css/properties/transition-delay.md)
- [transition-timing-function](/api/css/properties/transition-timing-function.md)
- [Animation Event](/api/lynx-api/event/animation-event.md)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.transition`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/vertical-align.md
---

# vertical-align

APISummary
## Introduction

The vertical-align property sets vertical alignment of inline element.

## Examples

**This is an example below: css-api**

**Entry:** `src/vertical-align`
**Bundle:** `dist/vertical-align.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";
import playImage from "../../resource/play.jpeg";

const VerticalAlign = () => {
  const containerStyle = {
    display: "linear" as const,
  };

  const titleStyle = {
    backgroundColor: "white",
  };

  const orangeContainerStyle = {
    lineHeight: "100px",
    backgroundColor: "orange",
  };

  const tomatoContainerStyle = {
    lineHeight: "100px",
    backgroundColor: "tomato",
  };

  const titleTextStyle = {
    fontSize: "25px",
  };

  const imageStyle = (align: string) => ({
    width: "20px",
    height: "20px",
    verticalAlign: align,
  });

  const textStyle = (align: string) => ({
    verticalAlign: align,
  });

  const viewStyle = (align: string) => ({
    width: "20px",
    height: "20px",
    backgroundColor: "yellow",
    verticalAlign: align,
  });

  return (
    <view className="intro" style={containerStyle} lynx-test-tag="container">
      <text style={titleStyle}>
        set vertical-align: middle,center,top,bottom,text-top,text-bottom,super,baseline,sub
      </text>
      <text style={orangeContainerStyle}>
        <text style={titleTextStyle}>inline-image:</text>

        <image src={playImage} style={imageStyle("middle")}></image>
        <image src={playImage} style={imageStyle("center")}></image>
        <image src={playImage} style={imageStyle("top")}></image>
        <image src={playImage} style={imageStyle("bottom")}></image>
        <image src={playImage} style={imageStyle("text-top")}></image>
        <image src={playImage} style={imageStyle("text-bottom")}></image>
        <image src={playImage} style={imageStyle("super")}></image>
        <image src={playImage} style={imageStyle("baseline")}></image>
        <image src={playImage} style={imageStyle("sub")}></image>
      </text>
      <text style={tomatoContainerStyle}>
        <text style={titleTextStyle}>inline-text:</text>
        <text style={textStyle("middle")}>xx</text>
        <text style={textStyle("center")}>xx</text>
        <text style={textStyle("top")}>xx</text>
        <text style={textStyle("bottom")}>xx</text>
        <text style={textStyle("text-top")}>xx</text>
        <text style={textStyle("text-bottom")}>xx</text>
        <text style={textStyle("super")}>xx</text>
        <text style={textStyle("baseline")}>xx</text>
        <text style={textStyle("sub")}>xx</text>
      </text>
      <text style={orangeContainerStyle}>
        <text style={titleTextStyle}>inline-view</text>
        <view style={viewStyle("middle")}></view>
        <view style={viewStyle("center")}></view>
        <view style={viewStyle("top")}></view>
        <view style={viewStyle("bottom")}></view>
        <view style={viewStyle("text-top")}></view>
        <view style={viewStyle("text-bottom")}></view>
        <view style={viewStyle("super")}></view>
        <view style={viewStyle("baseline")}></view>
        <view style={viewStyle("sub")}></view>
      </text>
    </view>
  );
};

root.render(<VerticalAlign />);

```



## Syntax

```css
vertical-align: 10px;
vertical-align: 50%;
vertical-align: baseline;
vertical-align: middle;
vertical-align: center;
vertical-align: top;
vertical-align: bottom;
vertical-align: text-top;
vertical-align: text-bottom;
vertical-align: super;
vertical-align: sub;
```

### Values

- `<length>`
  support `length` in Lynx,aligns the baseline of the element to the given length above the initial baseline,a negative value is allowed.

- `<percent>`
  Shift a percentage of the `line-height`,a negative value is allowed.

- `baseline`
  Aligns the baseline of element with the baseline of line.

- `middle`
  Get max x-height of all of text,aligns the middle of element with the position of half max x-height.

- `center`
  Aligns the middle of the element with the middle of line.

- `top`
  Aligns the top of the element with the top of line.

- `bottom`
  Aligns the bottom of the element with the bottom of line.

- `text-top`
  Get max ascent of all of text,aligns the top of element with the position of max ascent.

- `text-bottom`
  Get max descent of all of text,aligns the bottom of element with the position of max descent.

- `super`
  Upward shift 10% of the element's height.

- `sub`
  Downward shift 10% of the element's height.

- default value
  **baseline**

## Formal definition

| Initial value | baseline |
| Applies to | inline-text、inline-image、inline-view |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
<length> | <percent> | baseline | middle | center | top | bottom | text-top | text-bottom | super | sub
```

## Difference with Web

- [mdn:vertical-align](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align)

## Notes

- When the'text 'element nests the'view', the default text baseline is aligned to the bottom of the'view ', and the 'vertical-align-baseline' needs to be explicitly set on the'view 'to ensure that the text baseline is aligned to the'view' text baseline.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.vertical-align`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/vertical-align](https://developer.mozilla.org/zh-CN/docs/Web/CSS/vertical-align)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.6 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.6 | - |
| Clay iOS | 2.6 | - |
| Clay macOS | 2.6 | - |
| Clay Windows | 2.6 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/visibility.md
---

# visibility

APISummary
## Introduction

The visibility CSS property shows or hides an element without changing the layout of a document.

## Examples

**This is an example below: css-api**

**Entry:** `src/visibility`
**Bundle:** `dist/visibility.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

import image from "../../resource/lynx.png";

const Visibility = () => {
  const heightStyle = {
    height: "10px",
  };

  return (
    <scroll-view className="root" scroll-orientation="vertical">
      <view className="fixed_area">
        <image className="relative_image" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image visible" src={image}></image>
        <view style={heightStyle}></view>
        <image className="relative_image hidden" src={image}></image>
      </view>
    </scroll-view>
  );
};

root.render(<Visibility />);

```



## Syntax

```css
/* Keyword values */
visibility: visible;
visibility: hidden;
```

### Values

`visible`

The element box is visible.

`hidden`

The element box is invisible (not drawn), but still affects layout as normal. Looks like 'opacity: 0'.

## Formal definition

| Initial value | visible |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |


## Formal syntax

```
visibility =
  visible   |
  hidden
```

## Differences from Web

`collapse`、`inherit`、`initial`and`unset` are not supported.

When `visibility` is set to `hidden`, all subviews will be invisible, no matter what values their `visibility` are.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.visibility`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/visibility](https://developer.mozilla.org/zh-CN/docs/Web/CSS/visibility)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/white-space.md
---

# white-space

APISummary
## Introduction

`white-space`CSS property sets how white space inside an element is handled.。

## Examples

**This is an example below: css-api**

**Entry:** `src/white-space`
**Bundle:** `dist/white-space.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const WhiteSpace = () => {
  const containerStyle = {
    width: "100%",
    height: "100%",
    flexDirection: "column" as const,
  };

  const normalTextStyle = {
    className: "item normal",
  };

  const nowrapTextStyle = {
    className: "item nowrap",
  };

  const sampleText =
    "But ere she from the church-door stepped She smiled and told us why: 'It was a wicked woman's curse,' Quoth she, 'and what care I?' She smiled, and smiled, and passed it off Ere from the door she stept—";

  return (
    <view style={containerStyle}>
      <text className="title">white-space: normal</text>
      <text className="item normal">
        {sampleText}
      </text>

      <text className="title">white-space: nowrap</text>
      <text className="item nowrap">
        {sampleText}
      </text>
    </view>
  );
};

root.render(<WhiteSpace />);

```



## Syntax

```css
white-space: normal;

white-space: nowrap;
```

### Values

- `normal`
  **Default**
  No additional processing is performed on the text.

- `nowrap`
  Suppresses line breaks (text wrapping) within the source.

## Formal definition

| Initial value | normal |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
normal | nowrap
```

## Difference with Web

- Only support `normal` and `nowrap`

## Compatibility

**Compatibility Table**
**Query:** `css.properties.white-space`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/white-space](https://developer.mozilla.org/zh-CN/docs/Web/CSS/white-space)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/width.md
---

# width

APISummary
## Introduction

The `width` CSS property specifies the width of an element. By default, the property defines the width of the border area. If [`box-sizing`](/api/css/properties/box-sizing.md) is set to `content-box`, however, it instead determines the width of the content area.

The [`min-width`](/api/css/properties/min-width.md) and [`max-width`](/api/css/properties/max-width.md) properties override `width`.

## Examples

**This is an example below: css-api**

**Entry:** `src/width`
**Bundle:** `dist/width.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const Width = () => {
  const containerStyle = {
    display: "linear" as const,
    linearOrientation: "vertical" as const,
  };

  const borderBoxStyle = {
    width: "100px",
    border: "20px solid orange",
  };

  const contentBoxStyle = {
    width: "100px",
    border: "20px solid orange",
    boxSizing: "content-box" as const,
  };

  return (
    <view style={containerStyle}>
      <text style={borderBoxStyle}>
        border-box
      </text>
      <text style={contentBoxStyle}>
        content-box
      </text>
    </view>
  );
};

root.render(<Width />);

```



## Syntax

```css
/* <length> values */
width: 300px;
width: 25em;

/* <percentage> value */
width: 75%;

/* Keyword values */
width: max-content;
width: fit-content;
width: fit-content(20em);
width: auto;
```

### Values

- `auto`

  **Default value**. lynx will calculate and select a width for the specified element.

- `<length>`

  [`<length>`](/api/css/data-type/length.md) defines the width as a distance value.

- `<percentage>`

  Defines the width as a percentage of the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block)'s width.

- `max-content`

  The intrinsic preferred width.

- `fit-content`

  [`fit-content`](/api/css/data-type/fit-content.md) uses the computed size with the available space replaced by the specified argument.

## Formal definition

| Initial value | `auto` |
| Applies to | all elements |
| Inherited | no |
| Animatable | yes |
| Percentages | refer to the width of the containing block |


## Formal syntax

## Difference with the web

- By default, the property defines the width of the border area, while Web is `content area`.
- `min-content` is not supported.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.width`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/width](https://developer.mozilla.org/zh-CN/docs/Web/CSS/width)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/word-break.md
---

# word-break

APISummary
## Introduction

Used to specify how to break lines within a word.

## Examples

**This is an example below: css-api**

**Entry:** `src/word-break`
**Bundle:** `dist/word-break.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const WordBreak = () => {
  const normalBreakStyle = {
    overflow: "hidden",
    wordBreak: "normal",
  } as const;

  const breakAllStyle = {
    overflow: "hidden",
    wordBreak: "break-all",
  } as const;

  return (
    <view className="container">
      <text text-maxline="1" style={normalBreakStyle}>
        Hello, Lynx!Hello, Lynx!Hello, Lynx!
      </text>
      <text text-maxline="1" style={breakAllStyle}>
        Hello, Lynx!Hello, Lynx!Hello, Lynx!
      </text>
    </view>
  );
};

root.render(<WordBreak />);

```



## Syntax

```css
word-break: break-all;
word-break: normal;
```

### Values

- `normal`
  **Default value**. Use the default line break rule.

- `break-all`
  Lines can be interrupted in any character.

- `keep-all`
  Word breaks should not be used for Chinese/Japanese/Korean (CJK) text.

## Formal definition

| Initial value | normal |
| Applies to | text |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
normal | break-all | keep-all
```

## Difference with Web

- [mdn:word-break](https://developer.mozilla.org/en-US/docs/Web/CSS/word-break)

## Compatibility

**Compatibility Table**
**Query:** `css.properties.word-break`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/word-break](https://developer.mozilla.org/zh-CN/docs/Web/CSS/word-break)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/properties/z-index.md
---

# z-index

APISummary
## Introduction

The z-index CSS property sets the z-order of an element and its descendants or flex items. Overlapping elements with a larger z-index cover those with a smaller one.

:::info

If we want to generate [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context), you can add `z-index: 0` to an element. For example, make children follow the scroll by adding `z-index: 0` to the scroll-view

It is not recommended to use z-index in the direct children of list. This may affect the reuse of list. If you use z-index in the list item, the item should be a stacking context.

:::

## Examples

**This is an example below: css-api**

**Entry:** `src/z-index`
**Bundle:** `dist/z-index.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import "./index.scss";

const ZIndex = () => {
  const [indices, setIndices] = useState([2, 1, 0, -1, -2]);
  const [show, setShow] = useState(false);

  const containerStyle = {
    zIndex: 0,
    height: "280px",
  };

  const innerContainerStyle = {
    height: "100%",
  };

  const getBlockStyle = (index: number, color: string, top: string, left: string) => ({
    zIndex: indices[index],
    background: color,
    position: "absolute" as const,
    top,
    left,
  });

  const getTextStyle = (show: boolean) => ({
    top: show ? "0" : "80px",
  });

  const handleChange = () => {
    setIndices(show ? [2, 1, 0, -1, -2] : [-2, -1, 0, 1, 2]);
    setShow(!show);
  };

  return (
    <view className="main" bindtap={handleChange}>
      <view className="container" style={containerStyle}>
        <view className="container" style={innerContainerStyle}>
          <view className="block" style={getBlockStyle(0, "#2196F3", "10px", "10px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[0]}</text>
          </view>
          <view className="block" style={getBlockStyle(1, "#4CAF50", "50px", "50px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[1]}</text>
          </view>
          <view className="block" style={getBlockStyle(2, "#9C27B0", "90px", "90px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[2]}</text>
          </view>
          <view className="block" style={getBlockStyle(3, "#FF9800", "130px", "130px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[3]}</text>
          </view>
          <view className="block" style={getBlockStyle(4, "#E91E63", "170px", "170px")}>
            <text className="text" style={getTextStyle(show)}>z-index:{indices[4]}</text>
          </view>
        </view>
      </view>
    </view>
  );
};

root.render(<ZIndex />);

```



## Syntax

```css
z-index: 0;
z-index: 3;
z-index: 289;
z-index: -1;
```

### Values

- [`<number>`](/api/css/data-type/number.md)
  This integer is the stack level of the generated box in the current stacking context.

- Default value
  **auto**

## Formal definition

| Initial value | empty value |
| Applies to | all elements |
| Inherited | no |
| Animatable | no |


## Formal syntax

```
z-index = <integer>
```

## Difference between web

The default value of web is auto. Lynx determines whether it is a stacking context by setting z-index property.

## Compatibility

**Compatibility Table**
**Query:** `css.properties.z-index`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/z-index](https://developer.mozilla.org/zh-CN/docs/Web/CSS/z-index)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/at-rule.md
---

# Overview

## At-rules

### [@font-face](/api/css/at-rule/font-face.md)

- [Syntax](/api/css/at-rule/font-face.md#syntax)
- [Values](/api/css/at-rule/font-face.md#values)
- [Example](/api/css/at-rule/font-face.md#example)
- [Difference from W3C](/api/css/at-rule/font-face.md#difference-from-w3c)
- [Compatibility](/api/css/at-rule/font-face.md#compatibility)

### [@import](/api/css/at-rule/import.md)

- [Syntax](/api/css/at-rule/import.md#syntax)
- [Example](/api/css/at-rule/import.md#example)

### [@keyframes](/api/css/at-rule/keyframes.md)

- [Implementation on platform](/api/css/at-rule/keyframes.md#implementation-on-platform)
- [When properties are left out of some keyframes](/api/css/at-rule/keyframes.md#when-properties-are-left-out-of-some-keyframes)
- [Keyframe value](/api/css/at-rule/keyframes.md#keyframe-value)
- [Supported properties](/api/css/at-rule/keyframes.md#supported-properties)



---
url: /api/css/at-rule/font-face.md
---

# @font-face

APISummary
The `@font-face` CSS at-rule specifies a custom font with which to display text;
the font can be loaded from either a remote server or a locally-installed font
on the user's own computer.

## Syntax

```css
@font-face {
  [ font-family: <string>; ] ||
  [ src: url(<string>) | local(<string>); ]
}
```

## Values

### `font-family`

Specifies a name that will be used as the font face value for `font` or `font-family` properties.

### `src`

Use a comma-separated list to specify available fonts. Use `url()` function for remote fonts and Base64-encoded fonts.Use `local()` function for local fonts.

:::info
On Android:use local(file://absolute/path) for absolute font paths
On iOS:use local(font-name) for system-installed font names (e.g. local(xxx-light))
:::

:::caution
Supported font formats:

Android: TTF, OTF, TTC

iOS: TTF, OTF, WOFF (iOS 10+), WOFF2 (iOS 10+)
:::

## Example

**This is an example below: text**

**Entry:** `src/font_face`
**Bundle:** `dist/font_face.lynx.bundle` | Web: `dist/font_face.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { Component } from "@lynx-js/react";

import "./index.scss";

export default class FontFaceExample extends Component {
  render() {
    return (
      <view
        style={{
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          width: "100%",
        }}
      >
        <text>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Inter" }}>Whereas recognition of the inherent dignity</text>
        <text style={{ fontFamily: "Icon" }}>&#xEA01;</text>
      </view>
    );
  }
}
root.render(<FontFaceExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Difference from W3C

Not support font-style,font-weight and font-variant.

## Compatibility

**Compatibility Table**
**Query:** `css.at-rule.font-face`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/@font-face](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@font-face)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.0 | - |
| Clay iOS | 1.0 | - |
| Clay macOS | 1.0 | - |
| Clay Windows | 1.0 | - |
| Web | ✅ Yes | - |




---
url: /api/css/at-rule/import.md
---

# @import

The `@import` CSS at-rule is used to import style rules from other stylesheets.

## Syntax

```css
@import <string>;
```

See [string](/api/css/data-type/string.md) data type.

## Example

```css
@import 'custom.css';
@import './custom.css';
@import '/pages/card/index.css';
```



---
url: /api/css/at-rule/keyframes.md
---

# @keyframes

The `@keyframes` CSS at-rule controls the intermediate steps in a CSS animation sequence by defining styles for keyframes (or waypoints) along the animation sequence.
This gives more control over the intermediate steps of the animation sequence than `transitions`.

## Implementation on platform

Both Android and iOS use keyframes to animate, the difference is that the property changes caused by Android animation will actually act on the View, while the transform part of iOS is implemented using CATransform3D.

## When properties are left out of some keyframes

Properties that aren't specified in every keyframe are interpolated if possible — properties that can't be interpolated are dropped from the animation. For example:

```css
@keyframes identifier {
  0% {
    background-color: blue;
    opacity: 0;
  }
  30% {
    opacity: 0.3;
  }
  72% {
    background-color: yellow;
  }
  100% {
    opacity: 1;
    background-color: red;
  }
}
```

## Keyframe value

- `from` A starting offset of 0%.

- `to` An ending offset of 100%.

- [`<percentage>`](/api/css/data-type/percentage.md) A percentage of the time through the animation sequence at which the specified keyframe should occur.

## Supported properties

The `keyframes` animation supports the `left`, `right`, `top`, `bottom`, `width`, `height`,`opacity`, `background-color`, `color`, `transform`, `transform-origin`, `max-width`, `min-width`, `max-height`, `min-height`, `padding-left`, `padding-right`, `padding-top`, `padding-bottom`, `margin-left`, `margin-right`, `margin-top`, `margin-bottom`, `border-left-width`, `border-right-width`, `border-top-width`, `border-bottom-width`, `border-left-color`, `border-right-color`, `border-top-color`, `border-bottom-color`, `flex-basis`, `flex-grow`, `filter`.



---
url: /api/css/data-type.md
---

# Data Type

## Data types

### [`<angle>`](/api/css/data-type/angle.md)

- [Syntax](/api/css/data-type/angle.md#syntax)
- [Compatibility](/api/css/data-type/angle.md#compatibility)

### [`<color>`](/api/css/data-type/color.md)

- [Syntax](/api/css/data-type/color.md#syntax)
- [Compatibility](/api/css/data-type/color.md#compatibility)

### [`<fit-content>`](/api/css/data-type/fit-content.md)

- [Example](/api/css/data-type/fit-content.md#example)
- [Compatibility](/api/css/data-type/fit-content.md#compatibility)

### [`<gradient>`](/api/css/data-type/gradient.md)

- [Syntax](/api/css/data-type/gradient.md#syntax)
- [Compatibility](/api/css/data-type/gradient.md#compatibility)

### [`<length-percentage>`](/api/css/data-type/length-percentage.md)

- [Syntax](/api/css/data-type/length-percentage.md#syntax)
- [Compatibility](/api/css/data-type/length-percentage.md#compatibility)

### [`<length>`](/api/css/data-type/length.md)

- [Syntax](/api/css/data-type/length.md#syntax)
- [Units](/api/css/data-type/length.md#units)
- [Compatibility](/api/css/data-type/length.md#compatibility)

### [`<max-content>`](/api/css/data-type/max-content.md)

- [Example](/api/css/data-type/max-content.md#example)
- [Compatibility](/api/css/data-type/max-content.md#compatibility)

### [`<number>`](/api/css/data-type/number.md)

- [Examples](/api/css/data-type/number.md#examples)
- [Compatibility](/api/css/data-type/number.md#compatibility)

### [`<percentage>`](/api/css/data-type/percentage.md)

- [Examples](/api/css/data-type/percentage.md#examples)
- [Compatibility](/api/css/data-type/percentage.md#compatibility)

### [`<string>`](/api/css/data-type/string.md)

- [Syntax](/api/css/data-type/string.md#syntax)
- [Examples](/api/css/data-type/string.md#examples)
- [Compatibility](/api/css/data-type/string.md#compatibility)

### [`<time>`](/api/css/data-type/time.md)

- [Syntax](/api/css/data-type/time.md#syntax)
- [Examples](/api/css/data-type/time.md#examples)
- [Compatibility](/api/css/data-type/time.md#compatibility)



---
url: /api/css/data-type/angle.md
---

# `<angle>`

APISummary
The `<angle>` CSS data type represents an angle value expressed in degrees, radians, or turns. It is used, for example, in `<gradient>` and in some `transform` functions.

## Syntax

The `<angle>` data type consists of a `<number>` followed by one of the units listed below. As with all dimensions, there is no space between the unit literal and the number. The angle unit is optional after the number 0.

Optionally, it may be preceded by a single + or - sign. Positive numbers represent clockwise angles, while negative numbers represent counterclockwise angles. For static properties of a given unit, any angle can be represented by various equivalent values. For example, `90deg` equals `-270deg`, and `1turn` equals `4turn`.

### Units

- `deg` Represents an angle in degrees. One full circle is 360deg. Examples: `0deg`, `90deg`, `14.23deg`.

- `rad` Represents an angle in radians. One full circle is 2π radians which approximates to `6.2832rad`. `1rad` is 180/π degrees. Examples: `0rad`, `1.0708rad`, `6.2832rad`.

- `turn` Represents an angle in a number of turns. One full circle is 1turn. Examples: `0turn`, `0.25turn`, `1.2turn`.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.angle`

**Specifications:**
- [https://drafts.csswg.org/css-values/#angles](https://drafts.csswg.org/css-values/#angles)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;angle&gt;</code>




---
url: /api/css/data-type/color.md
---

# `<color>`

APISummary
The `<color>` CSS data type represents a color. A `<color>` may also include an alpha-channel transparency value, indicating how the color should composite with its background.

A `<color>` can be defined in any of the following ways:

Using a keyword (such as `blue` or `transparent`).
Using the `RGB cubic-coordinate system` (via the #-hexadecimal or the `rgb()` and `rgba()` functional notations).
Using the `HSL cylindrical-coordinate system` (via the `hsl()` and `hsla()` functional notations).

## Syntax

The `<color>` data type is specified using one of the options listed below.

### Named Color

Named colors are case-insensitive identifiers that represent a specific color, such as `red`, `blue`, `black`, or `lightseagreen`.

| Name                 | rgba function          | Live                                                                                                         |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| transparent          | rgba(0, 0, 0, 0)       | <div style={{ textAlign: 'center', margin: '-10px', backgroundColor: 'rgba(0, 0, 0, 0)' }}>transparent</div> |
| aliceblue            | rgba(240, 248, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 248, 255, 1)' }} />       |
| antiquewhite         | rgba(250, 235, 215, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 235, 215, 1)' }} />       |
| aqua                 | rgba(0, 255, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 255, 1)' }} />         |
| aquamarine           | rgba(127, 255, 212, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(127, 255, 212, 1)' }} />       |
| azure                | rgba(240, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 255, 255, 1)' }} />       |
| beige                | rgba(245, 245, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 245, 220, 1)' }} />       |
| bisque               | rgba(255, 228, 196, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 196, 1)' }} />       |
| black                | rgba(0, 0, 0, 1)       | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 0, 1)' }} />             |
| blanchedalmond       | rgba(255, 235, 205, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 235, 205, 1)' }} />       |
| blue                 | rgba(0, 0, 255, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 255, 1)' }} />           |
| blueviolet           | rgba(138, 43, 226, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(138, 43, 226, 1)' }} />        |
| brown                | rgba(165, 42, 42, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(165, 42, 42, 1)' }} />         |
| burlywood            | rgba(222, 184, 135, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(222, 184, 135, 1)' }} />       |
| cadetblue            | rgba(95, 158, 160, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(95, 158, 160, 1)' }} />        |
| chartreuse           | rgba(127, 255, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(127, 255, 0, 1)' }} />         |
| chocolate            | rgba(210, 105, 30, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(210, 105, 30, 1)' }} />        |
| coral                | rgba(255, 127, 80, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 127, 80, 1)' }} />        |
| cornflowerblue       | rgba(100, 149, 237, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(100, 149, 237, 1)' }} />       |
| cornsilk             | rgba(255, 248, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 248, 220, 1)' }} />       |
| crimson              | rgba(220, 20, 60, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(220, 20, 60, 1)' }} />         |
| cyan                 | rgba(0, 255, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 255, 1)' }} />         |
| darkblue             | rgba(0, 0, 139, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 139, 1)' }} />           |
| darkcyan             | rgba(0, 139, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 139, 139, 1)' }} />         |
| darkgoldenrod        | rgba(184, 134, 11, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(184, 134, 11, 1)' }} />        |
| darkgray             | rgba(169, 169, 169, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(169, 169, 169, 1)' }} />       |
| darkgreen            | rgba(0, 100, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 100, 0, 1)' }} />           |
| darkgrey             | rgba(169, 169, 169, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(169, 169, 169, 1)' }} />       |
| darkkhaki            | rgba(189, 183, 107, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(189, 183, 107, 1)' }} />       |
| darkmagenta          | rgba(139, 0, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 0, 139, 1)' }} />         |
| darkolivegreen       | rgba(85, 107, 47, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(85, 107, 47, 1)' }} />         |
| darkorange           | rgba(255, 140, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 140, 0, 1)' }} />         |
| darkorchid           | rgba(153, 50, 204, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(153, 50, 204, 1)' }} />        |
| darkred              | rgba(139, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 0, 0, 1)' }} />           |
| darksalmon           | rgba(233, 150, 122, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(233, 150, 122, 1)' }} />       |
| darkseagreen         | rgba(143, 188, 143, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(143, 188, 143, 1)' }} />       |
| darkslateblue        | rgba(72, 61, 139, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(72, 61, 139, 1)' }} />         |
| darkslategray        | rgba(47, 79, 79, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(47, 79, 79, 1)' }} />          |
| darkslategrey        | rgba(47, 79, 79, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(47, 79, 79, 1)' }} />          |
| darkturquoise        | rgba(0, 206, 209, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 206, 209, 1)' }} />         |
| darkviolet           | rgba(148, 0, 211, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(148, 0, 211, 1)' }} />         |
| deeppink             | rgba(255, 20, 147, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 20, 147, 1)' }} />        |
| deepskyblue          | rgba(0, 191, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 191, 255, 1)' }} />         |
| dimgray              | rgba(105, 105, 105, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(105, 105, 105, 1)' }} />       |
| dimgrey              | rgba(105, 105, 105, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(105, 105, 105, 1)' }} />       |
| dodgerblue           | rgba(30, 144, 255, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(30, 144, 255, 1)' }} />        |
| firebrick            | rgba(178, 34, 34, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(178, 34, 34, 1)' }} />         |
| floralwhite          | rgba(255, 250, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 240, 1)' }} />       |
| forestgreen          | rgba(34, 139, 34, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(34, 139, 34, 1)' }} />         |
| fuchsia              | rgba(255, 0, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 255, 1)' }} />         |
| gainsboro            | rgba(220, 220, 220, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(220, 220, 220, 1)' }} />       |
| ghostwhite           | rgba(248, 248, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(248, 248, 255, 1)' }} />       |
| gold                 | rgba(255, 215, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 215, 0, 1)' }} />         |
| goldenrod            | rgba(218, 165, 32, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(218, 165, 32, 1)' }} />        |
| gray                 | rgba(128, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 128, 1)' }} />       |
| green                | rgba(0, 128, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 128, 0, 1)' }} />           |
| greenyellow          | rgba(173, 255, 47, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(173, 255, 47, 1)' }} />        |
| grey                 | rgba(128, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 128, 1)' }} />       |
| honeydew             | rgba(240, 255, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 255, 240, 1)' }} />       |
| hotpink              | rgba(255, 105, 180, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 105, 180, 1)' }} />       |
| indianred            | rgba(205, 92, 92, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(205, 92, 92, 1)' }} />         |
| indigo               | rgba(75, 0, 130, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(75, 0, 130, 1)' }} />          |
| ivory                | rgba(255, 255, 240, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 240, 1)' }} />       |
| khaki                | rgba(240, 230, 140, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 230, 140, 1)' }} />       |
| lavender             | rgba(230, 230, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(230, 230, 250, 1)' }} />       |
| lavenderblush        | rgba(255, 240, 245, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 240, 245, 1)' }} />       |
| lawngreen            | rgba(124, 252, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(124, 252, 0, 1)' }} />         |
| lemonchiffon         | rgba(255, 250, 205, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 205, 1)' }} />       |
| lightblue            | rgba(173, 216, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(173, 216, 230, 1)' }} />       |
| lightcoral           | rgba(240, 128, 128, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(240, 128, 128, 1)' }} />       |
| lightcyan            | rgba(224, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(224, 255, 255, 1)' }} />       |
| lightgoldenrodyellow | rgba(250, 250, 210, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 250, 210, 1)' }} />       |
| lightgray            | rgba(211, 211, 211, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(211, 211, 211, 1)' }} />       |
| lightgreen           | rgba(144, 238, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(144, 238, 144, 1)' }} />       |
| lightgrey            | rgba(211, 211, 211, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(211, 211, 211, 1)' }} />       |
| lightpink            | rgba(255, 182, 193, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 182, 193, 1)' }} />       |
| lightsalmon          | rgba(255, 160, 122, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 160, 122, 1)' }} />       |
| lightseagreen        | rgba(32, 178, 170, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(32, 178, 170, 1)' }} />        |
| lightskyblue         | rgba(135, 206, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(135, 206, 250, 1)' }} />       |
| lightslategray       | rgba(119, 136, 153, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(119, 136, 153, 1)' }} />       |
| lightslategrey       | rgba(119, 136, 153, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(119, 136, 153, 1)' }} />       |
| lightsteelblue       | rgba(176, 196, 222, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(176, 196, 222, 1)' }} />       |
| lightyellow          | rgba(255, 255, 224, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 224, 1)' }} />       |
| lime                 | rgba(0, 255, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 0, 1)' }} />           |
| limegreen            | rgba(50, 205, 50, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(50, 205, 50, 1)' }} />         |
| linen                | rgba(250, 240, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 240, 230, 1)' }} />       |
| magenta              | rgba(255, 0, 255, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 255, 1)' }} />         |
| maroon               | rgba(128, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 0, 0, 1)' }} />           |
| mediumaquamarine     | rgba(102, 205, 170, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(102, 205, 170, 1)' }} />       |
| mediumblue           | rgba(0, 0, 205, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 205, 1)' }} />           |
| mediumorchid         | rgba(186, 85, 211, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(186, 85, 211, 1)' }} />        |
| mediumpurple         | rgba(147, 112, 219, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(147, 112, 219, 1)' }} />       |
| mediumseagreen       | rgba(60, 179, 113, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(60, 179, 113, 1)' }} />        |
| mediumslateblue      | rgba(123, 104, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(123, 104, 238, 1)' }} />       |
| mediumspringgreen    | rgba(0, 250, 154, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 250, 154, 1)' }} />         |
| mediumturquoise      | rgba(72, 209, 204, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(72, 209, 204, 1)' }} />        |
| mediumvioletred      | rgba(199, 21, 133, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(199, 21, 133, 1)' }} />        |
| midnightblue         | rgba(25, 25, 112, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(25, 25, 112, 1)' }} />         |
| mintcream            | rgba(245, 255, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 255, 250, 1)' }} />       |
| mistyrose            | rgba(255, 228, 225, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 225, 1)' }} />       |
| moccasin             | rgba(255, 228, 181, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 228, 181, 1)' }} />       |
| navajowhite          | rgba(255, 222, 173, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 222, 173, 1)' }} />       |
| navy                 | rgba(0, 0, 128, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 0, 128, 1)' }} />           |
| oldlace              | rgba(253, 245, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(253, 245, 230, 1)' }} />       |
| olive                | rgba(128, 128, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 128, 0, 1)' }} />         |
| olivedrab            | rgba(107, 142, 35, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(107, 142, 35, 1)' }} />        |
| orange               | rgba(255, 165, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 165, 0, 1)' }} />         |
| orangered            | rgba(255, 69, 0, 1)    | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 69, 0, 1)' }} />          |
| orchid               | rgba(218, 112, 214, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(218, 112, 214, 1)' }} />       |
| palegoldenrod        | rgba(238, 232, 170, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(238, 232, 170, 1)' }} />       |
| palegreen            | rgba(152, 251, 152, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(152, 251, 152, 1)' }} />       |
| paleturquoise        | rgba(175, 238, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(175, 238, 238, 1)' }} />       |
| palevioletred        | rgba(219, 112, 147, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(219, 112, 147, 1)' }} />       |
| papayawhip           | rgba(255, 239, 213, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 239, 213, 1)' }} />       |
| peachpuff            | rgba(255, 218, 185, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 218, 185, 1)' }} />       |
| peru                 | rgba(205, 133, 63, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(205, 133, 63, 1)' }} />        |
| pink                 | rgba(255, 192, 203, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 192, 203, 1)' }} />       |
| plum                 | rgba(221, 160, 221, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(221, 160, 221, 1)' }} />       |
| powderblue           | rgba(176, 224, 230, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(176, 224, 230, 1)' }} />       |
| purple               | rgba(128, 0, 128, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(128, 0, 128, 1)' }} />         |
| red                  | rgba(255, 0, 0, 1)     | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 0, 0, 1)' }} />           |
| rosybrown            | rgba(188, 143, 143, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(188, 143, 143, 1)' }} />       |
| royalblue            | rgba(65, 105, 225, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(65, 105, 225, 1)' }} />        |
| saddlebrown          | rgba(139, 69, 19, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(139, 69, 19, 1)' }} />         |
| salmon               | rgba(250, 128, 114, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(250, 128, 114, 1)' }} />       |
| sandybrown           | rgba(244, 164, 96, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(244, 164, 96, 1)' }} />        |
| seagreen             | rgba(46, 139, 87, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(46, 139, 87, 1)' }} />         |
| seashell             | rgba(255, 245, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 245, 238, 1)' }} />       |
| sienna               | rgba(160, 82, 45, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(160, 82, 45, 1)' }} />         |
| silver               | rgba(192, 192, 192, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(192, 192, 192, 1)' }} />       |
| skyblue              | rgba(135, 206, 235, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(135, 206, 235, 1)' }} />       |
| slateblue            | rgba(106, 90, 205, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(106, 90, 205, 1)' }} />        |
| slategray            | rgba(112, 128, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(112, 128, 144, 1)' }} />       |
| slategrey            | rgba(112, 128, 144, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(112, 128, 144, 1)' }} />       |
| snow                 | rgba(255, 250, 250, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 250, 250, 1)' }} />       |
| springgreen          | rgba(0, 255, 127, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 255, 127, 1)' }} />         |
| steelblue            | rgba(70, 130, 180, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(70, 130, 180, 1)' }} />        |
| tan                  | rgba(210, 180, 140, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(210, 180, 140, 1)' }} />       |
| teal                 | rgba(0, 128, 128, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(0, 128, 128, 1)' }} />         |
| thistle              | rgba(216, 191, 216, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(216, 191, 216, 1)' }} />       |
| tomato               | rgba(255, 99, 71, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 99, 71, 1)' }} />         |
| turquoise            | rgba(64, 224, 208, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(64, 224, 208, 1)' }} />        |
| violet               | rgba(238, 130, 238, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(238, 130, 238, 1)' }} />       |
| wheat                | rgba(245, 222, 179, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 222, 179, 1)' }} />       |
| white                | rgba(255, 255, 255, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 255, 1)' }} />       |
| whitesmoke           | rgba(245, 245, 245, 1) | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(245, 245, 245, 1)' }} />       |
| yellow               | rgba(255, 255, 0, 1)   | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(255, 255, 0, 1)' }} />         |
| yellowgreen          | rgba(154, 205, 50, 1)  | <div style={{ padding: '17.5px 90px', margin: '-10px', backgroundColor: 'rgba(154, 205, 50, 1)' }} />        |

### RGB Color Model

`RGB` colors can be expressed through both hexadecimal (prefixed with #) and functional (`rgb()`, `rgba()`) notations.

#### Syntax

- hexadecimal: `#RGB[A]` or `#RRGGBB[AA]`
  `R` (red), `G` (green), `B` (blue), and `A` (alpha) are hexadecimal characters (0-9, A-F). `A` is optional. For example, `#ff0000` is equivalent to `#ff0000ff`. The three-digit notation (`#RGB`) is a shorter version of the six-digit form (`#RRGGBB`). For example, `#f09` is the same color as `#ff0099`. Likewise, the four-digit RGB notation (`#RGBA`) is a shorter version of the eight-digit form (`#RRGGBBAA`). For example, `#0f38` is the same color as `#00ff3388`.

- `rgb()` or `rgba()`
  `R` (red), `G` (green), and `B` (blue) can be either [`<number>`](/api/css/data-type/number.md)s or [`<percentage>`](/api/css/data-type/percentage.md)s, where the number `255` corresponds to `100%`. `A` (alpha) can be a [`<number>`](/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/api/css/data-type/percentage.md), where the number `1` corresponds to `100%` (full opacity).

### HSL Color Model

The HSL color model defines a given color according to its hue, saturation, and lightness components. An optional alpha component represents the color's transparency.

#### Syntax

HSL colors are expressed through the functional `hsl()` and `hsla()` notations.

`hsl()` or `hsla()`:`hsl[a](H, S, L[, A])`

- `H` (hue) is an [`<angle>`](/api/css/data-type/angle.md) of the color circle given in `deg`s, `rad`s, `grad`s. When written as a unitless [`<number>`](/api/css/data-type/number.md), it is interpreted as degrees. By definition, red=0deg=360deg, with the other colors spread around the circle, so green=120deg, blue=240deg, etc.
- `S` (saturation) and `L` (lightness) are percentages. `100%` **saturation** is completely saturated, while `0%` is completely unsaturated (gray). `100%` **lightness** is white, `0%` lightness is black, and `50%` lightness is "normal".
- `A` (alpha) can be a [`<number>`](/api/css/data-type/number.md) between 0 and 1, or a [`<percentage>`](/api/css/data-type/percentage.md), where the number `1` corresponds to `100%` (full opacity).

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.color`

**Specifications:**
- [https://drafts.csswg.org/css-values/#colors](https://drafts.csswg.org/css-values/#colors)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay macOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;color&gt;</code>




---
url: /api/css/data-type/fit-content.md
---

# `<fit-content>`

APISummary
`fit-content()` currently supports for [`width`], [`height`] and [grid layout] properties ([`grid-template-columns`], [`grid-template-rows`], [`grid-auto-columns`], and [`grid-auto-rows`]).

When used as a [`width`] or [`height`], take the larger value between the following two: the maximum size of the content and the smaller value specified in `fit-content()`.

`fit-content` is equivalent to `fit-content(auto)`, and the specified value of auto is the same as the corresponding axis length of the parent element.

## Example

```css
width: fit-content;
height: fit-content(200px);
grid-template-columns: fit-content;
grid-template-rows: fit-content;
grid-auto-columns: fit-content;
grid-auto-rows: fit-content;
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.fit-content`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content](https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | targetSdkVersion 2.0 | - |
| iOS | targetSdkVersion 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |


[`width`]: /api/css/properties/width.md

[`height`]: /api/css/properties/height.md

[`grid-template-columns`]: /api/css/properties/grid-template-columns.md

[`grid-template-rows`]: /api/css/properties/grid-template-rows.md

[`grid-auto-columns`]: /api/css/properties/grid-auto-columns.md

[`grid-auto-rows`]: /api/css/properties/grid-auto-columns.md

[grid layout]: /guide/ui/layout/grid-layout.md



---
url: /api/css/data-type/gradient.md
---

# `<gradient>`

APISummary
The `<gradient>` CSS data type is a special type of `<image>` that consists of a progressive transition between two or more colors.

## Syntax

The `<gradient>` data type is defined with one of the function types listed below.

### Linear gradient

Linear gradients transition colors progressively along an imaginary line. They are generated with the `linear-gradient()` function.

```css
/* A gradient tilted 45 degrees, starting blue and finishing red */
linear-gradient(45deg, blue, red);
/* A gradient going from the bottom right to the top left corner, starting blue and finishing red */
linear-gradient(to left top, blue, red);
/* Color stop: A gradient going from the bottom to top, starting blue, turning green at 40% of its length, and finishing red */
linear-gradient(0deg, blue, green 40%, red);
```

#### Formal Syntax

```
linear-gradient([ <angle> | to <side-or-corner> ,]? <color-stop> [ , <color-stop> ]+ )
```

#### Values

- `<side-or-corner>`
  The position of the gradient line's starting point. If specified, it consists of the word `to` and up to two keywords: one indicates the horizontal side (`left` or `right`), and the other the vertical side (`top` or `bottom`). The order of the side keywords does not matter. If unspecified, it defaults to `to bottom`. <br />
  The values `to top`, `to bottom`, `to left`, and `to right` are equivalent to the angles `0deg`, `180deg`, `270deg`, and `90deg`, respectively. The other values are translated into an angle.

- `<angle>`
  The gradient line's angle of direction. A value of `0deg` is equivalent to `to top`; increasing values rotate clockwise from there.

- `<color-stop>`
  A color-stop's [`<color>`](/api/css/data-type/color.md) value, followed by at most one optional stop position, a [`<percentage>`](/api/css/data-type/percentage.md) or `<number>` value along the gradient's axis. Note that unlike the Web standard, Lynx does not support multiple positions after a single color. If a unitless `<number>` is used, it is treated as a percentage by multiplying it by 100 (e.g., `0.5` is treated as `50%`). Color stops without an explicit position are distributed linearly between known positions.

### Radial Gradient

Radial gradients transition colors progressively from a center point (origin). They are generated with the `radial-gradient()` function.

```css
radial-gradient(#e66465, #9198e5);

radial-gradient(closest-side, #3f87a6, #ebf8e1, #f69d3c);

radial-gradient(circle at 100%, #333, #333 50%, #eee 75%, #333 75%);

radial-gradient(ellipse at top, #e66465, transparent);
```

#### Formal Syntax

```
radial-gradient(
  [ [ circle || <length> ]                         [ at <position> ]? , |
    [ ellipse || [ <length> | <percentage> ]{2} ]  [ at <position> ]? , |
    [ [ circle | ellipse ] || <extent-keyword> ] [at <position> ]? , |
    at <position> ,
  ]?
  <color-stop> [ , <color-stop> ]+
)
```

#### Values

- `<position>`
  The position of the gradient, interpreted in the same way as [`background-position`](/api/css/properties/background-position.md) or [`transform-origin`](/api/css/properties/transform-origin.md). If unspecified, it defaults to center.

- `<ending-shape>`
  The gradient's ending-shape. The value can be `circle` (meaning that the gradient's shape is a circle with a constant radius) or `ellipse` (meaning that the shape is an axis-aligned ellipse). If unspecified, it defaults to `ellipse`.

- `<size>`
  Determines the size of the gradient's ending shape. <br />
  If omitted it defaults to farthest-corner. It can be given explicitly or by keyword. For the purpose of the keyword definitions, consider the gradient box edges as extending infinitely in both directions, rather than being finite line segments.

  | **Keyword**       | **Description**                                                                                                                                                                 |
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `closest-side`    | The gradient's ending shape meets the side of the box closest to its center (for circles) or meets both the vertical and horizontal sides closest to the center (for ellipses). |
  | `closest-corner`  | The gradient's ending shape is sized so that it exactly meets the closest corner of the box from its center.                                                                    |
  | `farthest-side`   | Similar to `closest-side`, except the ending shape is sized to meet the side of the box farthest from its center (or vertical and horizontal sides).                            |
  | `farthest-corner` | The default value, the gradient's ending shape is sized so that it exactly meets the farthest corner of the box from its center.                                                |

- `<color-stop>`
  Same as `linear-gradient`

### Conic Gradient

Conic gradients transition colors progressively around a center point (origin). They are generated with the `conic-gradient()` function.

```css
/* Starting from 0deg (default), center at 50% 50% (default) */
conic-gradient(red, blue);
/* Starting from 45deg */
conic-gradient(from 45deg, red, blue);
/* Center at top left */
conic-gradient(at top left, red, blue);
/* Starting from 90deg, center at 20% 30% */
conic-gradient(from 90deg at 20% 30%, red 0%, blue 50%, green 100%);
```

#### Formal Syntax

```
conic-gradient(
  [ [ from <angle> ]? [ at <position> ]? , ]?
  <color-stop-list>
)
```

#### Values

- `<angle>`
  The starting angle of the gradient, preceded by the keyword `from`. The default value is `0deg`. Supported units include `deg`, `grad`, `rad`, and `turn`. Unitless numbers are only accepted if the value is `0` or if the `enable_transform_legacy` compatibility mode is enabled.

- `<position>`
  The center point of the gradient, preceded by the keyword `at`. The default value is `50% 50%` (`center`). It supports one or two values, using the same syntax as [`background-position`](/api/css/properties/background-position.md):
  - Keywords: `left`, `center`, `right`, `top`, `bottom`.
  - Length or percentage: `<length-percentage>` (e.g., `20px`, `30%`).

- `<color-stop-list>`
  A comma-separated list of at least two color stops. Each color stop consists of a `<color>` followed by at most one optional position (`<percentage>` or `<number>`). Note that unlike the Web standard, Lynx does not support multiple positions after a single color. If a unitless `<number>` is used, it is treated as a percentage by multiplying it by 100 (e.g., `0.5` is treated as `50%`). Color stops without an explicit position are distributed linearly between known positions.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.gradient`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content](https://drafts.csswg.org/css-sizing-4/#valdef-width-fit-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;gradient&gt;</code>




---
url: /api/css/data-type/length-percentage.md
---

# `<length-percentage>`

APISummary
Equivalent to \[ [`<length>`] ｜ [`<percentage>`] ] with [`<percentage>`] will resolve to a [`<length>`]. Additionally support `calc()` math expression.

## Syntax

A `<length-percentage>` can be a [`<length>`], a [`<percentage>`] or a `calc()` math expression. The `calc()` function is a math function that allows basic arithmetic to be performed on numerical values, using addition (+), subtraction (-), multiplication (\*), division (/), and parentheses.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.length-percentage`

**Specifications:**
- [https://drafts.csswg.org/css-values/#typedef-length-percentage](https://drafts.csswg.org/css-values/#typedef-length-percentage)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;length-percentage&gt;</code>


[`<percentage>`]: /api/css/data-type/percentage.md

[`<length>`]: /api/css/data-type/length.md



---
url: /api/css/data-type/length.md
---

# `<length>`

APISummary
The `<length>` CSS data type represents a distance value.

## Syntax

The `<length>` data type consists of a `<number>` followed by one of the units listed below. As with all CSS dimensions, there is no space between the number and the unit literal. Specifying the length unit is optional if the number is 0.

_Without units other than 0 is not supported_

## Units

#### Relative length units

Relative lengths represent a measurement in terms of some other distance. Depending on the unit, this distance can be the size of a specific character, the line height, or the size of the `viewport`.

- `rpx`: Responsive pixel. It can be adapted according to the screen width. The specified screen width is `750rpx`. For example, on iPhone6's the screen width is `375px`, and there are `750` physical pixels in total, then `750rpx = 375px = 750ppx`, `1rpx = 0.5px = 1ppx`.

- `rem`: This unit represents the `font-size` of the root element. When used on the `font-size` of the root element, it represents its initial value.

- `em`: This unit represents the calculated value of the element's `font-size`. If used in the `font-size` property itself, it represents the `font-size` value inherited by the element.

- `vh`: `1vh` is 1% of the viewport height.

- `vw`: `1vw` is 1% of the viewport width.

#### Absolute length units

Absolute length units represent a physical measurement when the physical properties of the output medium are known, such as for print layout. This is done by anchoring one of the units to a physical unit and then defining the others relative to it. The anchoring is done differently for low-resolution devices and high-resolution devices.

- `px`: Pixel, equal to a physical pixel multiplied by pixel density, equivalent to `pt` on iOS or `dp` on Android. For high-resolution screens, one CSS pixel implies multiple device pixels. E.g: `1px` = `1/96th of 1in`.

- `ppx`: Physical pixel, equal to the size of an actual pixel on the screen.

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.length`

**Specifications:**
- [https://drafts.csswg.org/css-values/#lengths](https://drafts.csswg.org/css-values/#lengths)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;length&gt;</code>




---
url: /api/css/data-type/max-content.md
---

# `<max-content>`

APISummary
`max-content` currently supports for [`width`], [`height`] and [grid layout] properties ([`grid-template-columns`], [`grid-template-rows`], [`grid-auto-columns`], and [`grid-auto-rows`]).

## Example

```css
width: max-content;
grid-template-columns: max-content;
grid-template-rows: max-content;
grid-auto-columns: max-content;
grid-auto-rows: max-content;
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.max-content`

**Specifications:**
- [https://drafts.csswg.org/css-sizing-3/#valdef-width-max-content](https://drafts.csswg.org/css-sizing-3/#valdef-width-max-content)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | targetSdkVersion 2.0 | - |
| iOS | targetSdkVersion 2.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | ❌ No | - |
| Clay iOS | ❌ No | - |
| Clay Windows | ❌ No | - |
| Clay macOS | ❌ No | - |
| Web | ✅ Yes | - |


[`width`]: /api/css/properties/width.md

[`height`]: /api/css/properties/height.md

[`grid-template-columns`]: /api/css/properties/grid-template-columns.md

[`grid-template-rows`]: /api/css/properties/grid-template-rows.md

[`grid-auto-columns`]: /api/css/properties/grid-auto-columns.md

[`grid-auto-rows`]: /api/css/properties/grid-auto-columns.md

[grid layout]: /guide/ui/layout/grid-layout.md



---
url: /api/css/data-type/number.md
---

# `<number>`

APISummary
The `<number>` CSS data type represents a number, being either an integer or a number with a fractional component.

## Examples

### Valid numbers

```css
12          A raw <integer> is also a <number>.
4.01        Positive fraction
-456.8      Negative fraction
0.0         Zero
+0.0        Zero, with a leading +
-0.0        Zero, with a leading -
.60         Fractional number without a leading zero
10e3        Scientific notation
-3.4e-2     Complicated scientific notation
```

### Invalid numbers

```css
12.         Decimal points must be followed by at least one digit.
+-12.2      Only one leading +/- is allowed.
12.1.1      Only one decimal point is allowed.
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.number`

**Specifications:**
- [https://drafts.csswg.org/css-values/#number](https://drafts.csswg.org/css-values/#number)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;number&gt;</code>




---
url: /api/css/data-type/percentage.md
---

# `<percentage>`

APISummary
The `<percentage>` CSS data type represents a percentage value. It is often used to define a size as relative to an element's parent object. Numerous properties can use percentages, such as width, height, margin, padding, and font-size.

The `<percentage>` data type consists of a [`<number>`](/api/css/data-type/number.md) followed by the percentage sign (%). As with all CSS dimensions, there is no space between the symbol and the number.

## Examples

```tsx
<view>
  <text style={{ width: '50%', marginLeft: '20%', backgroundColor: '#00FF00' }}>
    Width: 50%, Left margin: 20%
  </text>
  <text style={{ width: '30%', marginLeft: '60%', backgroundColor: '#FF0000' }}>
    Width: 30%, Left margin: 60%
  </text>
</view>
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.percentage`

**Specifications:**
- [https://drafts.csswg.org/css-values/#percentages](https://drafts.csswg.org/css-values/#percentages)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;percentage&gt;</code>




---
url: /api/css/data-type/string.md
---

# `<string>`

APISummary
The `<string>` CSS data type represents a sequence of characters.

## Syntax

The `<string>` data type is composed of any number of [Unicode](https://en.wikipedia.org/wiki/Unicode) characters surrounded by either double (`"`) or single (`'`) quotes.

Most characters can be represented literally. All characters can also be represented with their respective [Unicode code points](https://en.wikipedia.org/wiki/Unicode#Code_point_planes_and_blocks) in hexadecimal, in which case they are preceded by a backslash (`\`). For example, `\22` represents a double quote, `\27` a single quote (`'`), and `\A9` the copyright symbol (`©`).

Importantly, certain characters which would otherwise be invalid can be escaped with a backslash. These include double quotes when used inside a double-quoted string, single quotes when used inside a single-quoted string, and the backslash itself. For example, `\\` will create a single backslash.

To output new lines, you must escape them with a line feed character such as `\A` or `\00000A`. In your code, however, strings can span multiple lines, in which case each new line must be escaped with a `\` as the last character of the line.

## Examples

```css
/* Simple strings */
"This string is demarcated by double quotes."
'This string is demarcated by single quotes.'

/* Character escaping */
"This is a string with \" an escaped double quote."
"This string also has \22 an escaped double quote."
'This is a string with \' an escaped single quote.'
'This string also has \27 an escaped single quote.'
"This is a string with \\ an escaped backslash."
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.string`

**Specifications:**
- [https://drafts.csswg.org/css-values/#string](https://drafts.csswg.org/css-values/#string)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;string&gt;</code>




---
url: /api/css/data-type/time.md
---

# `<time>`

APISummary
The `<time>` CSS data type represents a time value expressed in seconds or milliseconds. It is used in `animation`, `transition`, and related properties.

## Syntax

The `<time>` data type consists of a `<number>` followed by one of the units listed below. Optionally, it may be preceded by a single `+` or `-` sign. As with all dimensions, there is no space between the unit literal and the number.

### Units

- `s` Represents a time in seconds. Examples: `0s`, `1.5s`, `-60s`.

- `ms` Represents a time in milliseconds. Examples: `0ms`, `150.25ms`, `-60000ms`.

## Examples

### Valid times

```
12s         Positive integer
-456ms      Negative integer
4.3ms       Non-integer
14mS        The unit is case-insensitive, although capital letters are not recommended.
+0s         Zero with a leading + and a unit
-0ms        Zero with a leading - and a unit
```

### Invalid times

```
0           Although unitless zero is allowed for <length>s, it's invalid for <time>s.
12.0        This is a <number>, not a <time>, because it's missing a unit.
7 ms        No space is allowed between the number and the unit.
```

## Compatibility

**Compatibility Table**
**Query:** `css.data-type.time`

**Specifications:**
- [https://drafts.csswg.org/css-values/#time](https://drafts.csswg.org/css-values/#time)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 1.5 | - |
| Clay iOS | 1.5 | - |
| Clay Windows | 1.5 | - |
| Clay macOS | 1.5 | - |
| Web | ✅ Yes | - |

**Description:** <code>&lt;time&gt;</code>




---
url: /api/css/selectors.md
---

# Selectors

CSS selectors specify which elements a CSS rule applies to. Pedantically speaking, CSS selectors is an umbrella term that includes Selectors, Combinators, Pseudo-elements, and Pseudo-classes.

## Selectors

### Type selector

The CSS type selector matches elements by node name. In other words, it selects all elements of the given type.

#### Syntax

```css
element { property declarations }
```

#### Example Usage

```css
/* To match all <input> elements */
input {
  ...
}

```

#### Using `page` to Select the Root Node

Unlike on the Web, in Lynx, the `page` element is used to select the root node instead of `body`.

### Class selector

The CSS class selector matches elements based on the contents of their class attribute.

#### Syntax

```css
.className { property declarations }
```

#### Example Usage

```css
/* All elements with class="index" */
.index{
  ...
}
```

### Multiple Class Selectors

To select elements using multiple class names, specify that an element must contain all these classes by concatenating the class names together.

#### Syntax

```css
.className1.className2 { property declarations }

element.className1.className2 { property declarations }
```

#### Example Usage

```css
/* To match any input elements with a class that contains both "a" and "b". */
input.a.b{
  ...
}

/* element */
<input className="a b" /> /* selected */
```

### ID selector

The CSS ID selector matches an element based on the value of the element's id attribute. In order for the element to be selected, its id attribute must match exactly the value given in the selector.

#### Syntax

```css
#idName {  property declarations }
```

### Universal selector

The CSS universal selector (\*) matches elements of any type.

#### Syntax

```css
* {  property declarations }
```

## Combinator

### Descendant Combinator

e descendant combinator — typically represented by a single space (" ") character — combines two selectors such that elements matched by the second selector are selected if they have an ancestor (parent, parent's parent, parent's parent's parent, etc.) element matching the first selector. Selectors that utilize a descendant combinator are called descendant selectors.

**Compared to the old selector, it no longer restricts the levels of matched elements to two levels.**

#### Syntax

```css
selector1 selector2 selector3 {
  property declarations
}
```

#### Example Usage

```css
/* Match all "b" elements that are descendants of the "a" list. */
view.a .b{
   ...
}

/* element */
<view className="a" >
 <text className="b">hello</text> /* selected */
</view>
```

### Child Combinator

The child combinator (`>`) is placed between two CSS selectors. It matches only those elements matched by the second selector that are the direct children of elements matched by the first.

#### Syntax

```css
element1 > element2 {
  property declarations
}
```

#### Example Usage

```css
/* Match all text elements that are direct children of "a" view */
view.a > text {
  ...
}

/* element */
<view className="a" >
  <text>hello</text> /*selected*/
</view>
```

### Subsequent-sibling Combinator

The subsequent-sibling combinator (`~`, a tilde) separates two selectors and matches all instances of the second element that follow the first element (not necessarily immediately) and share the same parent element.

#### Syntax

```css
former_element ~ target_element { property declarations }
```

#### Example Usage

```css
/* Match all sibling text elements following view. */
view ~ text {
  ...
}

/* element */
<view className="a" />
<text />  /* selected */
...
<text />  /* selected */
```

### Next-sibling Combinator

The next-sibling combinator (`+`) separates two selectors and matches the second element only if it immediately follows the first element, and both are children of the same parent element.

#### Syntax

```css
former_element + target_element { property declarations }
```

#### Example Usage

```css
/*  Match the text element that come immediately after a view */
view + text {
  ...
}

/* element */
<view className="a" />
<text />  /*selected*/
<text />  /*not selected*/
```

### Selector list

The CSS selector list (`,`) selects all the matching nodes. A selector list is a comma-separated list of selectors.

#### Syntax

```css
selector1,selector2 { property declarations }
```

#### Example Usage

```css
/* All matching elements are selected. */
 selector1, selector2 {
  ...
}

Equivalent to

selector1 {
  ...
}

selector2 {
  ...
}
```

## Pseudo

### Pseudo-class

A `:` pseudo-class is a type of selector used to select elements in a specific state.

Supports

- `:active`
- `:not()`
- `:root`

#### `:not()`

Used to match elements that do not meet the conditions. Usage aligns with [W3C :not()](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:not)

#### `:root` \{#root-selector}

Similar to the `page` selector used to match the root node. Usage aligns with [W3C :root](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:root)

#### `:active`

When a node is pressed, it gets activated and selected. Releasing the finger deactivates it. Usage aligns with [W3C :active](https://developer.mozilla.org/zh-CN/docs/Web/CSS/:active)

#### Example Usage

```css
/* Elements that are not <view> and not <text> elements */
root :not(view):not(text) {
  font-weight: bold;
}

/* Elements that are not .crazy or .fancy
   Note that this syntax is not well supported yet. */
body :not(.crazy, .fancy) {
  font-family: sans-serif;
}
```

## Pseudo-element

Lynx doesn't have pseudo-element support yet.

## Troubleshooting

### `!important` is not supported as specificity

By the weight ratio of CSS selectors, the total specificity of CSS rules is calculated to determine the priority order of style rules. The basic calculation logic for CSS specificity is as follows:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/css-priority.png)


---
url: /api/lynx-api/event/animation-event.md
---

# AnimationEvent

APISummary
Represents the animation event object, inherited from [CustomEvent](/api/lynx-api/event/custom-event.md), used to describe the state changes of the animation in its life cycle, such as start, end, etc.

The event object contains information such as the type and name of the animation.

## Instance property

### detail

```ts
detail: {
  animation_type: string,
  animation_name: string,
  new_animator: boolean,
}
```

Represents some basic information of the animation to which the event belongs.

- `animation-type`: The type of the animation. If it is a keyframe animation, this value is `keyframe-animation`; if it is a transition animation, this value is `transition-animation`.
- `animation-name`: The name of the animation. If it is a keyframe animation, it is the name of [`@keyframes`](/api/css/at-rule/keyframes.md) in CSS; if it is a transition animation, it is the name of [`transition-property`](/api/css/properties/transition-property.md) in CSS.
- `new_animator`: The default value is `true`.

## AnimationEvent type

:::info
During the animation execution process, if the animation node is uninstalled and destroyed, the [`animationcancel`](#animationcancel) and [`transitioncancel`](#transitioncancel) events on the node will not be triggered.
:::

### animationstart

Indicates the start of keyframe animation playback.

### animationend

Indicates the end of keyframe animation playback.

### animationcancel

Indicates that the keyframe animation playback is canceled.

### animationiteration

Indicates the number of keyframe animation playback iterations.

### transitionstart

Indicates the start of the transition animation playback.

### transitionend

Indicates the end of the transition animation playback.

### transitioncancel

Indicates that the transition animation playback is canceled.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.AnimationEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.6 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/custom-event.md
---

# CustomEvent

APISummary
Represents a custom event object, inherited from [`Event`](/api/lynx-api/event/event.md), used to describe the state changes of the component customization, such as [`scroll`](/api/elements/built-in/scroll-view.md#bindscroll).

This event object contains some state information of the component customization, and developers can use it to understand the state changes of the component.

## Instance property

:::info
There are two properties of the custom event object, one is [`params`](#params), the other is [`detail`](#detail). [`params`](#params) will be discarded in the future, and it is recommended to use [`detail`](#detail).

Starting with Lynx version 3.1, custom event objects will always include the [`detail`](#detail) property.
:::

### params

```ts
params: object;
```

Represents some state information of the component customization.

### detail

```ts
detail: object;
```

Represents some state information of the component customization.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.CustomEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/event.md
---

# Event

APISummary
`Event` represents the event object when the event is triggered, which contains the state information when the event is triggered. Developers can listen through the [Event Handler Property](/guide/interaction/event-handling/event-propagation.md#event-handler-property).

Lynx has many different types of event objects, all of which are directly or indirectly inherited from `Event`. `Event` itself contains properties and methods applicable to all event objects.

## `Event` type

[`TouchEvent`](/api/lynx-api/event/touch-event.md)

`TouchEvent` represents a touch event object, which describes the state change of a finger on a touch surface (such as a touch screen).

[`CustomEvent`](/api/lynx-api/event/custom-event.md)

`CustomEvent` represents a custom event object, which describes the state change of a custom component.

[`AnimationEvent`](/api/lynx-api/event/animation-event.md)

`AnimationEvent` represents an animation event object, describing the state changes of the CSS animation life cycle.

[`MouseEvent`](/api/lynx-api/event/mouse-event.md)

`MouseEvent` represents a mouse event, describing the user's interaction with the mouse.

[`KeyEvent`](/api/lynx-api/event/key-event.md)

`KeyEvent` represents a keyboard event, describing the user's interaction with the keyboard.

[`WheelEvent`](/api/lynx-api/event/wheel-event.md)

`WheelEvent` represents a mouse wheel event, describing the user scrolling the mouse wheel or touchpad.

## Instance property

### type

```ts
type: string;
```

Indicates the type of event.

### timestamp

```ts
timestamp: number;
```

Indicates the timestamp when the event was generated.

### target

```ts
target: {
  id: string,
  uid: number,
  dataset: [key: string]: any,
}
```

Indicates a collection of some attribute values ​​of `element` that triggered the event.

- `id`: `element`'s `id` selector.
- `uid`: `element`'s unique identifier in Lynx Engine.
- `dataset`: A collection of custom attributes starting with [`data-`](/api/elements/built-in/view.md#data-) on `element`.

### currentTarget

```ts
currentTarget: {
  id: string,
  uid: number,
  dataset: [key: string]: any,
}
```

A collection of attribute values ​​of `element` that listens to events.

- `id`: `element`'s `id` selector.
- `uid`: `element`'s unique identifier in Lynx Engine.
- `dataset`: A collection of custom attributes starting with [`data-`](/api/elements/built-in/view.md#data-) on `element`.

## Instance method

### stopPropagation [MTS Only](/guide/spec.html#scripting-mts)
```ts
stopPropagation(): void;
```

Stop bubbling and prevent the event from continuing to bubble up the touch response chain.

Calling it in the [main thread script](/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

**This is an example below: event**

**Entry:** `src/event_stop_propagation`
**Bundle:** `dist/event_stop_propagation.lynx.bundle` | Web: `dist/event_stop_propagation.web.bundle`

```tsx {34}
import { root, runOnBackground, useState } from "@lynx-js/react";
import "./index.css";
import type { MainThread } from "@lynx-js/types";

export default function App() {
  const [active, setActive] = useState({ outer: false, middle: false, inner: false });

  // Utility to flash a box when it's clicked
  const flashBT = (key: "outer" | "middle" | "inner") => {
    setActive((prev) => ({ ...prev, [key]: true }));
    setTimeout(() => setActive((prev) => ({ ...prev, [key]: false })), 200);
  };

  // Utility to flash a box when it's clicked
  const flash = (
    key: "outer" | "middle" | "inner",
  ) => {
    "main thread";
    runOnBackground(flashBT)(key);
  };

  function handleOuterTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("outer");
  }

  function handleMiddleTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("middle");
  }

  function handleInnerTap(e: MainThread.TouchEvent) {
    "main thread";
    e.stopPropagation(); // ✋ stop event bubbling
    flash("inner");
  }

  return (
    <view
      main-thread:bindtap={handleOuterTap}
      className={`box outer ${active.outer ? "active" : ""}`}
    >
      <text>Outer {active.outer ? "(active)" : "(inactive)"}</text>
      <view
        main-thread:bindtap={handleMiddleTap}
        className={`box middle ${active.middle ? "active" : ""}`}
      >
        <text>Middle {active.middle ? "(active)" : "(inactive)"}</text>
        <view
          main-thread:bindtap={handleInnerTap}
          className={`box inner ${active.inner ? "active" : ""}`}
        >
          <text>Inner (click me, stops propagation) {active.inner ? "(active)" : "(inactive)"}</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### stopImmediatePropagation [MTS Only](/guide/spec.html#scripting-mts)
```ts
stopImmediatePropagation(): void;
```

Stop bubbling, prevent the event from continuing to bubble in the event response chain, and prevent other event handlers of the same event on the current node from being triggered.

Calling it in the [main thread script](/react/main-thread-script.md) can affect both event bubbling and event handler triggering in `JS`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.Event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/global-event.md
---

# GlobalEvent

APISummary
Represents a global event object, which is an array that can be passed between different elements and components, or between the client and the front end.

Developers can listen to this event based on [`GlobalEventEmitter`](/guide/interaction/event-handling/event-propagation.md#globaleventemitter).

## GlobalEvent Type

### keyboardstatuschanged

Represents the keyboard status change caused by input method focus or user operation.

```json
[
  status: ['on', 'off'],    // indicates the status of the keyboard
  height: number,           // indicates the height of the keyboard, in px
  compatHeight: number,     // indicates the height of compatible keyboards, in px
]
```

**Example:**

```javascript
// Listen to keyboard status changes
useLynxGlobalEventListener(
  'keyboardstatuschanged',
  (status, height, compatHeight) => {
    console.log(
      `status: ${status}, height: ${height}, compatHeight: ${compatHeight}`,
    );
  },
);
```

### onWindowResize

Indicates the change in Lynx page size due to screen rotation or external typesetting.

```json
[
  width?: number,    // indicates the width of the Lynx page after the change, in px
  height?: number,          // indicates the height of the Lynx page after the change, in px
]
```

**Example:**

```javascript
useLynxGlobalEventListener('onWindowResize', (width, height) => {
  console.log(`Window resized to: ${width}x${height}px`);
});
```

### exposure

Indicates that a node in the exposure data source has generated exposure, that is, the visibility of the node has changed from invisible to visible.

```json
[
  {
    "exposure-id": string,      // exposure-id set on the target node
    "exposure-scene": string,   // exposure-scene set on the target node
    "sign": string,             // uid of the target node
    "dataset": object,          // "data-" field set on the target node
    //......
  },
  //......
]
```

**Example:**

```javascript
useLynxGlobalEventListener('exposure', (exposures) => {
  // The argument is an Array of exposure items
  exposures.forEach((item) => {
    console.log(
      `Node exposed: ${item['exposure-id']}, scene: ${item['exposure-scene']}`,
    );
  });
});
```

### disexposure

Indicates that a node in the exposure data source has generated a reverse exposure, that is, the visibility of the node has changed from visible to invisible.

```json
[
  {
    "exposure-id": string,      // exposure-id set on the target node
    "exposure-scene": string,   // exposure-scene set on the target node
    "sign": string,             // uid of the target node
    "dataset": object,          // "data-" field set on the target node
    //......
  },
  //......
]
```

**Example:**

```javascript
useLynxGlobalEventListener('disexposure', (disexposures) => {
  // The argument is an Array of disexposure items
  disexposures.forEach((item) => {
    console.log(
      `Node hidden: ${item['exposure-id']}, scene: ${item['exposure-scene']}`,
    );
  });
});
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.GlobalEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/key-event.md
---

# KeyEvent

APISummary
Represents a keyboard event, inherited from [`Event`](/api/lynx-api/event/event.md), which describes the user's interaction with the keyboard. Each event describes a single interaction between the user and a key, or a key combined with modifier keys.

## Instance property

### key

```ts
key: string;
```

Represents the value of the physical key pressed by the user.

### repeat

```ts
repeat: boolean;
```

`true` indicates the key is being held down such that it is automatically repeating.

### altKey

```ts
altKey: boolean;
```

`true` indicates the Alt key, or Option (`⌥`) on macOS, was active when the key event was generated.

### ctrlKey

```ts
ctrlKey: boolean;
```

`true` indicates the Ctrl key was active when the key event was generated.

### metaKey

```ts
metaKey: boolean;
```

`true` indicates the Meta key was active when the key event was generated. On macOS, this is the Command (`⌘`) key. On Windows, this is the Windows key.

### shiftKey

```ts
shiftKey: boolean;
```

`true` indicates the Shift key was active when the key event was generated.

## KeyEvent type

### keydown

Indicates that a key has been pressed.

### keyup

Indicates that a key has been released.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.KeyEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/memory-event.md
---

# MemoryEvent

APISummary
Native memory pressure event dispatched from the host environment and delivered to the front end via the native context. The event name is `__OnLowMemory`, and the payload is a single `MemoryPressureLevel` enum value.

## Payload

### MemoryPressureLevel

```ts
enum MemoryPressureLevel {
  MEMORY_PRESSURE_LEVEL_NONE = 0,
  MEMORY_PRESSURE_LEVEL_MODERATE = 1,
  MEMORY_PRESSURE_LEVEL_CRITICAL = 2,
}
```

## Usage

```ts
// Add one or multiple listeners
lynx
  .getNative()
  .addEventListener('__OnLowMemory', (level: MemoryPressureLevel) => {
    if (level === MemoryPressureLevel.MEMORY_PRESSURE_LEVEL_CRITICAL) {
      // handle critical memory pressure
    }
  });

lynx
  .getNative()
  .addEventListener('__OnLowMemory', (level: MemoryPressureLevel) => {
    // parallel listener
  });
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.MemoryEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |
| HarmonyOS | 3.8 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/event/mouse-event.md
---

# MouseEvent

APISummary
Represents a mouse event, inherited from [`Event`](/api/lynx-api/event/event.md), which is a type of event that describes the user's interaction with the mouse. For example, mouse click.

:::info
Starting from Lynx 3.8, you can enable W3C Web standard-aligned `MouseEvent` behavior in `pageConfig`.

```js
// pageConfig
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

pluginReactLynx({
  alignMouseEventWithW3C: true,
});
```

:::

## Instance property

### button

```ts
button: number;
```

After `alignMouseEventWithW3C` is enabled, when a mouse event is triggered, if any mouse button is pressed or released, an integer value representing this mouse button will be returned.

| Value | Description            |
| ----- | ---------------------- |
| 0     | primary mouse button   |
| 1     | middle mouse button    |
| 2     | secondary mouse button |

### buttons

```ts
buttons: number;
```

After `alignMouseEventWithW3C` is enabled, when a mouse event is triggered, if any buttons are pressed, an integer value representing multiple buttons which user is pressing will be returned. Each button occupies one bit field.

| Bit | Description            |
| --- | ---------------------- |
| 0   | primary mouse button   |
| 1   | secondary mouse button |
| 2   | middle mouse button    |

### x

```ts
x: number;
```

Represents the horizontal axis position of the mouse pointer in the `element` coordinate system that contains the mouse pointer and is closest to the user.

### y

```ts
y: number;
```

Represents the vertical axis position of the mouse pointer in the `element` coordinate system that contains the mouse pointer and is closest to the user.

### pageX

```ts
pageX: number;
```

Indicates the horizontal axis position of the mouse pointer in the current `LynxView` coordinate system.

### pageY

```ts
pageY: number;
```

Represents the vertical axis position of the mouse pointer in the current `LynxView` coordinate system.

### clientX

```ts
clientX: number;
```

Indicates the horizontal axis position of the mouse pointer in the current window coordinate system.

### clientY

```ts
clientY: number;
```

Indicates the vertical axis position of the mouse pointer in the current window coordinate system.

## Type of MouseEvent

### mousedown

Indicates a mouse button is pressed (primary or secondary). [`target`](/api/lynx-api/event/event.md#target) is the `element` closest to the user that contains the mouse pointer.

### mousemove

Indicates that the mouse is moving inside the element. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

### mouseup

Indicates that the mouse button is released on the element. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

### mouseenter

Indicates that the mouse moves into the activation area of [`target`](/api/lynx-api/event/event.md#target) for the first time. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

Note: the `mouseenter` event does not bubble, and it can't be captured by using [`capture-`](/guide/interaction/event-handling/event-propagation.md#event-handler-property) API.

### mouseover

Indicates that the mouse pointer is moved onto the [`target`](/api/lynx-api/event/event.md#target) or one of its children. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the mouse pointer and is closest to the user.

### mouseleave

Indicates that the mouse moves out of the activation area of [`target`](/api/lynx-api/event/event.md#target) for the first time. [`target`](/api/lynx-api/event/event.md#target) is the same as previous [`mouseenter`](#mouseenter)'s [`target`](/api/lynx-api/event/event.md#target).

Note: the `mouseleave` event does not bubble, and it can't be captured by using [`capture-`](/guide/interaction/event-handling/event-propagation.md#event-handler-property) API.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.MouseEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/touch-event.md
---

# TouchEvent

APISummary
Represents a touch event object, inherited from [`Event`](/api/lynx-api/event/event.md), used to describe the state changes of a finger on a touch surface (such as a touch screen), such as finger movement, click, long press, etc.

This event object contains one or more touch points, through which developers can understand the state changes of fingers on the touch surface.

## Instance property

### detail

```ts
detail: {
  x: number,
  y: number,
}
```

Represents the touch point position of the first finger.

- `x`: The horizontal axis position of the touch point in the current `LynxView` coordinate system.
- `y`: The vertical axis position of the touch point in the current `LynxView` coordinate system.

### touches

```ts
touches: Touch []
```

Represents the `Touch` object currently on the touch plane. Each `Touch` object describes the touch point information of the corresponding finger. The format is as follows:

```ts
{
  identifier: number,   // Unique identifier of the touch point, which remains unchanged during the same touch process
  x: number,            // The horizontal position of the touch point in the coordinate system of the element actually touched
  y: number,            // The vertical position of the touch point in the coordinate system of the element actually touched
  pageX: number,        // The horizontal position of the touch point in the current LynxView coordinate system
  pageY: number,        // The vertical position of the touch point in the current LynxView coordinate system
  clientX: number,      // The horizontal position of the touch point in the current window coordinate system
  clientY: number,      // The horizontal position of the touch point in the current window coordinate system
}
```

### changedTouches

```ts
changedTouches: Touch []
```

Indicates a `Touch` object whose state has changed compared to the last touch event, such as from nothing to something, position change, from something to nothing. The format of [`changesTouches`](#changedtouches) is the same as that of [`touches`](#touches).

## TouchEvent type

### touchstart

Indicates that the finger begins to touch the touch surface. [`target`](/api/lynx-api/event/event.md#target) is the `element` that contains the touch point and is closest to the user.

### touchmove

Indicates that the finger moves on the touch surface. [`target`](/api/lynx-api/event/event.md#target) is always the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart).

### touchend

Indicates that the finger leaves the touch surface. [`target`](/api/lynx-api/event/event.md#target) is the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart). The touch point that has left the screen can be found in [`changedTouches`](#changedtouches).

### touchcancel

Indicates that the touch event is interrupted by the system or `Lynx` external gesture, such as system pop-up window or incoming call. [`target`](/api/lynx-api/event/event.md#target) is the same as [`target`](/api/lynx-api/event/event.md#target) of [`touchstart`](#touchstart). The interrupted touch point can be found in [`changedTouches`](#changedtouches).

### tap

This indicates a single tap on the touch surface. The [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point and closest to the user. Only the first finger can trigger this event.

If the finger moves beyond a certain distance threshold, or if an `element` in the [`event response chain`](/guide/interaction/event-handling/event-propagation.md#event-response-chain) slides, the `tap` event will not trigger.

This event and the [`longpress`](#longpress) event are mutually exclusive in event listening. That is, if the front-end listens for both events simultaneously, they will not trigger concurrently; [`longpress`](#longpress) takes precedence.

### longpress

This indicates a long press on the touch surface. The [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point and closest to the user. Only the first finger can trigger this event. The `longpress` event will not trigger if the finger moves beyond a certain threshold or the long press time interval is less than `500 ms`.

### click

This indicates a single click on the touch plane. [`target`](/api/lynx-api/event/event.md#target) is the `element` containing the touch point, closest to the user, and listening for the `click` event. Only the first finger can trigger this event.

This event differs slightly from the [`tap`](#tap) event, primarily in its blocking distance threshold and the [`target`](/api/lynx-api/event/event.md#target):

- The [`target`](/api/lynx-api/event/event.md#target) for [`tap`](#tap) event is the node closest to the user during the actual touch; while the [`target`](/api/lynx-api/event/event.md#target) for `click` event is the node closest to the user that is listening for the `click` event.

- The blocking distance threshold for [`tap`](#tap) event is fixed; it won't trigger if the finger moves beyond a certain distance. The blocking distance threshold for `click` event depends on the touch hotspot of [`target`](/api/lynx-api/event/event.md#target); it won't trigger if the finger moves outside the touch hotspot.

- When an element slides on the [`event response chain`](/guide/interaction/event-handling/event-propagation.md#event-response-chain) corresponding to [`target`](/api/lynx-api/event/event.md#target), the [`tap`](#tap) or `click` event cannot be triggered.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/tap_and_click.png)
## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.TouchEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/event/wheel-event.md
---

# WheelEvent

APISummary
Represents a mouse wheel event, inherited from [`MouseEvent`](/api/lynx-api/event/mouse-event.md). It can also be fired by trackpads and other scrolling devices. [`target`](/api/lynx-api/event/event.md#target) is the `element` under the mouse pointer when the first `WheelEvent` occurs.

## Instance property

### deltaX

```ts
deltaX: number;
```

Indicates the horizontal scrolling distance in logical pixels.

### deltaY

```ts
deltaY: number;
```

Indicates the vertical scrolling distance in logical pixels.

## WheelEvent type

### wheel

Indicates that the user scrolls the mouse wheel or touchpad. [`target`](/api/lynx-api/event/event.md#target) is the `element` under the mouse pointer when the first `WheelEvent` occurs.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.event.WheelEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global.md
---

# Overview

## clearInterval()

### [clearInterval()](/api/lynx-api/global/clear-interval.md)

- [Syntax](/api/lynx-api/global/clear-interval.md#syntax)
- [Example](/api/lynx-api/global/clear-interval.md#example)
- [Notices](/api/lynx-api/global/clear-interval.md#notices)
- [Compatibility](/api/lynx-api/global/clear-interval.md#compatibility)
## clearTimeout()

### [clearTimeout()](/api/lynx-api/global/clear-timeout.md)

- [Syntax](/api/lynx-api/global/clear-timeout.md#syntax)
- [Example](/api/lynx-api/global/clear-timeout.md#example)
- [Notes](/api/lynx-api/global/clear-timeout.md#notes)
- [Compatibility](/api/lynx-api/global/clear-timeout.md#compatibility)
## console

### [assert()](/api/lynx-api/global/console/assert.md)

- [Syntax](/api/lynx-api/global/console/assert.md#syntax)
- [Compatibility](/api/lynx-api/global/console/assert.md#compatibility)

### [count()](/api/lynx-api/global/console/count.md)

- [Syntax](/api/lynx-api/global/console/count.md#syntax)
- [Compatibility](/api/lynx-api/global/console/count.md#compatibility)

### [countReset()](/api/lynx-api/global/console/countReset.md)

- [Syntax](/api/lynx-api/global/console/countReset.md#syntax)
- [Compatibility](/api/lynx-api/global/console/countReset.md#compatibility)

### [debug()](/api/lynx-api/global/console/debug.md)

- [Syntax](/api/lynx-api/global/console/debug.md#syntax)
- [Compatibility](/api/lynx-api/global/console/debug.md#compatibility)

### [error()](/api/lynx-api/global/console/error.md)

- [Syntax](/api/lynx-api/global/console/error.md#syntax)
- [Compatibility](/api/lynx-api/global/console/error.md#compatibility)

### [group()](/api/lynx-api/global/console/group.md)

- [Syntax](/api/lynx-api/global/console/group.md#syntax)
- [Compatibility](/api/lynx-api/global/console/group.md#compatibility)

### [groupCollapsed()](/api/lynx-api/global/console/groupCollapsed.md)

- [Syntax](/api/lynx-api/global/console/groupCollapsed.md#syntax)
- [Compatibility](/api/lynx-api/global/console/groupCollapsed.md#compatibility)

### [groupEnd()](/api/lynx-api/global/console/groupEnd.md)

- [Syntax](/api/lynx-api/global/console/groupEnd.md#syntax)
- [Compatibility](/api/lynx-api/global/console/groupEnd.md#compatibility)

### [info()](/api/lynx-api/global/console/info.md)

- [Syntax](/api/lynx-api/global/console/info.md#syntax)
- [Compatibility](/api/lynx-api/global/console/info.md#compatibility)

### [log()](/api/lynx-api/global/console/log.md)

- [Syntax](/api/lynx-api/global/console/log.md#syntax)
- [Compatibility](/api/lynx-api/global/console/log.md#compatibility)

### [profile()](/api/lynx-api/global/console/profile.md)

- [Syntax](/api/lynx-api/global/console/profile.md#syntax)
- [Compatibility](/api/lynx-api/global/console/profile.md#compatibility)

### [profileEnd()](/api/lynx-api/global/console/profileEnd.md)

- [Syntax](/api/lynx-api/global/console/profileEnd.md#syntax)
- [Compatibility](/api/lynx-api/global/console/profileEnd.md#compatibility)

### [table()](/api/lynx-api/global/console/table.md)

- [Syntax](/api/lynx-api/global/console/table.md#syntax)
- [Compatibility](/api/lynx-api/global/console/table.md#compatibility)

### [time()](/api/lynx-api/global/console/time.md)

- [Syntax](/api/lynx-api/global/console/time.md#syntax)
- [Compatibility](/api/lynx-api/global/console/time.md#compatibility)

### [timeEnd()](/api/lynx-api/global/console/timeEnd.md)

- [Syntax](/api/lynx-api/global/console/timeEnd.md#syntax)
- [Compatibility](/api/lynx-api/global/console/timeEnd.md#compatibility)

### [timeLog()](/api/lynx-api/global/console/timeLog.md)

- [Syntax](/api/lynx-api/global/console/timeLog.md#syntax)
- [Compatibility](/api/lynx-api/global/console/timeLog.md#compatibility)

### [warn()](/api/lynx-api/global/console/warn.md)

- [Syntax](/api/lynx-api/global/console/warn.md#syntax)
- [Compatibility](/api/lynx-api/global/console/warn.md#compatibility)
## fetch

### [fetch](/api/lynx-api/global/fetch.md)

- [Example](/api/lynx-api/global/fetch.md#example)
- [Compatibility](/api/lynx-api/global/fetch.md#compatibility)
## setInterval()

### [setInterval()](/api/lynx-api/global/set-interval.md)

- [Syntax](/api/lynx-api/global/set-interval.md#syntax)
- [Example](/api/lynx-api/global/set-interval.md#example)
- [Compatibility](/api/lynx-api/global/set-interval.md#compatibility)
## setTimeout()

### [setTimeout()](/api/lynx-api/global/set-timeout.md)

- [Syntax](/api/lynx-api/global/set-timeout.md#syntax)
- [Example](/api/lynx-api/global/set-timeout.md#example)
- [Compatibility](/api/lynx-api/global/set-timeout.md#compatibility)
## SystemInfo

### [SystemInfo](/api/lynx-api/global/system-info.md)

- [Syntax](/api/lynx-api/global/system-info.md#syntax)
- [Compatibility](/api/lynx-api/global/system-info.md#compatibility)



---
url: /api/lynx-api/global/clear-interval.md
---

# clearInterval() global function

APISummary
Cancels the timer set by `setInterval`.

## Syntax

```typescript
clearInterval(timerId: number): void;
```

### Parameters

#### timerId

The timer ID returned by `setInterval`.
\*\* Passing in an ID value other than the one returned by `setInterval` is undefined behavior and may cause problems. \*\*

## Example

## Notices

1. `setTimeout()` and `setInterval()` have a shared pool of ID numbers, so technically `clearTimeout()` and `clearInterval()` are interchangeable. However, for clarity, you should avoid doing so.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.clearInterval`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Cancels the timer set by `setInterval`.




---
url: /api/lynx-api/global/clear-timeout.md
---

# clearTimeout() global function

APISummary
Cancel the timer set by `setTimeout`.

## Syntax

```typescript
  clearTimeout(timerId: number): void;
```

### Parameter

#### timerId

The timer ID returned by `setTimeout`.
If the timer corresponding to this ID has already finished executing, the method will not perform any action.

\*\* Passing in an ID value that is not returned by `setTimeout` is undefined behavior and may cause problems. \*\*

## Example

## Notes

1. `setTimeout()` and `setInterval()` have a shared pool of ID numbers, so technically `clearTimeout()` and `clearInterval()` are interchangeable. However, for clarity, you should avoid doing so.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.clearTimeout`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/API/clearTimeout](https://developer.mozilla.org/zh-CN/docs/Web/API/clearTimeout)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Cancel the timer set by `setTimeout`.




---
url: /api/lynx-api/global/console/assert.md
---

# console: assert() method

APISummary
`assert` writes an error message to the console if the assertion is false. If the assertion is true, nothing happens.

## Syntax

```ts
assert(assertion: boolean, val1, val2, ...): undefined;
```

### Parameters

#### assertion

Any boolean expression. If the assertion is false, a generic message indicating assertion failure is written to the console.

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.assert`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** assert failed and output error level message




---
url: /api/lynx-api/global/console/count.md
---

# console: count() method

APISummary
`count` logs the number of times that this particular call to count() has been called.

## Syntax

```ts
count(label: string?): undefined;
```

### Parameters

#### label

A string. If supplied, count() outputs the number of times it has been called with that label. If omitted, count() behaves as though it was called with the "default" label.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.count`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** start count




---
url: /api/lynx-api/global/console/countReset.md
---

# console: countReset() method

APISummary
`countReset` resets counter used with console.count().

## Syntax

```ts
countReset(label: string?): undefined;
```

### Parameters

#### label

A string. If supplied, countReset() resets the count for that label to 0. If omitted, countReset() resets the default counter to 0.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.countReset`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** reset count




---
url: /api/lynx-api/global/console/debug.md
---

# console: debug() method

APISummary
`debug` outputs a message to the console at the "debug" log level.

## Syntax

```ts
debug(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.debug`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a debug level message




---
url: /api/lynx-api/global/console/error.md
---

# console: error() method

APISummary
`error` outputs a message to the console at the "error" log level.

## Syntax

```ts
error(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a error level message




---
url: /api/lynx-api/global/console/group.md
---

# console: group() method

APISummary
`group` creates a new inline group in the console log, causing any subsequent console messages to be indented by an additional level, until console.groupEnd() is called.

## Syntax

```ts
group(label: string?): undefined;
```

### Parameters

#### label

Label for the group.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.group`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** start a console group




---
url: /api/lynx-api/global/console/groupCollapsed.md
---

# console: groupCollapsed() method

APISummary
`groupCollapsed` creates a new inline group in the console. Unlike console.group(), however, the new group is created collapsed. The user will need to use the disclosure button next to it to expand it, revealing the entries created in the group.

## Syntax

```ts
groupCollapsed(label: string?): undefined;
```

### Parameters

#### label

Label for the group.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.groupCollapsed`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** start a collapsed console group




---
url: /api/lynx-api/global/console/groupEnd.md
---

# console: groupEnd() method

APISummary
`groupEnd` exits the current inline group in the console.

## Syntax

```ts
groupEnd(): undefined;
```

### Parameters

None.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.groupEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** end a console group




---
url: /api/lynx-api/global/console/info.md
---

# console: info() method

APISummary
`info` 方法用于在控制台面板输出信息，日志级别为 info 级别。

## Syntax

```ts
info(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

输出的JavaScript值列表。这些值中的每个值的表示形式都以给定的顺序输出。

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a info level message




---
url: /api/lynx-api/global/console/log.md
---

# console: log() method

APISummary
`log` outputs a message to the console.

## Syntax

```ts
log(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.log`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a log level message




---
url: /api/lynx-api/global/console/profile.md
---

# console: profile() method

APISummary
`profile` starts recording a performance profile.

## Syntax

```ts
profile(profileName: string): undefined;
```

### Parameters

#### profileName

The name to give the profile.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.profile`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a message




---
url: /api/lynx-api/global/console/profileEnd.md
---

# console: profileEnd() method

APISummary
`profileEnd` stops recording a profile previously started with console.profile().

## Syntax

```ts
profileEnd(profileEndName: string): undefined;
```

### Parameters

#### profileEndName

The name to give the profile.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.profileEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** end profile




---
url: /api/lynx-api/global/console/table.md
---

# console: table() method

APISummary
`table` displays tabular data as a table.

## Syntax

```ts
table(data: any, columns: array?): undefined;
```

### Parameters

#### data

The data to display. This must be either an array or an object. Each item in the array, or property in the object, is represented by a row in the table. The first column in the table is labeled (index) and its values are the array indices or the property names.

#### columns

An array which can be used to restrict the columns shown in the table. It contains indices, if each entry of data is an array, or property names, if each entry of data is an object. The resulting table then includes only columns for items which match the given indices or names.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.table`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** print message by table




---
url: /api/lynx-api/global/console/time.md
---

# console: time() method

APISummary
`time` starts a timer you can use to track how long an operation takes.

## Syntax

```ts
time(label: string?): undefined;
```

### Parameters

#### label

A string representing the name to give the new timer.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.time`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** start a timer




---
url: /api/lynx-api/global/console/timeEnd.md
---

# console: timeEnd() method

APISummary
`timeEnd` stops a timer that was previously started by calling console.time().

## Syntax

```ts
timeEnd(label: string?): undefined;
```

### Parameters

#### label

A string representing the name to give the new timer.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.timeEnd`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** end a timer




---
url: /api/lynx-api/global/console/timeLog.md
---

# console: timeLog() method

APISummary
`timeLog` logs the current value of a timer that was previously started by calling console.time().

## Syntax

```ts
timeLog(label: string?): undefined;
```

### Parameters

#### label

The name of the timer to log to the console. If this is omitted the label "default" is used.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.timeLog`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.2 | - |
| iOS | 3.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** print timer




---
url: /api/lynx-api/global/console/warn.md
---

# console: warn() method

APISummary
`warn` outputs a warning message to the console at the "warning" log level.

## Syntax

```ts
warn(val1, val2, ...): undefined;
```

### Parameters

#### val1, val2, ...

A list of JavaScript values to output.

### return value

None(`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.console.warn`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** output a warn level message




---
url: /api/lynx-api/global/fetch.md
---

# fetch

APISummary
## Syntax

```typescript
fetch(resource);
fetch(resource, options);
```

### Parameters

#### resource

This defines the resource that you wish to fetch. This can either be:

- A string or any other object with stringify API — including a URL object — that provides the URL of the resource you want to fetch.

- A `Request` object.

#### options

A `RequestInit` object containing any custom settings that you want to apply to the request.

## Example

```typescript
const request = new Request('https://jsonplaceholder.typicode.com/todos/1');
const response = await fetch(request);
console.log(await response.json());
```

## Compatibility

:::info

- Client environment are different from Web, Lynx does not support Web-only features like: [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)、redirect、keepalive related APIs. FormData/Blob related APIs are not supported.

- Web Platform supports Fetch API using Browser's Fetch implementation, it follows the same rules as the web.

:::

**Compatibility Table**
**Query:** `lynx-api.fetch.fetch`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** <code>fetch</code>


### Headers

**Compatibility Table**
**Query:** `lynx-api.fetch.Headers`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Headers](https://developer.mozilla.org/docs/Web/API/Headers)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |


### Request

**Compatibility Table**
**Query:** `lynx-api.fetch.Request`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Request](https://developer.mozilla.org/docs/Web/API/Request)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |


### Response

**Compatibility Table**
**Query:** `lynx-api.fetch.Response`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Response](https://developer.mozilla.org/docs/Web/API/Response)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global/set-interval.md
---

# setInterval() global function

APISummary
Repeatedly calls a function or executes a code fragment with a fixed time interval between each call.

## Syntax

```typescript
setInterval(function: () => void, delay: number): number;
```

### Parameters

#### function

Functions to be called repeatedly are executed after every specified `delay` milliseconds. The first call occurs after `delay` milliseconds.

#### delay

The time interval between repeated function calls, in milliseconds.

The js thread may be frozen while the app is in the background. Therefore, the actual delay of `setInterval` may be greater than the specified value. At the same time, the duration of the js thread being frozen will still be counted in the delay of `setInterval`. In this case, the specified function will only be called once immediately after the app wakes up, even if the js thread is frozen for a number of times longer than `delay`.

### Return value

Returns a positive integer representing the ID value of the timer. This ID value can be used to cancel the timer.

The front-end code should not make any assumptions about the actual value of the returned ID.

## Example

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.setInterval`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Repeatedly calls a function or executes a code fragment with a fixed time interval between each call.




---
url: /api/lynx-api/global/set-timeout.md
---

# setTimeout() global function

APISummary
The `setTimeout` method sets a timer that executes the specified function when it expires.

## Syntax

```typescript
setTimeout(function: () => void, delay?: number): number;
```

### Parameters

#### function

The function to be executed after the expiration time.

#### delay (Optional)

The number of milliseconds of delay after which the function call will occur.
If this parameter is omitted, `delay` takes the default value of 0, specifying that the function will be executed after the execution of existing tasks queued in the js thread task queue.

The js thread may be frozen while the app is in the background. As a result, the actual delay of `setTimeout` may be longer than the specified value.
Also, the duration of the frozen js thread will still be counted in the delay of `setTimeout`.

### Return Value

Returns a positive integer representing the ID value of the timer.
This ID value can be used to cancel the timer.

The front-end code should not make any assumptions about the actual value of the returned ID.

## Example

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.setTimeout`

**MDN Reference:** [https://developer.mozilla.org/en-US/docs/Web/API/setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/global/system-info.md
---

APISummary
# SystemInfo

`SystemInfo` is a plain JavaScript object that contains information of the current system.

## Syntax

```ts
declare const SystemInfo: {
  /**
   * The version of the Lynx Engine.
   *
   * @example '3.2'
   */
  readonly engineVersion: string;

  /**
   * The version of the Lynx Engine.
   * @example '3.2'
   * @deprecated Use `SystemInfo.engineVersion` instead
   */
  readonly lynxSdkVersion: string;

  /**
   * The current operating system version.
   */
  readonly osVersion: string;

  /**
   * The physical pixel height of the real device.
   */
  readonly pixelHeight: number;

  /**
   * The physical pixel width of the real device.
   */
  readonly pixelWidth: number;

  /**
   * The physical pixel ratio of the main screen.
   */
  readonly pixelRatio: number;

  /**
   * The platform of the current device.
   */
  readonly platform: 'Android' | 'iOS' | 'macOS' | 'windows' | 'headless';

  /**
   * The JavaScript engine currently used.
   * @note Not avaliable in lepus
   */
  readonly runtimeType: 'v8' | 'jsc' | 'quickjs';
};
```

### Fields

#### engineVersion

The Lynx Engine version, in format `major.minor`.

E.g.: `3.2`.

#### ~~lynxSdkVersion~~

The Lynx Engine version, in format `major.minor`.

E.g.: `3.2`.

#### osVersion

A string representing the current version of the operating system.


**iOS**

> [systemVersion | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uidevice/1620043-systemversion?language=objc)
```objc
[[UIDevice currentDevice].systemVersion UTF8String]
```


**Android**

Equivalent to the Java [`Build.VERSION.SDK_INT`](https://developer.android.com/reference/android/os/Build.VERSION#SDK_INT) API.
> [API Levels | Android NDK | Android Developers](https://developer.android.com/ndk/reference/group/apilevels#android_get_device_api_level)
```cpp
std::to_string(android_get_device_api_level())
```


#### pixelHeight

The absolute height of the available display size in pixels.


**iOS**

> [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)
```objc
CGSize screenSize;
if (!CGSizeEqualToSize(builder.screenSize, CGSizeZero)) {
  screenSize = builder.screenSize;
} else {
  screenSize = [UIScreen mainScreen].bounds.size;
}
const CGFloat scale = [UIScreen mainScreen].scale;
// highlight-next-line
const CGFloat pixelHeight = screenSize.height * scale;
```


**Android**

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)
```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
int pixelHeight = dm.heightPixels;
```


#### pixelWidth

The absolute width of the available display size in pixels.


**iOS**

> [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)
```objc
CGSize screenSize;
if (!CGSizeEqualToSize(builder.screenSize, CGSizeZero)) {
  screenSize = builder.screenSize;
} else {
  screenSize = [UIScreen mainScreen].bounds.size;
}
const CGFloat scale = [UIScreen mainScreen].scale;
// highlight-next-line
const CGFloat pixelWidth = screenSize.width * scale;
```


**Android**

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics)
```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
int pixelWidth = dm.widthPixels;
```


#### pixelRatio

The natural scale factor associated with the screen.


**iOS**

> [UIScreen | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uiscreen?language=objc)
```objc
const CGFloat pixelRatio = [UIScreen mainScreen].scale;
```


**Android**

> [DisplayMetrics | Android Developers](https://developer.android.com/reference/android/util/DisplayMetrics#density)
```java
DisplayMetrics dm = context.getResources().getDisplayMetrics();
// highlight-next-line
float pixelRatio = dm.density;
```


#### platform

The platform of the current device.

Candidate values:

1. `iOS`
2. `Android`
3. `macOS`
4. `windows`

#### runtimeType

The JavaScript engine currently used.

:::info
This is only avaliable in the background thread.
:::

Candidate values:

1. `quickjs`
2. `jsc`
3. `v8`

See [JavaScript Environment](/guide/scripting-runtime/index.md) for more details.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.global.SystemInfo`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | 1.0 | only support SystemInfo.platform; ⚠️ Partial implementation |

**Description:** Information of the current system




---
url: /api/lynx-api/intersection-observer.md
---

# IntersectionObserver

APISummary
`IntersectionObserver` is used to observe the intersection status between the target node and the reference node and the target node and the ancestor node. When the intersection status changes, the corresponding callback is triggered. Based on this, you can monitor whether the target node is exposed/de-exposed.

## Instance method

[`IntersectionObserver.relativeTo()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to.md)

Specify the reference node, which is specified based on `id`.

[`IntersectionObserver.relativeToViewport()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md)

Specify `LynxView` as the reference node.

[`IntersectionObserver.relativeToScreen()`](/api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md)

Specify the screen as the reference node.

[`IntersectionObserver.observer()`](/api/lynx-api/intersection-observer/intersection-observer-observe.md)

Specify the target node and callback. The target node is specified based on `id`.

[`IntersectionObserver.disconnect()`](/api/lynx-api/intersection-observer/intersection-observer-disconnect.md)

Clear the target node and callback, the target node will no longer be observed, and the corresponding callback will not be triggered.

## Example

You can observe changes in the intersection status of the target node and the reference node through the following three steps:

1. Create an `IntersectionObserver` object and specify a threshold list for intersection state changes
2. Call the `relativeTo*` method of the `IntersectionObserver` object to specify the reference node
3. Call the `observe` method of the `IntersectionObserver` object to specify the target node and callback
4. Call the `disconnect` method of the `IntersectionObserver` object to clear the target node and callback

```tsx
// 1. Create IntersectionObserver object
const observer = lynx.createIntersectionObserver(this, {
  thresholds: [0, 0.25, 0.5, 0.75, 1.0],
});

// 2. Call the relativeTo method to specify the reference node
observer.relativeTo('#refNode', { left: 10, right: 10 });

// 3. Call the observe method to specify the target node and callback
observer.observe('#targetNode', (res) => {
  console.log('IntersectionObserver: ', JSON.stringify(res));
});

// 4. Call the disconnect method to clear the target node and callback
observer.disconnect();
```

## Precautions

- It is recommended to set the page switch `enableNewIntersectionObserver` to `true`, otherwise the scrollable container needs to be bound to the corresponding scroll event (such as `scroll`) to trigger the corresponding callback.
- When using `relativeTo` and `observe` methods, you need to pay attention to the calling timing and ensure that the reference node and target node have been created when calling. Otherwise, the observation will be invalid, that is, the corresponding callback will never be triggered.
- When `enableNewIntersectionObserver` is enabled, child nodes of a scroll-view on Android will not trigger corresponding callbacks when scrolling. You need to set [`flatten`](/api/elements/built-in/view.md#flatten) to `false` on the child node to trigger the callback.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.IntersectionObserver`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Observe the intersection status between the target node and the reference node and the target node and the ancestor node. When the intersection status changes, the corresponding callback is triggered. Based on this, you can monitor whether the target node is exposed/de-exposed.




---
url: /api/lynx-api/intersection-observer/intersection-observer-disconnect.md
---

# IntersectionObserver: disconnect() method

APISummary
The `disconnect` method can be used to clear the target node and callback. The target node will no longer be observed and the corresponding callback will not be triggered. If you need to re-observe the target node, you need to re-specify the target node and callback.

## grammar

```ts
disconnect(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.disconnect`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Clear the target node and callback. The target node will no longer be observed and the corresponding callback will not be triggered.




---
url: /api/lynx-api/intersection-observer/intersection-observer-observe.md
---

# IntersectionObserver: observe() method

APISummary
`observe` specifies the target node and callback, and the target node is specified according to `id`.

## grammar

```ts
observe(selector: string, callback: Function): void;
```

### Parameters

#### selector

```ts
selector: string;
```

Specify the id used when searching for the target node. The `id` will be searched first in the `component` passed in when creating the `IntersectionObserver` object. If not found, the global search will be performed. If the global search is not found, the specification will be invalid.

#### callback

```ts
callback: (res) => {};
```

Specify the callback triggered when the intersection status of the target node and the reference node changes.
The format of the callback parameter `res` is as follows:

```ts
{
     "isIntersecting": boolean, // Whether the target node intersects with the reference node
     "intersectionRatio": number, // The intersection ratio between the target node and the reference node
     "intersectionRect": object, // The intersection area between the target node and the reference node
     "boundingClientRect": object, // The intersection area of the target node
     "relativeRect": object, // The intersection area of the reference node
     "observerId": string, // The id of the target node
     "time": number, // timestamp during intersection detection (not implemented, now returns are all 0)
}
```

The structures of `intersectionRect`, `boundingClientRect` and `relativeRect` are the same. The coordinate systems are all relative to `LynxView`, that is, the upper left corner of `LynxView` is the origin of the coordinate system, with the horizontal direction to the right being the positive direction of the `x`-axis, and the vertical direction being downwards being the positive direction of the `y`-axis:

```ts
{
     "left": number | 0, // left boundary of the intersection area
     "right": number | 0, // Right boundary of the intersection area
     "top": number | 0, // The upper boundary of the intersection area
     "bottom": number | 0, // The lower boundary of the intersection area
}
```

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.observe`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Specify the target node and callback, and the target node is specified according to id.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-screen.md
---

# IntersectionObserver: relativeToScreen() method

APISummary
The `relativeToScreen` method can be used to specify the screen as the reference node, and the reference node's viewport can be scaled according to `margins`.

## grammar

```ts
relativeToScreen(
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

- The intersection ratio of the target node and the screen (scaled by `margins`)
- The intersection ratio between the target node and `LynxView`
- The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeToScreen`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.10 | - |
| iOS | 2.10 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Specify the screen as the reference node.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to-viewport.md
---

# IntersectionObserver: relativeToViewport() method

APISummary
The `relativeToViewport` method can be used to specify a `LynxView` as a reference node, and the reference node's viewport can be scaled according to `margins`.

## grammar

```ts
relativeToViewport(
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

- The intersection ratio between the target node and `LynxView` (scaled by `margins`)
- The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeToViewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Specify a LynxView as a reference node.




---
url: /api/lynx-api/intersection-observer/intersection-observer-relative-to.md
---

# IntersectionObserver: relativeTo() method

APISummary
The `relativeTo` method can be used to specify a reference node. The reference node is specified by `id`. The viewport of the reference node can be scaled according to `margins`.

## grammar

```ts
relativeTo(
   selector: string,
   margins ? margins : {left: 0, right: 0, top: 0, bottom: 0}
): IntersectionObserver;
```

### Parameters

#### selector

```ts
selector: string;
```

Specify the `id` used when searching for the reference node. It will first search in the `component` passed in when creating the `IntersectionObserver` object. If not found, the global search will be performed. If the global search is not found, `LynxView` will be used as the reference node.

#### margins

```ts
margins ? margins : { left: 0, right: 0, top: 0, bottom: 0 };
```

Specifies the zoom value of the reference node window. This value only affects the detection of the intersection state and does not affect the actual view display. A positive value means expanding the reference node window boundary, and a negative value means shrinking the reference node window boundary.

| Property name | Type              | Description                                                |
| ------------- | ----------------- | ---------------------------------------------------------- |
| `left`        | `number ｜ string` | The scaling value of the left boundary of the target node  |
| `right`       | `number ｜ string` | The scaling value of the right boundary of the target node |
| `top`         | `number ｜ string` | The scaling value of the upper boundary of the target node |
| `bottom`      | `number ｜ string` | The scaling value of the lower boundary of the target node |

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

### Precautions

The intersection state between the target node and the reference node and the target node and the ancestor node is defined as the smallest intersection ratio as follows:

1. When the reference node is valid, that is, the reference node is the ancestor node of the target node, select the smallest
   - The intersection ratio of the target node and the reference node (scaled by `margins`)
   - The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to the reference node. The ancestor node will be ignored when `overflow: visible` is set.
2. When the reference node is invalid, that is, the reference node is not the ancestor node of the target node or there is no node with the `id` set, select the smallest one below
   - The intersection ratio between the target node and `LynxView` (scaled by `margins`)
   - The intersection ratio between the target node and the ancestor node. The ancestor node includes the nodes on the path from the target node to `LynxView`. The ancestor node will be ignored when `overflow: visible` is set.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.intersection-observer.relativeTo`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Specify a reference node. The reference node is specified by id.




---
url: /api/lynx-api/lynx.md
---

# Overview

## accessibilityAnnounce()

### [accessibilityAnnounce()](/api/lynx-api/lynx/lynx-accessibility-announce.md)

- [Syntax](/api/lynx-api/lynx/lynx-accessibility-announce.md#syntax)
- [示例](/api/lynx-api/lynx/lynx-accessibility-announce.md#示例)
- [Compatibility](/api/lynx-api/lynx/lynx-accessibility-announce.md#compatibility)
## addFont()

### [addFont()](/api/lynx-api/lynx/lynx-add-font.md)

- [Syntax](/api/lynx-api/lynx/lynx-add-font.md#syntax)
- [Example](/api/lynx-api/lynx/lynx-add-font.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-add-font.md#compatibility)
## animate()

### [animate()](/api/lynx-api/lynx/lynx-animate-api.md)

- [Introduction](/api/lynx-api/lynx/lynx-animate-api.md#introduction)
- [Syntax](/api/lynx-api/lynx/lynx-animate-api.md#syntax)
- [Example](/api/lynx-api/lynx/lynx-animate-api.md#example)
- [Animation Event](/api/lynx-api/lynx/lynx-animate-api.md#animation-event)
- [Other Infos](/api/lynx-api/lynx/lynx-animate-api.md#other-infos)
- [See also](/api/lynx-api/lynx/lynx-animate-api.md#see-also)
- [Compatibility](/api/lynx-api/lynx/lynx-animate-api.md#compatibility)
## BeforePublishEvent

### [add()](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md)

- [grammar](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md#grammar)
- [Compatibility](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md#compatibility)

### [remove()](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md)

- [grammar](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md#grammar)
- [Compatibility](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md#compatibility)
## cancelAnimationFrame()

### [cancelAnimationFrame()](/api/lynx-api/lynx/lynx-cancel-animation-frame.md)

- [Syntax](/api/lynx-api/lynx/lynx-cancel-animation-frame.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-cancel-animation-frame.md#compatibility)
## cancelResourcePrefetch()

### [cancelResourcePrefetch()](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md)

- [Syntax](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md#syntax)
- [Exceptions](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md#exceptions)
- [Example](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-cancel-resource-prefetch.md#compatibility)
## createIntersectionObserver()

### [createIntersectionObserver()](/api/lynx-api/lynx/lynx-create-intersection-observer.md)

- [grammar](/api/lynx-api/lynx/lynx-create-intersection-observer.md#grammar)
- [Example](/api/lynx-api/lynx/lynx-create-intersection-observer.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-create-intersection-observer.md#compatibility)
## createSelectorQuery()

### [createSelectorQuery()](/api/lynx-api/lynx/lynx-create-selector-query.md)

- [Syntax](/api/lynx-api/lynx/lynx-create-selector-query.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-create-selector-query.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-create-selector-query.md#compatibility)
## getElementById()

### [getElementById()](/api/lynx-api/lynx/lynx-get-element-by-id.md)

- [Introduction](/api/lynx-api/lynx/lynx-get-element-by-id.md#introduction)
- [Syntax](/api/lynx-api/lynx/lynx-get-element-by-id.md#syntax)
- [Example](/api/lynx-api/lynx/lynx-get-element-by-id.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-get-element-by-id.md#compatibility)
## getJSModule()

### [getJSModule()](/api/lynx-api/lynx/lynx-get-js-module.md)

- [Syntax](/api/lynx-api/lynx/lynx-get-js-module.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-get-js-module.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-get-js-module.md#compatibility)
## getSessionStorageItem

### [getSessionStorageItem](/api/lynx-api/lynx/lynx-get-session-storage.md)

- [Syntax](/api/lynx-api/lynx/lynx-get-session-storage.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-get-session-storage.md#compatibility)
## getTextInfo()

### [getTextInfo()](/api/lynx-api/lynx/lynx-get-text-info.md)

- [Syntax](/api/lynx-api/lynx/lynx-get-text-info.md#syntax)
- [Example](/api/lynx-api/lynx/lynx-get-text-info.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-get-text-info.md#compatibility)
## GlobalProps

### [GlobalProps](/api/lynx-api/lynx/lynx-global-props.md)

- [Usage](/api/lynx-api/lynx/lynx-global-props.md#usage)
- [Event Listening](/api/lynx-api/lynx/lynx-global-props.md#event-listening)
- [Client side](/api/lynx-api/lynx/lynx-global-props.md#client-side)
- [Compatibility](/api/lynx-api/lynx/lynx-global-props.md#compatibility)
## performance

### [createObserver()](/api/lynx-api/lynx/lynx-performance/create-observer.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/create-observer.md#compatibility)

### [profileStart()](/api/lynx-api/lynx/lynx-performance/profile-start.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/profile-start.md#compatibility)

### [profileEnd()](/api/lynx-api/lynx/lynx-performance/profile-end.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/profile-end.md#compatibility)

### [profileMark()](/api/lynx-api/lynx/lynx-performance/profile-mark.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/profile-mark.md#compatibility)

### [profileFlowId()](/api/lynx-api/lynx/lynx-performance/profile-flow-id.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/profile-flow-id.md#compatibility)

### [isProfileRecording()](/api/lynx-api/lynx/lynx-performance/is-profile-recording.md)

- [Compatibility](/api/lynx-api/lynx/lynx-performance/is-profile-recording.md#compatibility)
## queueMicrotask()

### [queueMicrotask()](/api/lynx-api/lynx/lynx-queue-microtask.md)

- [Syntax](/api/lynx-api/lynx/lynx-queue-microtask.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-queue-microtask.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-queue-microtask.md#compatibility)
## registerModule()

### [registerModule()](/api/lynx-api/lynx/lynx-register-module.md)

- [Syntax](/api/lynx-api/lynx/lynx-register-module.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-register-module.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-register-module.md#compatibility)
## reload()

### [reload()](/api/lynx-api/lynx/lynx-reload.md)

- [Syntax](/api/lynx-api/lynx/lynx-reload.md#syntax)
- [Notices](/api/lynx-api/lynx/lynx-reload.md#notices)
- [Compatibility](/api/lynx-api/lynx/lynx-reload.md#compatibility)
## reportError()

### [reportError()](/api/lynx-api/lynx/lynx-report-error.md)

- [Syntax](/api/lynx-api/lynx/lynx-report-error.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-report-error.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-report-error.md#compatibility)
## requestAnimationFrame()

### [requestAnimationFrame()](/api/lynx-api/lynx/lynx-request-animation-frame.md)

- [Syntax](/api/lynx-api/lynx/lynx-request-animation-frame.md#syntax)
- [Examples](/api/lynx-api/lynx/lynx-request-animation-frame.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-request-animation-frame.md#compatibility)
## requestResourcePrefetch()

### [requestResourcePrefetch()](/api/lynx-api/lynx/lynx-request-resource-prefetch.md)

- [Syntax](/api/lynx-api/lynx/lynx-request-resource-prefetch.md#syntax)
- [Errors](/api/lynx-api/lynx/lynx-request-resource-prefetch.md#errors)
- [Example](/api/lynx-api/lynx/lynx-request-resource-prefetch.md#example)
- [Compatibility](/api/lynx-api/lynx/lynx-request-resource-prefetch.md#compatibility)
## requireModuleAsync()

### [requireModuleAsync()](/api/lynx-api/lynx/lynx-require-module-async.md)

- [Syntax](/api/lynx-api/lynx/lynx-require-module-async.md#syntax)
- [Exception](/api/lynx-api/lynx/lynx-require-module-async.md#exception)
- [Examples](/api/lynx-api/lynx/lynx-require-module-async.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-require-module-async.md#compatibility)
## requireModule()

### [requireModule()](/api/lynx-api/lynx/lynx-require-module.md)

- [Syntax](/api/lynx-api/lynx/lynx-require-module.md#syntax)
- [Exception](/api/lynx-api/lynx/lynx-require-module.md#exception)
- [Examples](/api/lynx-api/lynx/lynx-require-module.md#examples)
- [Compatibility](/api/lynx-api/lynx/lynx-require-module.md#compatibility)
## resumeExposure()

### [resumeExposure()](/api/lynx-api/lynx/lynx-resume-exposure.md)

- [Syntax](/api/lynx-api/lynx/lynx-resume-exposure.md#syntax)
- [Precautions](/api/lynx-api/lynx/lynx-resume-exposure.md#precautions)
- [Compatibility](/api/lynx-api/lynx/lynx-resume-exposure.md#compatibility)
## setObserverFrameRate()

### [setObserverFrameRate()](/api/lynx-api/lynx/lynx-set-observer-frame-rate.md)

- [grammar](/api/lynx-api/lynx/lynx-set-observer-frame-rate.md#grammar)
- [Compatibility](/api/lynx-api/lynx/lynx-set-observer-frame-rate.md#compatibility)
## setSessionStorageItem

### [setSessionStorageItem](/api/lynx-api/lynx/lynx-set-session-storage.md)

- [Syntax](/api/lynx-api/lynx/lynx-set-session-storage.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-set-session-storage.md#compatibility)
## stopExposure()

### [stopExposure()](/api/lynx-api/lynx/lynx-stop-exposure.md)

- [Syntax](/api/lynx-api/lynx/lynx-stop-exposure.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-stop-exposure.md#compatibility)
## subscribeSessionStorage

### [subscribeSessionStorage](/api/lynx-api/lynx/lynx-subscribe-session-storage.md)

- [Syntax](/api/lynx-api/lynx/lynx-subscribe-session-storage.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-subscribe-session-storage.md#compatibility)
## unsubscribeSessionStorage

### [unsubscribeSessionStorage](/api/lynx-api/lynx/lynx-unsubscribe-session-storage.md)

- [Syntax](/api/lynx-api/lynx/lynx-unsubscribe-session-storage.md#syntax)
- [Compatibility](/api/lynx-api/lynx/lynx-unsubscribe-session-storage.md#compatibility)



---
url: /api/lynx-api/lynx/lynx-accessibility-announce.md
---

# lynx: accessibilityAnnounce() static method

APISummary
Makes screen readers announce the specified text content, helping visually impaired users perceive interface state changes or operation results.

## Syntax

```ts
accessibilityAnnounce({"content" : string}) : void;
```

### Parameter

#### `content`

The text content to be announced

## 示例

```jsx
lynx.accessibilityAnnounce(
  {
    content: 'hello lynx',
  },
  (res) => {
    console.log('test: ' + JSON.stringify(res));
  },
);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.accessibilityAnnounce`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to have the specified text content read by the screen reader.




---
url: /api/lynx-api/lynx/lynx-add-font.md
---

# lynx: addFont() static method

APISummary
Used for dynamically adding fonts.

## Syntax

```ts
export interface FontFace {
  'font-family': string;
  'src': string;
}

addFont(fontFace: FontFace, callback?: () => void): void;
```

### Parameter

#### fontFace

The font to be added.

#### callback

The callback after adding the font.

## Example

```ts
lynx.addFont(
  {
    'font-family': 'CustomFont',
    src: 'url("xxx")',
  },
  () => {
    console.log('load font');
  },
);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.addFont`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.12 | - |
| iOS | 2.12 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used for dynamically adding fonts.




---
url: /api/lynx-api/lynx/lynx-animate-api.md
---

# animate()

APISummary
## Introduction

Use `animate()` to set a [CSS Animation](/api/css/properties/animation.md) on UI elements.

1. Use the [getElementById](/api/lynx-api/lynx/lynx-get-element-by-id.md) API to find the `Element` object that needs to be animated based on its `id`.
2. Call the `animate` API on the `Element` object to achieve animation.

## Syntax

```js
animate(keyframes, options);
```

### Parameter

#### keyframes

There are **two different formats**:

1. An **array** consisting of objects that contain properties and values of multiple keyframes.

```js
element.animate(
  [
    {
      // from
      opacity: 0,
      color: '#fff',
    },
    {
      // to
      opacity: 1,
      color: '#000',
    },
  ],
  2000,
);
```

2. An **object** consisting of keys as offsets and values as keyframes.

```js
element.animate({
  '0%': {
    // from
    opacity: 0,
    color: '#fff',
  },
  '50%': {
    // 50%
    opacity: 0.5,
    color: '#aaa',
  },
  '100%': {
    // to
    opacity: 1,
    color: '#000',
  },
});
```

3. You can also assign a [timing-function](/api/css/properties/animation-timing-function.md) for each keyframe.

```js
element.animate([
  {
    // from
    opacity: 0,
    color: '#fff',
    'animation-timing-function': 'linear',
  },
  {
    // to
    opacity: 1,
    color: '#000',
    'animation-timing-function': 'ease-in',
  },
]);
```

#### options

An **object** that contains one or more properties:

| Key        | Value Type | Optional | Description                                                                                                                                                                                                                                                                        | Default Value          |
| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| duration   | Number     | optional | The length of time for the animation to run.                                                                                                                                                                                                                                       | 0                      |
| delay      | Number     | optional | The length of time to wait before starting the animation.                                                                                                                                                                                                                          | 0                      |
| iterations | Number     | optional | The number of times the animation should repeat. You can set this to `Infinity` to make the animation loop indefinitely.                                                                                                                                                           | 1                      |
| direction  | String     | optional | Whether the animation runs forwards (`normal`), backwards (`reverse`), switches direction after each iteration (`alternate`), or runs backwards and switches direction after each iteration (`alternate-reverse`). Defaults to `"normal"`.                                         | `"normal"`             |
| easing     | String     | optional | The rate of the animation's change over time. Accepts an [timing-function](/api/css/properties/animation-timing-function.md), such as `"linear"`, `"ease-in"`, or `"cubic-bezier(0.42, 0, 0.58, 1)"`. Defaults to "linear".                                                        | `"linear"`             |
| fill       | String     | optional | Dictates whether the animation's effects should be reflected by the element(s) prior to playing ("backwards"), retained after the animation has completed playing ("forwards"), or both. Defaults to "none".                                                                       | `"none"`               |
| name       | String     | optional | The name of the animation, which can be used to uniquely identify it. This name appears in the [animation events](/api/lynx-api/event/animation-event.md#animation) parameters and is typically used to determine if a particular animation event is the one you're interested in. | An internal unique ID. |
| play-state | String     | optional | Animation motion state, which defines whether an animation is running or paused, accepts an [animation-play-state](/api/css/properties/animation-play-state.md)                                                                                                                    | running                |

:::info Note:

1. If no `name` is specified, a unique id is generated incrementally.
2. An animation with the same `name` cannot be triggered consecutively multiple times.

:::

### Return Value

Returns an `Animation` object.
The `Animation` object has the following methods:

| Method Name          | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `Animation.cancel()` | Cancels the animation and triggers the `animation cancel` event. |
| `Animation.pause()`  | Pauses the animation.                                            |
| `Animation.play()`   | Resumes the animation.                                           |

## Example

### by getElementById()

```js
let ani = lynx.getElementById('test').animate(
  [
    {
      'background-color': 'blue',
      transform: 'translateX(100px) translateY(300px) rotate(360deg)',
    },
    {
      'background-color': 'red',
      transform: 'translateX(0px) translateY(600px) rotate(0deg)',
    },
  ],
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

// When the parameter is Object, it is strictly required to write percentages with a percent sign such as '.50' and '50' equivalents are divided by 100
let ani = lynx.getElementById('test').animate(
  {
    '0%': {
      transform: 'rotate(0deg)',
      left: '0px',
    },
    '50%': {
      // The properties of the intermediate frame can default.
      left: '30px',
    },
    '100%': {
      transform: 'rotate(225deg)',
      left: '100px',
    },
  },
  {
    duration: 3000,
    delay: 1000,
    iterations: Infinity,
    direction: 'alternate',
    easing: 'ease-in-out',
    fill: 'both',
  },
);

ani.pause();
ani.play();
ani.cancel();
```

::: note

- Each call to `getElementById("test").animate` will generate a new `Animation` object, and the later created animation will override the previous ones.
- If you want to restart the same animation, you need to call `getElementById("test").animate` again to create a new `Animation` object.

:::

### by createSelectorQuery() 3.4

After **Lynx version 3.4**, the `animate()` can be called via the `createSelectorQuery()`.

**It's an experimental feature, and you should use it with caution.**

```js
const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1'])
  .exec();
```

### Multiple animate 3.4

After **Lynx version 3.4**, you can chain multiple animation with `createSelectorQuery()`.

**It's an experimental feature, and you should use it with caution.**

```js
const ani1 = lynx.createAnimation(
  'ani1',
  [
    {
      transform: 'translateY(0px)',
    },
    {
      transform: 'translateY(-150px)',
    },
  ],
  {
    name: 'js-animation-1',
    duration: 3000,
    iterations: 'infinite',
    easing: 'cubic-bezier(.64, .57, .67, 1.53)',
    fill: 'forwards',
  },
);

const ani2 = lynx.createAnimation(
  'ani2',
  [
    {
      'background-color': 'red',
    },
    {
      'background-color': 'blue',
    },
  ],
  {
    name: 'js-animation-2',
    duration: 3000,
    easing: 'linear',
    fill: 'forwards',
    iterations: 'infinite',
  },
);

// start
this.createSelectorQuery().select('#test').animate([ani1, ani2]).exec();
// pause
this.createSelectorQuery()
  .select('#test')
  .pauseAnimation(['js-animation-1', 'js-animation-2'])
  .exec();
```

## Animation Event

The events for the `animate()` API are the same as the [animation events](/api/lynx-api/event/animation-event.md#animation) for CSS animations.

## Other Infos

:::tip

- Animate Api and CSS Animation will override each other, and the one that takes effect later will override the former.

- The Animate API may not take effect, possibly because `getElementById` failed to select the node:
  - The ID selector might be incorrect
  - The value of the ID selector might depend on a complex JS expression, causing the value of the ID selector not to be available on the first screen. In this case, if getElementById is invoked too early (like in ComponentDidMount), it might not find the node.

:::

## See also

- [Introduction to CSS Animations](/guide/styling/animation.md)
- [Animate API in MTS](/api/lynx-api/main-thread/lynx-animate-api.md)

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.animateAPI`


---
url: /api/lynx-api/lynx/lynx-before-publish-event.md
---

# BeforePublishEvent

APISummary
`lynx.beforePublishEvent` is used to register/remove listening for an element event.

## Instance methods

[`BeforePublishEvent.add()`](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md)

Register a listener for an element event.

[`BeforePublishEvent.remove()`](/api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md)

Remove listening for an element event.

## Example

Register/remove listening for a certain element event.

```tsx
//Register to listen for the tap event
lynx.beforePublishEvent.add('tap', this.handleTap);

//Remove monitoring of tap event
lynx.beforePublishEvent.remove('tap', this.handleTap);
```

## Precautions

Since this is an aspect interface on the background thread, the element element needs to be bound to the corresponding event and triggered, so that the aspect interface can listen to the element event.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.BeforePublishEvent`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to register/remove monitoring of an element event




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-add.md
---

# BeforePublishEvent: add() method

APISummary
The `add` method can be used to register listening for a certain element event.

## grammar

```ts
add(name: string, listener: () => {}, context?: BaseInstance): BeforePublishEvent;
```

### Parameters

#### name

```ts
name: string;
```

Specify the name of the element event to be listened to.

#### listener

```ts
listener: () => {};
```

Specify the listening callback.

#### context

```ts
context?: BaseInstance
```

Front-end custom `component` or `card` instance.

### return value

`BeforePublishEvent` object.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.add`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Register to listen for an element event.




---
url: /api/lynx-api/lynx/lynx-before-publish-event/before-publish-event-remove.md
---

# BeforePublishEvent: remove() method

APISummary
The `remove` method can be used to remove listening for a certain element event.

## grammar

```ts
remove(name: string, listener: () => {}): BeforePublishEvent;
```

### Parameters

#### name

```ts
name: string;
```

Specifies the name of the element event to be listened to.

#### listener

```ts
listener: () => {};
```

Specify the listening callback.

### return value

`BeforePublishEvent` object.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.lynx-before-publish-event.remove`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Remove monitoring of an element event.




---
url: /api/lynx-api/lynx/lynx-cancel-animation-frame.md
---

# lynx: cancelAnimationFrame() static method

APISummary
Cancel a [`requestAnimationFrame`] callback.

## Syntax

```ts
cancelAnimationFrame: (requestID: number) => void;
```

### Parameters

#### requestID

The return value of the [`requestAnimationFrame`] that needs to be cancelled.

### Return Value

None (`undefined`).

[`requestAnimationFrame`]: /api/lynx-api/lynx/lynx-request-animation-frame.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.cancelAnimationFrame`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Cancel a `requestAnimationFrame` callback.




---
url: /api/lynx-api/lynx/lynx-cancel-resource-prefetch.md
---

# lynx: cancelResourcePrefetch() static method

APISummary
- This API is used to cancel resource preloading initiated by [requestResourcePrefetch](/api/lynx-api/lynx/lynx-request-resource-prefetch.md).

## Syntax

```ts
cancelResourcePrefetch(data: object, callback: (res: object) => void) : void;
```

### Parameters

#### `data`

A collection that describes the details of all resources to be canceled for preloading, with its keys defined as follows:

- `data`: Type `array`, each item inside the array corresponds to a resource. The keys for each item are defined as follows:
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of resource. The supported resource types are defined as follows:
    - `video`: Audio/video resources (preloading cancellation for image and font resources is currently not supported)
  - `params`: Custom control parameters for canceling preloading, the supported parameters are as follows:
    - `preloadKey`: Only for `video` type resources. Represents a unique key that identifies the resource. It is necessary to ensure that the `preloadKey` passed here is consistent with that used when calling [requestResourcePrefetch](/api/lynx-api/lynx/lynx-request-resource-prefetch.md). This is a required parameter.

#### `callback`

The callback function that is called after the API execution is completed or fails. The structure of its return parameters is as follows:

- `code`: Type `number`, status code, which may take the following values:
  - `0`: Success
  - `11001`: Parameter error
- `msg`: Type `string`, a global error message
- `details`: Type `array`, where each detail represents the cancelation status details of a resource. The structure of each detail is as follows:
  - `code`: Type `number`, status code, which may take the following values:
    - `0`: Success
    - `11001`: Parameter error
  - `msg`: Type `string`, error message
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of the resource, defined as follows:
    - `video`: Audio/video resources

### Return Value

None (`undefined`).

## Exceptions

- When there is a parameter error, `code` will return the `11001` error code, and the `msg` will contain detailed error information.

## Example

```js
import { useEffect } from '@lynx-js/react';

function Page() {
  // We need to preload two videos.
  // First, prepare the resource parameters, assigning the necessary preloadKey to the videos.
  let resData = [
    {
      uri: 'https://zzzzz1.mp4',
      type: 'video',
      params: { preloadKey: 'zzzzz1' },
    },
    {
      uri: 'https://zzzzz2.mp4',
      type: 'video',
      params: { preloadKey: 'zzzzz2' },
    },
  ];

  useEffect(() => {
    // Call requestResourcePrefetch to initiate preloading
    lynx.requestResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'prefetch status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  }, []);

  const handleTap = () => {
    // Trigger the cancellation of resource preloading on click
    // Call cancelResourcePrefetch to cancel the preloading
    lynx.cancelResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'cancel status of each resource:',
          JSON.stringify(res.details),
        );
      },
    );
  };

  return <view onTap={handleTap}>{/* ... */}</view>;
}

export default Page;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.cancelResourcePrefetch`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to cancel the prefetch of resource.




---
url: /api/lynx-api/lynx/lynx-create-intersection-observer.md
---

# lynx: createIntersectionObserver() static method

APISummary
The `lynx.createIntersectionObserver` method can be used to create an `IntersectionObserver` object. The object behavior can be customized by passing in parameters. Once the object is created, it cannot be modified.

## grammar

```ts
lynx.createIntersectionObserver(
   component: BaseInstance,
   options ? options : {
     thresholds : [0],
     initialRatio: 0,
     observeAll : false,
   }
): IntersectionObserver;
```

### Parameters

#### component

```ts
component: BaseInstance;
```

For front-end custom `component` or `card` instances, the target node and reference node are searched first in this `component`. If not found, the global search is performed.

#### options

```ts
options
  ? options
  : {
      thresholds: [0],
      initialRatio: 0,
      observeAll: false,
    };
```

Specify the behavior of `IntersectionObserver` objects:

- `thresholds`: The valid range of each array element is `[0, 1]`, specifying a threshold list for intersection state changes. When the intersection ratio of the target node and the reference node passes one of the thresholds, a callback is triggered, and the old intersection ratio is represented. and the new intersection ratio is on either side of the threshold or the intersection ratio is equal to the threshold
- `initialRatio`: The valid range is `[0, 1]`, which specifies the threshold for triggering the callback when detected for the first time. The callback is triggered when the intersection ratio of the first detection is greater than the threshold.
- `observeAll`: Specify whether to observe multiple target nodes at the same time

### return value

[IntersectionObserver object](/api/lynx-api/intersection-observer.md).

## Example

You can observe changes in the intersection status of the target node and the reference node through the following three steps:

1. Create an `IntersectionObserver` object and specify a threshold list for intersection state changes
2. Call the `relativeTo*` method of the `IntersectionObserver` object to specify the reference node
3. Call the `observe` method of the `IntersectionObserver` object to specify the target node and callback
4. Call the `disconnect` method of the `IntersectionObserver` object to clear the target node and callback

```tsx
// 1. Create IntersectionObserver object
const observer = lynx.createIntersectionObserver(this, {
  thresholds: [0, 0.25, 0.5, 0.75, 1.0],
});

// 2. Call the relativeTo method to specify the reference node
observer.relativeTo('#refNode', { left: 10, right: 10 });

// 3. Call the observer method to specify the target node and callback
observer.observe('#targetNode', (res) => {
  console.log('IntersectionObserver: ', JSON.stringify(res));
});

// 4. Call the disconnect method to clear the target node and callback
observer.disconnect();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.createIntersectionObserver`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.5 | - |
| iOS | 1.5 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 3.5 | - |
| Clay iOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Clay macOS | 3.5 | - |
| Web | ❌ No | - |

**Description:** Create an IntersectionObserver object.




---
url: /api/lynx-api/lynx/lynx-create-selector-query.md
---

# lynx: createSelectorQuery() static method

APISummary
Create a [`SelectorQuery`] with the root node of the page as the root.

## Syntax

```ts
createSelectorQuery(): SelectorQuery;
```

### Parameter

None.

### Return Value

A [`SelectorQuery`] object with the root node of the page as the root.

## Examples

Obtain the position and size of the specified `text` node:

```jsx
import { useEffect } from '@lynx-js/react';

function App() {
  useEffect(() => {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }, []);

  return (
    <view>
      <text id="my-id">Hello, ReactLynx</text>
    </view>
  );
}
```

[`SelectorQuery`]: /api/lynx-api/selector-query.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.createSelectorQuery`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:**  Create a `SelectorQuery` with the root node of the page as the root.




---
url: /api/lynx-api/lynx/lynx-get-element-by-id.md
---

# getElementById()

APISummary
## Introduction

getElementById is a method for finding elements' reference based on a specified id in the current [page](/guide/spec.md#page).
This method takes an id selector as the parameter and returns a reference to the corresponding element's reference.
Please note that this reference does not allow background threads to hold the elements;
background threads can only use this reference to [inter thread call](/guide/spec.md#inter-thread-call-or-itc) [element methods](/guide/spec.md#element-method) across threads,
and this reference does not affect the element's lifecycle.

## Syntax

```js
let element = lynx.getElementById(id);
```

### Parameter

#### id

A String type, the id selector of the element to be obtained.

### Return Value

Returns a NodeRef: If the corresponding element is found, a reference to the element is returned; if no corresponding element is found, null is returned.

## Example

```js
let ele = lynx.getElementById('id');
```

::: tip

The reasons that `getElementById` may not select nodes are:

- The ID selector is incorrect
- The value of the ID selector depends on complex JS expressions, so that the value of the ID selector cannot be obtained at the first screen. At this time, if getElementById is too early (such as in ComponentDidMount), it may not find the node

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getElementById`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to import modules.




---
url: /api/lynx-api/lynx/lynx-get-js-module.md
---

# lynx: getJSModule() static method

APISummary
Acquire a JavaScript value that can be shared within a single LynxView, but not between different LynxViews.

## Syntax

```ts
getJSModule: <Module>(name: string) => Module;
```

### Parameters

#### name

The name of the value that registered using [`lynx.registerModule`].

### Return Value

The registered value.

If the `name` is not registered, return `undefined`.

## Examples

### Get module from JS

Use the [`lynx.registerModule`] method to register a value:

```js
const fooModule = {};
lynx.registerModule('foo', fooModule);
lynx.getJSModule('foo') === fooModule; // true
```

[`lynx.registerModule`]: /api/lynx-api/lynx/lynx-register-module.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getJSModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |




---
url: /api/lynx-api/lynx/lynx-get-session-storage.md
---

# lynx: getSessionStorageItem() static method

APISummary
The `lynx.getSessionStorageItem` method is used to retrieve data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/lynx/lynx-set-session-storage.md) to set the cached data.

## Syntax

```ts
lynx.getSessionStorageItem(key, (value) => {});
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### callback

The callback function for retrieving cached data. The argument is the cached data object.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getSessionStorageItem`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.getSessionStorageItem` method is used to retrieve data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data.




---
url: /api/lynx-api/lynx/lynx-get-text-info.md
---

# getTextInfo()

APISummary
Used to measure the width of text content.

## Syntax

```ts
export interface TextInfo {
  fontSize: string;
  fontFamily?: string;
  maxWidth?: string;
  maxLine?: number;
}

export interface TextMetrics {
  width: number;
  content:  Array<string>;
}

getTextInfo(text: string, info: TextInfo): TextMetrics;
```

### Parameters

#### text

The text string to be measured.

#### info

The attribute information set on the text, supports setting fontSize, fontFamily, maxWidth and maxLine, among which fontSize is mandatory, fontSize and maxWidth only support px unit.

### Return Value

The result of text measurement, including width and the text string of each line, the returned width unit is px.

## Example

```ts
// default font family
const { width } = lynx.getTextInfo('text content', { fontSize: '14px' });

const { width } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
});

const { content } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
  maxWidth: '100px',
  maxLine: 2,
});
```

::: tip

- It is strongly recommended to check the passed parameters, data not expected should be filtered out to reduce unexpected time consumption. For example, fontSize is 0, 1, these data with no actual meaning, maxWidth is 0, 1, 2, these data are too small.

- fontFamily currently only supports built-in fonts, does not support custom fonts set through font-face, use the default font when fontFamily is not set.

- Does not currently support letterSpacing, fontWeight and other properties that are not explicitly declared supported.

- If maxLine is set to 1, the returned TextMetrics will not contain content, at this time the transmission of content is meaningless, avoid one transmission overhead.

- In case of non-compliant input, such as `maxLine > 1 && maxWidth < 1` or `fontSize <= 0` or textContent is empty, it will return `TextMetrics {width: 0}`.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getTextInfo`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to measure the width of text content.




---
url: /api/lynx-api/lynx/lynx-global-props.md
---

# GlobalProps

APISummary
`lynx.__globalProps` is a global object that you can access from anywhere.

- It is read-only in the front-end code, you cannot modify its value.
- The client can set and update its value by calling APIs provided by the Lynx SDK.
- Every time the client performs an update, it will trigger the `onGlobalPropsChanged` event, followed by a re-rendering of the entire page.

## Usage

```tsx
// The properties within the `lynx.__globalProps` object are not managed by Lynx itself.
// Therefore, you must extend its interface yourself.
declare module '@lynx-js/types' {
  interface GlobalProps {
    appTheme: string;
    title: string;
  }
}

function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    <view class={themeClass}>
      <text>{lynx.__globalProps.title}</text>
    </view>
  );
}
```

## Event Listening

You can listen for changes to `__globalProps` in your component.

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

export function App() {
  useLynxGlobalEventListener('onGlobalPropsChanged', () => {
    console.log('onGlobalPropsChanged', lynx.__globalProps);
  });

  return <view />;
}
```

## Client side

`__globalProps` can be updated through APIs provided by `LynxView`.

### Android

```java
void updateGlobalProps(@NonNull Map<String, Object> props)

void updateGlobalProps(@NonNull TemplateData props)

```

### iOS

```objc
- (void)updateGlobalPropsWithDictionary:(NSDictionary<NSString*, id>*)data

- (void)updateGlobalPropsWithTemplateData:(LynxTemplateData*)data
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.globalProps`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** global data set by client.




---
url: /api/lynx-api/lynx/lynx-performance.md
---

# lynx: performance readonly object

APISummary
This object provides access to performance metrics related to the current page.

## Instance Methods

[`createObserver()`](/api/lynx-api/lynx/lynx-performance/create-observer.md) Creates a [`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md) object that will be used to receive performance events generated by Lynx engine.

[`profileStart()`](/api/lynx-api/lynx/lynx-performance/profile-start.md) Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

[`profileEnd()`](/api/lynx-api/lynx/lynx-performance/profile-end.md) Marks the end of the most recent [trace event](https://perfetto.dev/docs/instrumentation/track-events).

[`profileMark()`](/api/lynx-api/lynx/lynx-performance/profile-mark.md) Marks an instant(point-in-time) event.

[`profileFlowId()`](/api/lynx-api/lynx/lynx-performance/profile-flow-id.md) Generates a unique flow id for [flow events](https://perfetto.dev/docs/instrumentation/track-events#flows).

[`isProfileRecording()`](/api/lynx-api/lynx/lynx-performance/is-profile-recording.md) Checks if trace recording is currently active.

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/create-observer.md
---

# createObserver()

APISummary
Creates a
[`PerformanceObserver`](/api/lynx-api/performance-api/performance-observer.md)
object that will be used to receive performance events generated by Lynx engine.

#### Syntax

```ts
createObserver(callback: PerformanceCallback): PerformanceObserver;
```

#### Parameters

##### callback

A callback function that handles performance events, defined as `type PerformanceCallback = (entry: PerformanceEntry) => void`. The entry is a subclass of [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md).

This callback is triggered when the [PerformanceObserver](/api/lynx-api/performance-api/performance-observer.md) receives a performance event.

#### Return Value

A `PerformanceObserver` object.

#### Examples

The following example creates a `PerformanceObserver` watching for [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) entries.

**This is an example below: performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fsp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fsp") {
        entryType = "MetricFspEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fsp" and "pipeline" event.
    observer.observe(["metric.fsp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-start.md
---

# profileStart()

APISummary
Marks the start of a [trace
event](https://perfetto.dev/docs/instrumentation/track-events).

#### Syntax

```typescript
profileStart(name: string, option?: { flowId: number, arg?:  Record<string, string>}): void;
```

#### Parameters

##### name

The name of the trace event.

##### option(optional)

Additional options such as `flowId` and custom arguments.

#### Examples

```typescript
// Start a trace event with only a name
lynx.performance.profileStart('DataFetch');

// Start a trace event with custom arguments
lynx.performance.profileStart('DataFetch', {
  args: { url: 'https://api.example.com/data', method: 'GET' },
});

// Start a trace event with a flow id
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileStart('UserAction', { flowId });

// Start a duration event with both arguments and flow ID
lynx.performance.profileStart('ComplexProcess', {
  args: { step: 'start' },
  flowId,
});
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-end.md
---

# profileEnd()

APISummary
Marks the end of the most recent [trace
event](https://perfetto.dev/docs/instrumentation/track-events).

#### Syntax

```typescript
profileEnd(): void;
```

#### Examples

```typescript
// End the most recent duration event
lynx.performance.profileEnd();
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-mark.md
---

# profileMark()

APISummary
Marks an instant(point-in-time) event.

#### Syntax

```typescript
profileMark(name: string, option?: { flowId: number, arg?:  Record<string, string>}): void;
```

#### Parameters

##### name

The name of the instant event.

##### option(optional)

Additional options such as `flowId` and custom arguments.

#### Examples

```typescript
// Mark an instant event with only a name
lynx.performance.profileMark('FetchStarted');

// Mark an instant event with custom arguments
lynx.performance.profileMark('FetchStarted', {
  args: { status: 'initiated' },
});

// Mark an instant event with a flow id
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileMark('ActionCheckpoint', { flowId });

// Mark an instant event with both arguments and flow id
lynx.performance.profileMark('ProcessMidpoint', {
  args: { step: 'middle' },
  flowId,
});
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/profile-flow-id.md
---

# profileFlowId()

APISummary
Generates a unique flow id for [flow
events](https://perfetto.dev/docs/instrumentation/track-events#flows).

#### Syntax

```typescript
profileFlowId(): number;
```

#### Return Value

A unique flow id number.

### Examples

```typescript
const flowId = lynx.performance.profileFlowId();
lynx.performance.profileStart('UserAction', { flowId });
lynx.performance.profileMark('ActionCheckpoint', { flowId });
lynx.performance.profileEnd();
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-performance/is-profile-recording.md
---

# isProfileRecording()

APISummary
Checks if trace recording is currently active.

#### Syntax

```typescript
isProfileRecording(): boolean
```

#### Return Value

Return `true` if trace recording is currently active;

### Examples

```typescript
if (lynx.performance.isProfileRecording()) {
  lynx.performance.profileMark('RecordingIsActive');
}
```

## Compatibility

**Error:** No compatibility data found for `lynx-api.lynx.performance`


---
url: /api/lynx-api/lynx/lynx-queue-microtask.md
---

# lynx: queueMicrotask() static method

APISummary
Send a task to a microtask queue for execution. For more information about microtask, please refer to [here](https://developer.mozilla.org/en-US/docs/Web/API/Window/queueMicrotask)

## Syntax

```ts
queueMicrotask(callback: () => void): void;
```

### Parameters

#### callback

Function object that needs to be sent to the microtask queue.

### Return Value

None（`undefined`）。

## Examples

```tsx
lynx.queueMicrotask(() => {
  console.log('microtask execute.');
});
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.queueMicrotask`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** insert a task into microtask queue




---
url: /api/lynx-api/lynx/lynx-register-module.md
---

# lynx: registerModule() static method

APISummary
Register a JavaScript value that can be shared within a single LynxView, but not between different LynxViews.

## Syntax

```ts
registerModule: <Module>(name: string, module: Module) => void;
```

### Parameters

#### name

The name of the value.

#### module

The value to be registered, can use any JavaScript types.

### Return Value

None (`undefined`).

## Examples

### Get module from JS

Use the [`lynx.getJSModule`] method to get a registered value:

```js
const fooModule = {};
lynx.registerModule('foo', fooModule);
lynx.getJSModule('foo') === fooModule; // true
```

[`lynx.getJSModule`]: /api/lynx-api/lynx/lynx-get-js-module.md

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.registerModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/lynx/lynx-reload.md
---

# lynx: reload() static method

APISummary
Reloads the current page, like the Refresh button.

## Syntax

```ts
reload(value: object, callback: () => void): void;
```

### Parameters

#### value

The new initial data the page reloading uses.

#### callback

The callback function when page reloading finishes.

### Return Value

None(`undefined`).

## Notices

1. The `lynx.reload()` method will not trigger the frontend `DataProcessor` function;
2. `__globalProps`, `SystemInfo` and JS global variables will remain unchanged;
3. `lynx.reload()` will trigger the `componentWillUnmount`/`onDetach` callbacks of all current frontend components; and recreate new custom components.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.reload`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.7 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| iOS | 2.7 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | ReactLynx 3.0 is not supported.; ⚠️ Partial implementation |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Reloads the current page, like the Refresh button.




---
url: /api/lynx-api/lynx/lynx-report-error.md
---

# lynx: reportError() static method

APISummary
The `lynx.reportError` method is used to manually report an error from JavaScript.

## Syntax

```ts
reportError(error: string | Error, options?: {level: 'warning' | 'error' | 'fatal'}): void;
```

### Parameters

#### error

`lynx.reportError` the first arg can receive a string or a JavaScript Error object. The second arg can receive an object with a `level` property,where `level` indicates the level of the error, with the `fatal` level interrupting the execution environment to prevent further chaining of errors.

If a string is passed, `reportError` will construct an error object with `JSON.stringify(error)` as the message.

Which means

```js
lynx.reportError('foo');
```

is equivalent with

```js
lynx.reportError(new Error('foo'));
```

### Return Value

None (`undefined`).

## Examples

```tsx
try {
  const { data } = JSON.parse(content);
} catch (error) {
  lynx.reportError(error);
}
```

### Async error with original stack

A common use case is when an exception occurs in an asynchronous callback:

```javascript
import fetch from '@fetch';

export function getData(params) {
  return new Promise((resolve, reject) => {
    fetch(
      {
        url: HOST,
        method: 'GET',
        params,
      },
      function cb(res) {
        if (res?.status_code === 0) {
          lynx.reportError('fetch error: ' + res?.status_code);
          reject(res);
        } else {
          resolve(res);
        }
      },
    );
  });
}
```

But this will result in an error stack like this:

```
at Lynx.reportError (file://shared/lynx_core.js:9821:48)
at cb (file://view/app-service.js:284:27)
```

This first frame points to the `lynx.reportError` method and the second frame points to the callback passed to `fetch`. No more information could be found from the error stack. We could never know who calls the `getData` method from the reported error stack.

This is because Lynx uses polyfilled `Promise` and does not track asynchronous call stacks.
To get a readable error stack, we could construct an error object before entering asynchronous process.

```javascript
import fetch from '@fetch';

export function getData(params) {
  const error = new Error(); // construct the error synchronously
  return new Promise((resolve, reject) => {
    fetch(
      {
        url: 'HOST',
        method: 'GET',
        params,
      },
      (res) => {
        if (res?.status_code === 0) {
          error.message = 'fetch error: ' + res?.status_code;
          lynx.reportError(error);
          reject(res);
        } else {
          resolve(res);
        }
      },
    );
  });
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.reportError`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to report a JavaScript Error.




---
url: /api/lynx-api/lynx/lynx-request-animation-frame.md
---

# requestAnimationFrame()

APISummary
Invoke the specified callback function at the next VSYNC.

`requestAnimationFrame` is typically used in scenarios where you want to achieve animation effects by modifying element attributes in each frame.
Note that `requestAnimationFrame` will only take effect in the next frame; if you want it to continue to take effect, you need to nest `requestAnimationFrame`.

## Syntax

```ts
requestAnimationFrame: (callback: (timeStamp: number) => void) => number;
```

### Parameters

#### callback

The callback function that needs to be called at the next VSYNC.
The callback function has one parameter `timeStamp`, which is the moment when the callback function starts to execute.

### Return Value

An integer type id, used to cancel this `requestAnimationFrame` callback.

## Examples

Print the frame rate in the console:

**This is an example below: lynx-api**

**Bundle:** `dist/request-animation-frame.lynx.bundle` | Web: `dist/request-animation-frame.web.bundle`

```tsx
import { root, useEffect, useRef, useState } from "@lynx-js/react";

import "./index.css";

import arrow from "../../resource/arrow.png";
import lynxLogo from "../../resource/lynxlogo.png";

const RequestAnimationFrame = () => {
  const lastUptimeRef = useRef(0);
  const framesRef = useRef(0);
  const [fpsStr, setFpsStr] = useState("0");

  function drawFrame(timestamp: number) {
    requestAnimationFrame(drawFrame);
    framesRef.current++;
    const time = Math.floor(timestamp / 3000) | 0;

    if (time !== lastUptimeRef.current) {
      setFpsStr(String(Math.floor(framesRef.current / 3)));
      console.log("FPS: " + fpsStr);
      lastUptimeRef.current = time;
      framesRef.current = 0;
    }
  }
  useEffect(() => {
    requestAnimationFrame(drawFrame);
  }, []);
  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo">
            <image src={lynxLogo} className="Logo--lynx" />
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">{"FPS: " + fpsStr}</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
};

root.render(<RequestAnimationFrame />);

```



## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requestAnimationFrame`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.6 | - |
| iOS | 1.6 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Invoke the specified callback function at the next VSYNC.




---
url: /api/lynx-api/lynx/lynx-request-resource-prefetch.md
---

# lynx: requestResourcePrefetch() static method

APISummary
- This API is used for proactively initiating the preloading of CDN resources from the frontend, currently supporting **image**, **video**, **audio**, and **font** resource types.
- The preloaded resources will not be returned to the frontend through this API; instead, they are retained in memory or on disk. Therefore, after preloading is complete, a `unique key` is needed to specify the resource to the component:
  - The key for an image resource is consistent with the `uri` parameter during its preloading. When rendering, pass this key to the [src](/api/elements/built-in/image.md#src) attribute of the `<image />` component, allowing the component to locate the resource.

## Syntax

```ts
requestResourcePrefetch(
  data: object,
  callback: (res: object) => void,
  config?: {
    awaitComplete?: boolean;
    awaitTimeout?: number; // ms, default is 60000
  }
) : void;
```

### Parameters

#### `data`

A collection that describes all the details of the resources to be preloaded, its keys are defined as follows:

- `data`: Type `array`, each item inside the array corresponds to a resource. The keys for each item are defined as follows:
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of resource. The defined types of resources are as follows:
    - `image`: Image resource. (api/elements/built-in/image.html#trailnewimage--) switch for the Image component to preload images.)
    - `video`: Video resource.
    - `audio`: Audio resource.
    - `font`: Font resource.
  - `params` (optional): Custom control parameters for resource preloading, the supported parameters are as follows:
    - `priority` (optional): Only for `image` type resources. Indicates network request priority. If the priority is high, other image requests will be blocked while the image library preloads these images, which may slow down the display of other images. Therefore, if these preloaded images are not immediately needed for display, consider setting a lower priority. The options supported are as follows:
      - `high`: High priority.
      - `medium`: Medium priority.
      - `low`: Low priority, this is the default value.
    - `cacheTarget` (optional): Only for `image` type resources. Indicates the form in which resources are saved. The options supported are as follows:
      - `disk`: Resource is saved to disk after preloading is completed, this is the default value.
      - `bitmap`: Resource is decoded into a bitmap and saved in memory after preloading. (**Note: Currently, Android bitmap caching is not yet effective.**)
    - `preloadKey`: Only for `video`, `audio` type resources. Represents a unique key that identifies the resource. When rendering the \<x-video-pro> component, this key must be specified so that the component can find the preloaded cache. This is a required parameter.
    - `size` (optional): Only for `video` type resources. Indicates the size of the preload, with a default value of 500 \* 1024 (bytes).

#### `callback`

The callback function called after the API is executed or fails. The inside definition of its parameters is as follows:

- `code`: Type `number`, status code, which may take the following values:
  - `0`: Success.
  - `32101`: Parameter error.
  - `32102`: Image prefetch helper does not exist.
  - `32103`: Resource service does not exist.
  - `32104`: Timed out while waiting for prefetch completion. This is only possible when `config.awaitComplete = true`.
- `msg`: Type `string`, a global error message.
- `details`: Type `array`, where each detail represents the preload status details of a resource, with the internal definition of detail as follows:
  - `code`: Type `number`, status code, which may take the following values:
    - `0`: Success.
    - `32101`: Parameter error.
    - `32102`: Image prefetch helper does not exist.
    - `32103`: Resource service does not exist.
  - `msg`: Type `string`, error message.
  - `uri`: Type `string`, represents the CDN address of the resource.
  - `type`: Type `string`, represents the type of the resource, with resource types defined as follows:
    - `image`: Image resource.
    - `video`: Video resource.
    - `audio`: Audio resource.
    - `font`: Font resource.

#### `config` (since 3.9)

Controls whether the callback waits for prefetch completion and how long it waits:

- `awaitComplete` (optional): Type `boolean`, default `false`. When set to `true`, the `callback` is invoked only after all resources complete prefetching; if the wait times out, the API returns `32104`.
- `awaitTimeout` (optional): Type `number`, in milliseconds, default `60000`. This only takes effect when `awaitComplete = true`.

### Return Value

None (`undefined`).

## Errors

- When there is a parameter error, the `code` returns `32101`, and the `msg` contains detailed error information.
- When the Image prefetch helper does not exist, the `code` returns `32102`.
- When the Resource service does not exist, the `code` returns `32103`.
- When `awaitComplete` is enabled and waiting times out, the `code` returns `32104`.

## Example

```js
import { useState, useEffect } from '@lynx-js/react';

function Page() {
  const [show, setShow] = useState(false);

  useEffect(() => {
    // We initiate resource preloading ahead of time when the page DidMount
    // We need to preload a batch of resources, including two images and two videos.
    // First, prepare the resource parameters, assign priority and cacheTarget for images, and the required preloadKey for videos.
    let resData = [
      {
        uri: 'https://xxxxx1.jpg',
        type: 'image',
        params: { priority: 'high', cacheTarget: 'disk' },
      },
      {
        uri: 'https://xxxxx2.jpg',
        type: 'image',
        params: { cacheTarget: 'bitmap' },
      },
      {
        uri: 'https://zzzzz1.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz1' },
      },
      {
        uri: 'https://zzzzz2.mp4',
        type: 'video',
        params: { preloadKey: 'zzzzz2' },
      },
      {
        uri: 'https://my-font-src',
        type: 'font',
      },
    ];

    // Call the requestResourcePrefetch to initiate preloading
    lynx.requestResourcePrefetch?.(
      {
        data: resData,
      },
      (res) => {
        if (res.code == 0) {
          console.log('success!');
        } else {
          console.log('fail! ', res.msg);
        }
        console.log(
          'prefetch status of each resource:',
          JSON.stringify(res.details),
        );
      },
      {
        awaitComplete: true,
        awaitTimeout: 3000,
      },
    );
  }, []);

  const handleTap = () => {
    // Change the show state through setState to control the display of images and videos
    setShow(!show);
  };

  return (
    <view onTap={handleTap}>
      {/* According to the show status to determine whether to display the image, note that here src is the unique key mentioned above, this should keep the src consistent with the preload time */}
      {show && <image src="https://xxxxx1.jpg" />}
      {show && <image src="https://xxxxx2.jpg" />}
      {/* According to the show status to determine whether to display the video, note that here preload-key is the unique key mentioned above, this should keep the preload-key consistent with the preload time */}
      {show && <x-video-pro src="https://zzzzz1.mp4" preload-key="zzzzz1" />}
      {show && <x-video-pro src="https://zzzzz2.mp4" preload-key="zzzzz2" />}
    </view>
  );
}

export default Page;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requestResourcePrefetch`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.6 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Used to request the prefetch of resource.




---
url: /api/lynx-api/lynx/lynx-require-module-async.md
---

# lynx: requireModuleAsync() static method

APISummary
Used to import modules. Just like the [`requireModule`](/api/lynx-api/lynx/lynx-require-module.md) method, but loading asynchronously.

During the loading, the other JavaScript code can be executed.

The module loaded by `requireModuleAsync` needs to use a specific format. Use [`@lynx-js/runtime-wrapper-webpack-plugin`](https://www.npmjs.com/package/@lynx-js/runtime-wrapper-webpack-plugin) to generate modules that are `requireModuleAsync`-loadable.

## Syntax

```ts
requireModuleAsync<T>(path: string, callback: (error: Error | null, exports?: T) => void): void;
```

### Parameters

#### path

The path of the module. Can be a remote path, or a path inside the template.

#### callback

The callback to be executed after the require is finished

- If any error occurs, an error will be passed as the first parameter.
- Otherwise, a `null` will be passed as the first parameter, and the exported value of the module will be passed as the second parameter.

### Return Value

None (`undefined`).

## Exception

`requireModuleAsync` will return an error in callback when:

- Network error
- Module execute error

## Examples

### Loading remote resources

```tsx
lynx.requireModuleAsync('https://example.com/path/to/chunk', (err, exports) => {
  if (err) {
    return;
  }
  // use exports
});
```

### Promisify

```js
const requireModulePromise = (path) =>
  new Promise((resolve, reject) => {
    lynx.requireModuleAsync(path, (err, exports) => {
      if (err) {
        return reject(err);
      }
      return resolve(exports);
    });
  });

await requireModulePromise('path/to/chunk');
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requireModuleAsync`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Used to import modules.




---
url: /api/lynx-api/lynx/lynx-require-module.md
---

# lynx: requireModule() static method

APISummary
Used to import modules. Just like NodeJS's [`require`](https://nodejs.org/docs/latest/api/modules.html#requireid).

`requireModule` will load the module **synchronously**. During the loading, the JavaScript thread will be hang. No JavaScript code will be executed.

## Syntax

```ts
requireModule<T>(path: string): T;
```

### Parameters

#### path

The path of the module. Can be a remote path, or a path inside the template.

### Return Value

The exported value of the module.

## Exception

`requireModule` will throw an exception when:

- Network error
- Module execute error
- Timeout

The error can be catch and handled by using `try-catch`.

### Timeout

To avoid JavaScript thread hang forever when loading remote resources, `requireModule` will throw an exception 5 seconds after the request is sent.

## Examples

### Loading remote resources

```tsx
const foo = lynx.requireModule('https://example.com/path/to/chunk');
```

### Re-try on timeout

```js
let result = null;
(function () {
  let retry = 0;
  function requireModule(path) {
    try {
      result = lynx.requireModule(path);
    } catch (error) {
      retry += 1;
      if (retry < 3) {
        requireModule(path);
      } else {
        throw error;
      }
    }
  }
  requireModule('path/to/chunk');
})();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.requireModule`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.4 | - |
| iOS | 1.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Used to import modules and JSON.




---
url: /api/lynx-api/lynx/lynx-resume-exposure.md
---

# lynx: resumeExposure() static method

APISummary
The `lynx.resumeExposure` method can be used to turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.

## Syntax

```ts
resumeExposure(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Precautions

Calling `lynx.resumeExposure` may not trigger an exposure event. Whether or not an exposure event is triggered depends on the difference between the results of this exposure detection and the previous one. For details, please refer to [Exposure Capability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.resumeExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.




---
url: /api/lynx-api/lynx/lynx-set-observer-frame-rate.md
---

# lynx: setObserverFrameRate() static method

APISummary
The `lynx.setObserverFrameRate` method can be used to set the frequency of exposure detection.

## grammar

```ts
setObserverFrameRate(options?: Options): void;
```

### Parameters

#### options

```ts
interface Options {
  forPageRect?: number;
  forExposureCheck?: number;
}
```

Specify exposure detection frequency:

- `forPageRect`: unit `fps`, specifies the minimum time interval for detecting `LynxView` position changes. Defaults to 20.
- `forExposureCheck`: unit `fps`, specifies the minimum time interval for detecting the visibility of the target node. Defaults to 20.

### return value

None (`undefined`).

### Precautions

When `LynxView` will not have position changes, such as full-page scenarios, you can set `forPageRect` to `0` to stop detecting position changes of `LynxView`. However, in the card scene, setting `forPageRect` to `0` will cause the exposure of the `Lynx` card to fail in the sliding scene. For details, please refer to [Exposure Ability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.setObserverFrameRate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.15 | - |
| iOS | 2.15 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |

**Description:** Set the frequency of exposure detection.




---
url: /api/lynx-api/lynx/lynx-set-session-storage.md
---

# lynx: setSessionStorageItem() static method

APISummary
The `lynx.setSessionStorageItem` method is used to set data shared across multiple LynxViews.

## Syntax

```ts
setSessionStorageItem(key: string, value: object): void;
```

### Parameters

#### key

The key for the cached data. It can be used subsequently to retrieve the data or listen for changes.

#### value

The data object to be stored.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.setSessionStorageItem`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.setSessionStorageItem` method is used to set data shared across multiple LynxViews.




---
url: /api/lynx-api/lynx/lynx-stop-exposure.md
---

# lynx: stopExposure() static method

APISummary
The `lynx.stopExposure` method can be used to stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future. You can call \[lynx.resumeExposure]\(./lynx-resume-exposure .mdx) to restart exposure detection.

## Syntax

```ts
stopExposure(options?: StopExposureOptions): void;
```

### Parameters

#### options

```ts
interface StopExposureOptions {
  sendEvent?: boolean;
}
```

Specify the behavior of `lynx.stopExposure`:

- `sendEvent`: Specify whether to send anti-exposure events of all currently visible target nodes. Defaults to `true`.

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.stopExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future.




---
url: /api/lynx-api/lynx/lynx-subscribe-session-storage.md
---

# lynx: subscribeSessionStorage() static method

APISummary
The `lynx.subscribeSessionStorage` method is used to listen for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/lynx/lynx-set-session-storage.md) to set the cached data.

## Syntax

```ts
let id = lynx.subscribeSessionStorage(key, (value) => {});
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### callback

The callback function for listening to cached data. The argument is the cached data object.

### Return Value

`id: number`, the ID for the data change listener, which can be used to cancel the listener.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.subscribeSessionStorage`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.subscribeSessionStorage` method is used to listen for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data.




---
url: /api/lynx-api/lynx/lynx-unsubscribe-session-storage.md
---

# lynx: unsubscribeSessionStorage() static method

APISummary
The `lynx.unsubscribeSessionStorage` method is used to cancel the listener for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/lynx/lynx-set-session-storage.md) to set the cached data. After cancellation, the cached data corresponding to this key will no longer be listened to.

## Syntax

```ts
lynx.unsubscribeSessionStorage(key, id);
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### id

The ID for the data change listener. Use the ID returned by [lynx.subscribeSessionStorage](/api/lynx-api/lynx/lynx-subscribe-session-storage.md) to cancel the listener.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.unsubscribeSessionStorage`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.unsubscribeSessionStorage` method is used to cancel the listener for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data. After cancellation, the cached data corresponding to this key will no longer be listened to.




---
url: /api/lynx-api/nodes-ref.md
---

# NodesRef

APISummary
Represents a reference to one or more UI nodes. It can be used to invoke UI methods, get and set properties on UI nodes.

`NodesRef` only saves the information needed to find nodes (such as CSS selectors), and does not actually reference a specific node.
The actual node search is only carried out when `SelectorQuery.prototype.exec()` is executed.
Therefore, the node that `NodesRef` reference may not actually exist. In this case, an error will be reported when `exec()` is called.

## Instance Method

[`NodesRef.fields()`](/api/lynx-api/nodes-ref/nodes-ref-fields.md)

Query the attributes of the selected node.

[`NodesRef.invoke()`](/api/lynx-api/nodes-ref/nodes-ref-invoke.md)

Execute the UI method of the selected node.

[`NodesRef.path()`](/api/lynx-api/nodes-ref/nodes-ref-path.md)

Query the path information from the node to the root node of the page.

[`NodesRef.setNativeProps()`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md)
.mdx)

Directly set the attributes of the selected node.

## Examples

Obtain the position and size of the specified `text` node:

```tsx
class Page extends Component {
  componentDidMount() {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }

  render() {
    return (
      <view>
        <text id="my-id">...</text>
      </view>
    );
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.NodesRef`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Represents a reference to one or more UI nodes. It can be used to call methods, get and set properties on UI nodes.




---
url: /api/lynx-api/nodes-ref/nodes-ref-fields.md
---

# NodesRef: fields() method

APISummary
Query the attributes of the selected node.

## Syntax

```ts
fields(fields: Record<string, boolean>, callback: (data: object, status: object) => void): SelectorQuery;
```

### Parameters

#### fields

A `Record<string, boolean>`, describing whether it is necessary to query the corresponding type of property.
The range of queryable property types is as follows, and values outside this range will be ignored:

- `attribute` (optional)
  - Only custom attributes will be returned, attributes such as `id`, `class`, `style`, `dataset` will not be returned.
  - Attributes with values `null` / `undefined` / `function` will not be returned.
  - The key of the returned value is in kebab case.

- `class` (optional)

- `dataset` (optional)

- `id` (optional)

- `index` (optional)

- `query` (optional)
  - The `SelectorQuery` object with this node as the root node
    - The query performed on this `SelectorQuery` object is limited to this node and its descendant nodes.
    - Calling `selectRoot()` on this `SelectorQuery` object will return the `NodesRef` object representing this node.

- `tag` (optional)

- `unique_id` (optional)

#### callback

A callback function, the query result will be returned as the parameter of the callback function. The callback function has two parameters:

The first parameter returns the query result.

- If the `NodesRef` represents one single node, it returns a `Record<string, any>` object containing the query result. If the node is not found, it returns `null`.
- If the `NodesRef` represents multiple nodes, it returns an array of `Record<string, any>` objects, each element in the array corresponds to the query result of a node. If no nodes are found, it returns an empty array.

The second parameter returns the status of the query (error message).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
lynx
  .createSelectorQuery()
  .select('#id')
  .fields(
    {
      id: true,
      dataset: true,
      tag: true,
    },
    (data, status) => {
      console.log(data, status);
    },
  )
  .exec();
```

Possible output;

```javascript
// data
{"tag":"text","dataset":{"hello":"world"},"id":"my-id"}

// status
{"data":"success","code":0}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.fields`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Query the attributes of the selected node.




---
url: /api/lynx-api/nodes-ref/nodes-ref-invoke.md
---

# NodesRef: invoke() method

APISummary
Execute the UI method of the selected node.

Please note that the UI function is a function provided by the client, usually directly controlling UI functions, such as the play or stop of the player.
`invoke` cannot be used to call a js function of a custom component.

## Syntax

```ts
invoke(options: Record<string, any>): SelectorQuery;
```

### Parameters

### options

The `options` parameter is a `Record<string, any>`, which contains the information needed for the execution of the UI method. Its key list is as follows:

- `method`

- A `string`, the name of the UI method to be called

- `params` (optional)

- A `Record<string, any>`, the parameters of the UI method to be called

- `success` (optional)

- A callback function that is called when the UI method is successfully executed, with the first parameter being the result returned by the UI method

- `fail` (optional)

- A callback function that is called when the UI method fails to execute, with the first parameter type being `{code: number, data: any}`, which contains the error code and error message returned by the UI method.

- If no fail callback function is provided, a red screen error will be generated when the UI method fails to execute.

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
var params = {
  method: 'seekTo',
  params: {
    duration: 1000,
  },
  success: function (res) {
    console.log(res);
  },
  fail: function (data) {
    console.log(data.code, data.data);
  },
};

lynx.createSelectorQuery().select('#video').invoke(params).exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.invoke`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| iOS | 2.2 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| HarmonyOS | 3.4 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| Clay macOS | 3.7 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| Clay Windows | 3.7 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |
| Web | 1.0 | Does not support usage on `NodesRef` created through `SelectorQuery.proptotype.selectAll()`.; ⚠️ Partial implementation |

**Description:** Execute the UI method of the selected node.




---
url: /api/lynx-api/nodes-ref/nodes-ref-path.md
---

# NodesRef: path() method

APISummary
Query the path information from the node to the root node of the page.

## Syntax

```ts
path(callback: (data: object, status: object) => void): SelectorQuery;
```

### Parameters

#### callback

A callback function, the query result will be returned as the parameter of the callback function. The callback function has two parameters:

The first parameter returns the query result.

- If the `NodesRef` represents one single node, it returns a `Record<string, any>` object containing the query result. If the node is not found, it returns `null`.
- If the `NodesRef` represents multiple nodes, it returns an array of `Record<string, any>` objects, each element in the array corresponds to the query result of a node. If no nodes are found, it returns an empty array.

The second parameter returns the status of the query (error message).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

```javascript
lynx
  .createSelectorQuery()
  .select('#target')
  .path((res, status) => {
    console.log(JSON.stringify(res));
    console.log(JSON.stringify(status));
  })
  .exec();
```

Possible output:

```javascript
// res
{
    // array from target to root
    "path":
    [
        {
            tag:"",
            id:"",
            class:[],
            dataSet:{},
            // index of parent's children
            index:0,
        },
        ...
        {
            tag:"page",
            id:"",
            class:[],
            dataSet:{},
            index:0,
        }
    ]
}

// status
{
  "data": "succeed",
  "code": 0
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.path`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Query the path information from the node to the root node of the page.




---
url: /api/lynx-api/nodes-ref/nodes-ref-set-native-props.md
---

# NodesRef: setNativeProps() method

APISummary
Directly set the attributes of the selected node.

:::warning When should you use setNativeProps?
When you have to refresh frequently and encounter performance bottlenecks.

Directly operating components is not a tool that should be used often.
Generally, it is only used to create continuous animations, while avoiding the large overhead brought about by rendering component structures and synchronizing too many view changes.
`setNativeProps` is a "simple and crude" method, it directly records the state at element instead of in the Lynx component, which makes the code logic difficult to understand.
So before using this method, please try to solve the problem with [`useState`](/api/react/Function.useState.md) method first.
:::

## Syntax

```ts
setNativeProps(nativeProps: Record<string, any>): SelectorQuery;
```

### Parameters

#### nativeProps

A `Record<string, any>`, describes the properties that need to be set. Properties can be any attribute of the UI node, including CSS properties and `attributes`.

Note that `style` cannot be set as a whole (the key of `nativeProps` cannot be `style`).

### Return Value

Contains the `SelectorQuery` object for this task. Call `exec()` to execute the task.

## Examples

1. Set the text content of the text node.

```jsx
function App() {
  return (
    <view
      bindtap={() => {
        lynx
          .createSelectorQuery()
          .select('#intro')
          .setNativeProps({
            text: 'Hello, Lynx!',
          })
          .exec();
      }}
    >
      <text id="intro">Hello, World!</text>
    </view>
  );
}
```

2. Set the `upper-threshold` attribute of `<scroll-view />`.

```jsx
function App() {
  return (
    <scroll-view id="intro">
      <text
        bindtap={() => {
          lynx
            .createSelectorQuery()
            .select('#intro')
            .setNativeProps({
              'upper-threshold': '10px',
            })
            .exec();
        }}
      >
        Hello, World!
      </text>
    </scroll-view>
  );
}
```

3. Set the background color of the `<view />`.

```jsx
function App() {
  return (
    <view id="intro">
      <text
        bindtap={() => {
          lynx
            .createSelectorQuery()
            .select('#intro')
            .setNativeProps({
              'background-color': 'red',
            })
            .exec();
        }}
      >
        Hello, World!
      </text>
    </view>
  );
}
```

4. Modify the transform properties

```jsx
function App() {
  return (
    <view
      bindtap={() => {
        lynx
          .createSelectorQuery()
          .select('#intro')
          .setNativeProps({
            transform: 'translateY(3px)',
          })
          .exec();
      }}
    >
      <text id="intro">Hello, World!</text>
    </view>
  );
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.nodes-ref.setNativeProps`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Directly set the attributes of the selected node.




---
url: /api/lynx-api/main-thread.md
---

# Main Thread APIs

APISummary
Main Thread Script allows JavaScript scripts to be executed on the main thread.

Main Thread Scripts are commonly used for smooth animations and gesture handling. They address the response delay issue caused by events being triggered and handled on different threads in the Lynx multi-threaded architecture, thereby achieving a near-native interactive experience.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.MainThread-APIs`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | ⚠️ Partial implementation |

**Description:** APIs available on the main thread.




---
url: /api/lynx-api/main-thread/main-thread-element.md
---

# Element

APISummary
`MainThread.Element` represents an element. You can access or modify the element's properties in main thread scripts.

## Instance Methods

### `Element.getAttribute()`

Get the specified attribute value of the element. If the element does not have the specified attribute, returns `undefined`.

```ts
const value = element.getAttribute(attrName);
```

### `Element.getAttributeNames()`

Get an array of the element's attribute names.

```ts
const nameArray = element.getAttributeNames();
```

### `Element.invoke()`

Asynchronously invoke the element's UI method. Returns a `Promise`. When the UI method completes successfully, the `Promise` is resolved and returns the UI method's return value. If an exception occurs during the UI method call, the `Promise` is rejected and returns an `Error` object, with its `message` describing the error in detail.

```ts
const result = await element.invoke(methodName, params?);
```

### `Element.setAttribute()`

Set the specified attribute of the element.

```ts
element.setAttribute(attrName, value);
```

### `Element.setStyleProperty()`

Set the specified style of the element. The style name must be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case).

```ts
element.setStyleProperty(styleName, value);
```

### `Element.setStyleProperties()`

Set the specified styles of the element using an object that can contain multiple "styleName: styleValue" records. The style names must be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case).

```ts
element.setStyleProperties(styleProperties);
```

### `Element.getComputedStyleProperty()`

Get the ComputedStyle for the element by key. The style name must be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case).

Refer to [Element.getComputedStyleProperty](/api/lynx-api/main-thread/element-get-computed-style.md).

```ts
const width = element.getComputedStyleProperty(styleName);
```

### `Element.querySelector()`

Find the first element within the element's child elements that matches the specified selector. Returns a `MainThread.Element`. If no matching element is found, returns `null`. For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

```ts
const element = element.querySelector(selector);
```

### `Element.querySelectorAll()`

Find all elements within the element's child elements that match the specified selector. Returns an array of `MainThread.Element`. If no matching elements are found, returns an empty array. For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

```ts
const elementArray = element.querySelectorAll(selector);
```

### `Element.animate()`

Start an animation on the element. Returns an `Animation` object. For more details, see [Element.animate()](/api/lynx-api/main-thread/lynx-animate-api.md).

```ts
const animation = element.animate(keyframes, options);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.Element`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | ⚠️ Partial implementation |

**Description:** Represents an element in the main thread.




---
url: /api/lynx-api/main-thread/lynx-animate-api.md
---

# animate()

APISummary
## Introduction

Use `animate()` to set a [CSS Animation](/api/css/properties/animation.md) on UI elements.

## Syntax

```js
animate(keyframes, options);
```

### Parameter

#### keyframes

1. An **array** consisting of objects that contain properties and values of multiple keyframes.

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  ele.animate(
    [
      {
        // from
        opacity: 0,
        color: '#fff',
      },
      {
        // to
        opacity: 1,
        color: '#000',
      },
    ],
    2000,
  );
}
```

2. Assign a [timing-function](/api/css/properties/animation-timing-function.md) for each keyframe to control the animation's speed.

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  ele.animate(
    [
      {
        // from
        opacity: 0,
        color: '#fff',
        'animation-timing-function': 'linear',
      },
      {
        // to
        opacity: 1,
        color: '#000',
        'animation-timing-function': 'ease-in',
      },
    ],
    2000,
  );
}
```

#### options

An **object** that contains one or more properties:

| Key        | Value Type | Optional | Description                                                                                                                                                                                                                                                                        | Default Value          |
| ---------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| duration   | Number     | optional | The length of time for the animation to run.                                                                                                                                                                                                                                       | 0                      |
| delay      | Number     | optional | The length of time to wait before starting the animation.                                                                                                                                                                                                                          | 0                      |
| iterations | Number     | optional | The number of times the animation should repeat. You can set this to `Infinity` to make the animation loop indefinitely.                                                                                                                                                           | 1                      |
| direction  | String     | optional | Whether the animation runs forwards (`normal`), backwards (`reverse`), switches direction after each iteration (`alternate`), or runs backwards and switches direction after each iteration (`alternate-reverse`). Defaults to `"normal"`.                                         | `"normal"`             |
| easing     | String     | optional | The rate of the animation's change over time. Accepts an [timing-function](/api/css/properties/animation-timing-function.md), such as `"linear"`, `"ease-in"`, or `"cubic-bezier(0.42, 0, 0.58, 1)"`. Defaults to "linear".                                                        | `"linear"`             |
| fill       | String     | optional | Dictates whether the animation's effects should be reflected by the element(s) prior to playing ("backwards"), retained after the animation has completed playing ("forwards"), or both. Defaults to "none".                                                                       | `"none"`               |
| name       | String     | optional | The name of the animation, which can be used to uniquely identify it. This name appears in the [animation events](/api/lynx-api/event/animation-event.md#animation) parameters and is typically used to determine if a particular animation event is the one you're interested in. | An internal unique ID. |
| play-state | String     | optional | Animation motion state, which defines whether an animation is running or paused, accepts an [animation-play-state](/api/css/properties/animation-play-state.md)                                                                                                                    | running                |

:::info Note:

If no `name` is specified, a unique id is generated incrementally.

:::

### Return Value

Returns an `Animation` object.
The `Animation` object has the following methods:

| Method Name          | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `Animation.cancel()` | Cancels the animation and triggers the `animation cancel` event. |
| `Animation.pause()`  | Pauses the animation.                                            |
| `Animation.play()`   | Resumes the animation.                                           |

## Example

```js
function controlAnimation(ele: MainThread.Element) {
  'main thread'
  let ani = ele.animate(
    [
      {
        'background-color': 'blue',
        transform: 'translateX(100px) translateY(300px) rotate(360deg)',
      },
      {
        'background-color': 'red',
        transform: 'translateX(0px) translateY(600px) rotate(0deg)',
      },
    ],
    {
      duration: 3000,
      delay: 1000,
      iterations: Infinity,
      direction: 'alternate',
      easing: 'ease-in-out',
      fill: 'both',
    },
  );

  ani.pause();
  ani.play();
  ani.cancel();
}

```

## Animation Event

The events for the `animate()` API are the same as the [animation events](/api/lynx-api/event/animation-event.md#animation) for CSS animations.

## See also

- [Introduction to CSS Animations](/guide/styling/animation.md)
- [Animate API in BTS](/api/lynx-api/lynx/lynx-animate-api.md)

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.ElementAnimate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Create An Animation in MTS




---
url: /api/lynx-api/main-thread/element-get-computed-style.md
---

# getComputedStyleProperty()

APISummary
## Introduction

The **`getComputedStyleProperty()`** method of the [`Element`](/api/lynx-api/main-thread/main-thread-element.md) returns the [computed style](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#resolved_value) for the element.

## Syntax

```ts
const value = element.getComputedStyleProperty(styleName);
```

### Parameters

#### styleName

A string specifying the property name to be retrieved. The style name must be in [kebab-case](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case).

### Return Value

A string containing the value of the [computed style](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/Property_value_processing#resolved_value).

## Example

```ts
const width = element.getComputedStyleProperty('width');
const backgroundColor = element.getComputedStyleProperty('background-color');
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.main-thread.ElementGetComputedStyle`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |

**Description:** Create An Animation in MTS




---
url: /api/lynx-api/main-thread/lynx-get-text-info.md
---

# 

# getTextInfo()

APISummary
Used to measure the width of text content.

## Syntax

```ts
export interface TextInfo {
  fontSize: string;
  fontFamily?: string;
  maxWidth?: string;
  maxLine?: number;
}

export interface TextMetrics {
  width: number;
  content:  Array<string>;
}

getTextInfo(text: string, info: TextInfo): TextMetrics;
```

### Parameters

#### text

The text string to be measured.

#### info

The attribute information set on the text, supports setting fontSize, fontFamily, maxWidth and maxLine, among which fontSize is mandatory, fontSize and maxWidth only support px unit.

### Return Value

The result of text measurement, including width and the text string of each line, the returned width unit is px.

## Example

```ts
// default font family
const { width } = lynx.getTextInfo('text content', { fontSize: '14px' });

const { width } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
});

const { content } = lynx.getTextInfo('text content', {
  fontSize: '14px',
  fontFamily: 'PingFang SC',
  maxWidth: '100px',
  maxLine: 2,
});
```

::: tip

- It is strongly recommended to check the passed parameters, data not expected should be filtered out to reduce unexpected time consumption. For example, fontSize is 0, 1, these data with no actual meaning, maxWidth is 0, 1, 2, these data are too small.

- fontFamily currently only supports built-in fonts, does not support custom fonts set through font-face, use the default font when fontFamily is not set.

- Does not currently support letterSpacing, fontWeight and other properties that are not explicitly declared supported.

- If maxLine is set to 1, the returned TextMetrics will not contain content, at this time the transmission of content is meaningless, avoid one transmission overhead.

- In case of non-compliant input, such as `maxLine > 1 && maxWidth < 1` or `fontSize <= 0` or textContent is empty, it will return `TextMetrics {width: 0}`.

:::

## Compatibility

Missing API QueryEither a query must be provided as the `query` prop to the `<APITable />`, or it will be retrieved from the `api` field in the frontmatter of the current page.




---
url: /api/lynx-api/main-thread/lynx-query-selector.md
---

# lynx: querySelector(selector: string)

APISummary
Find the first element within the page's child elements that matches the specified selector.

## Syntax

```ts
const element = lynx.querySelector(selector);
```

### Parameters

#### selector

For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md) or `null`。

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.querySelector`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/main-thread/lynx-query-select-all.md
---

# lynx: querySelectorAll(selector: string)

APISummary
Find all elements within the page's child elements that match the specified selector.

## Syntax

```ts
const elementArray = lynx.querySelectorAll(selector);
```

### Parameters

#### selector

For a list of supported selectors, see [selector](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

[`MainThread.Element[]`](/api/lynx-api/main-thread/main-thread-element.md) or `[]`。

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.querySelectorAll`

**Status:** 🧪 Experimental

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/main-thread/lynx-request-animation-frame.md
---

# 

# requestAnimationFrame()

APISummary
Invoke the specified callback function at the next VSYNC.

`requestAnimationFrame` is typically used in scenarios where you want to achieve animation effects by modifying element attributes in each frame.
Note that `requestAnimationFrame` will only take effect in the next frame; if you want it to continue to take effect, you need to nest `requestAnimationFrame`.

## Syntax

```ts
requestAnimationFrame: (callback: (timeStamp: number) => void) => number;
```

### Parameters

#### callback

The callback function that needs to be called at the next VSYNC.
The callback function has one parameter `timeStamp`, which is the moment when the callback function starts to execute.

### Return Value

An integer type id, used to cancel this `requestAnimationFrame` callback.

## Examples

Print the frame rate in the console:

**This is an example below: lynx-api**

**Bundle:** `dist/request-animation-frame.lynx.bundle` | Web: `dist/request-animation-frame.web.bundle`

```tsx
import { root, useEffect, useRef, useState } from "@lynx-js/react";

import "./index.css";

import arrow from "../../resource/arrow.png";
import lynxLogo from "../../resource/lynxlogo.png";

const RequestAnimationFrame = () => {
  const lastUptimeRef = useRef(0);
  const framesRef = useRef(0);
  const [fpsStr, setFpsStr] = useState("0");

  function drawFrame(timestamp: number) {
    requestAnimationFrame(drawFrame);
    framesRef.current++;
    const time = Math.floor(timestamp / 3000) | 0;

    if (time !== lastUptimeRef.current) {
      setFpsStr(String(Math.floor(framesRef.current / 3)));
      console.log("FPS: " + fpsStr);
      lastUptimeRef.current = time;
      framesRef.current = 0;
    }
  }
  useEffect(() => {
    requestAnimationFrame(drawFrame);
  }, []);
  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo">
            <image src={lynxLogo} className="Logo--lynx" />
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">{"FPS: " + fpsStr}</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
};

root.render(<RequestAnimationFrame />);

```



## Compatibility

Missing API QueryEither a query must be provided as the `query` prop to the `<APITable />`, or it will be retrieved from the `api` field in the frontmatter of the current page.




---
url: /api/lynx-api/main-thread/lynx-global-props.md
---

# 

# GlobalProps

APISummary
`lynx.__globalProps` is a global object that you can access from anywhere.

- It is read-only in the front-end code, you cannot modify its value.
- The client can set and update its value by calling APIs provided by the Lynx SDK.
- Every time the client performs an update, it will trigger the `onGlobalPropsChanged` event, followed by a re-rendering of the entire page.

## Usage

```tsx
// The properties within the `lynx.__globalProps` object are not managed by Lynx itself.
// Therefore, you must extend its interface yourself.
declare module '@lynx-js/types' {
  interface GlobalProps {
    appTheme: string;
    title: string;
  }
}

function App() {
  const themeClass = useMemo(
    () => `theme-${lynx.__globalProps.appTheme}`,
    [lynx.__globalProps.appTheme],
  );

  return (
    <view class={themeClass}>
      <text>{lynx.__globalProps.title}</text>
    </view>
  );
}
```

## Event Listening

You can listen for changes to `__globalProps` in your component.

```tsx
import { useLynxGlobalEventListener } from '@lynx-js/react';

export function App() {
  useLynxGlobalEventListener('onGlobalPropsChanged', () => {
    console.log('onGlobalPropsChanged', lynx.__globalProps);
  });

  return <view />;
}
```

## Client side

`__globalProps` can be updated through APIs provided by `LynxView`.

### Android

```java
void updateGlobalProps(@NonNull Map<String, Object> props)

void updateGlobalProps(@NonNull TemplateData props)

```

### iOS

```objc
- (void)updateGlobalPropsWithDictionary:(NSDictionary<NSString*, id>*)data

- (void)updateGlobalPropsWithTemplateData:(LynxTemplateData*)data
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.globalProps`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.3 | - |
| iOS | 1.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** global data set by client.




---
url: /api/lynx-api/main-thread/lynx-stop-exposure.md
---

# lynx: stopExposure() static method

APISummary
The `lynx.stopExposure` method can be used to stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future. You can call \[lynx.resumeExposure]\(./lynx-resume-exposure .mdx) to restart exposure detection.

## Syntax

```ts
stopExposure(options?: StopExposureOptions): void;
```

### Parameters

#### options

```ts
interface StopExposureOptions {
  sendEvent?: boolean;
}
```

Specify the behavior of `lynx.stopExposure`:

- `sendEvent`: Specify whether to send anti-exposure events of all currently visible target nodes. Defaults to `true`.

### return value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.stopExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Stop exposure detection, that is, the visibility of the target node will no longer be detected, and exposure/anti-exposure events will no longer be triggered in the future.




---
url: /api/lynx-api/main-thread/lynx-resume-exposure.md
---

# lynx: resumeExposure() static method

APISummary
The `lynx.resumeExposure` method can be used to turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.

## Syntax

```ts
resumeExposure(): void;
```

### Parameters

None (`undefined`).

### return value

None (`undefined`).

## Precautions

Calling `lynx.resumeExposure` may not trigger an exposure event. Whether or not an exposure event is triggered depends on the difference between the results of this exposure detection and the previous one. For details, please refer to [Exposure Capability](/guide/interaction/visibility-detection/exposure-ability.md).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.resumeExposure`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |
| Web | ✅ Yes | - |

**Description:** Turn on exposure detection, that is, to restart the detection of the visibility of the target node, and subsequently trigger the exposure/anti-exposure event normally.




---
url: /api/lynx-api/main-thread/lynx-get-session-storage.md
---

# lynx: getSessionStorageItem() static method

APISummary
The `lynx.getSessionStorageItem` method is used to retrieve data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/main-thread/lynx-set-session-storage.md) to set the cached data.

## Syntax

```ts
lynx.getSessionStorageItem(key, (value) => {});
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### callback

The callback function for retrieving cached data. The argument is the cached data object.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.getSessionStorageItem`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.getSessionStorageItem` method is used to retrieve data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data.




---
url: /api/lynx-api/main-thread/lynx-set-session-storage.md
---

# lynx: setSessionStorageItem() static method

APISummary
The `lynx.setSessionStorageItem` method is used to set data shared across multiple LynxViews.

## Syntax

```ts
setSessionStorageItem(key: string, value: object): void;
```

### Parameters

#### key

The key for the cached data. It can be used subsequently to retrieve the data or listen for changes.

#### value

The data object to be stored.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.setSessionStorageItem`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.setSessionStorageItem` method is used to set data shared across multiple LynxViews.




---
url: /api/lynx-api/main-thread/lynx-subscribe-session-storage.md
---

# lynx: subscribeSessionStorage() static method

APISummary
The `lynx.subscribeSessionStorage` method is used to listen for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/main-thread/lynx-set-session-storage.md) to set the cached data.

## Syntax

```ts
let id = lynx.subscribeSessionStorage(key, (value) => {});
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### callback

The callback function for listening to cached data. The argument is the cached data object.

### Return Value

`id: number`, the ID for the data change listener, which can be used to cancel the listener.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.subscribeSessionStorage`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.subscribeSessionStorage` method is used to listen for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data.




---
url: /api/lynx-api/main-thread/lynx-unsubscribe-session-storage.md
---

# lynx: unsubscribeSessionStorage() static method

APISummary
The `lynx.unsubscribeSessionStorage` method is used to cancel the listener for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](/api/lynx-api/main-thread/lynx-set-session-storage.md) to set the cached data. After cancellation, the cached data corresponding to this key will no longer be listened to.

## Syntax

```ts
lynx.unsubscribeSessionStorage(key, id);
```

### Parameters

#### key

The key for the cached data, used to retrieve data and listen for changes.

#### id

The ID for the data change listener. Use the ID returned by [lynx.subscribeSessionStorage](/api/lynx-api/main-thread/lynx-subscribe-session-storage.md) to cancel the listener.

### Return Value

None (`undefined`).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.lynx.unsubscribeSessionStorage`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.9 | - |
| iOS | 2.9 | - |
| HarmonyOS | 3.8 | - |
| Clay macOS | 3.5 | - |
| Clay Windows | 3.5 | - |

**Description:** The `lynx.unsubscribeSessionStorage` method is used to cancel the listener for changes in data shared across multiple LynxViews. This enables data sharing between multiple pages via `SessionStorage`. You can call [lynx.setSessionStorageItem](./lynx-set-session-storage.mdx) to set the cached data. After cancellation, the cached data corresponding to this key will no longer be listened to.




---
url: /api/lynx-api/selector-query.md
---

# SelectorQuery

APISummary
Gets a reference to the specified node in order to call its methods or get its properties.

Depending on the method of creation, each `SelectorQuery` object will be assigned a root node. The scope of any node search will be limited to the leaf nodes of that node.

## Instance Methods

[`SelectorQuery.exec()`](/api/lynx-api/selector-query/selector-query-exec.md)

Execute all submitted UI node operation tasks.

[`SelectorQuery.select()`](/api/lynx-api/selector-query/selector-query-select.md)

Select the first node that matches the specified CSS selector under the root node specified by `SelectorQuery`.

[`SelectorQuery.selectAll()`](/api/lynx-api/selector-query/selector-query-select-all.md)

Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.

[`SelectorQuery.selectRoot()`](/api/lynx-api/selector-query/selector-query-select-root.md)

Select the root node specified by `SelectorQuery`.

[`SelectorQuery.selectUniqueID()`](/api/lynx-api/selector-query/selector-query-select-unique-id.md)

Select nodes by specifying `uid`.

## Example

Get the position and size of the specified `text` node:

```tsx
class Page extends Component {
  componentDidMount() {
    lynx
      .createSelectorQuery() // create SelectorQuery
      .select('#my-id') // Specify the selector of the target node
      .invoke({
        // Specify the operation for the target node
        method: 'boundingClientRect',
        success: function (res) {
          console.log(res);
        },
        fail: function (res) {
          console.log(res.code, res.data);
        },
      })
      .exec(); // Execute the query
  }

  render() {
    return (
      <view>
        <text id="my-id">...</text>
      </view>
    );
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.SelectorQuery`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Gets a reference to the specified node in order to call its methods or get its properties.




---
url: /api/lynx-api/selector-query/selector-query-exec.md
---

# SelectorQuery: exec() method

APISummary
Execute all submitted operations. Note that no node search and UI operations will actually be executed until `exec()` is called.

## Syntax

```ts
exec(): void;
```

### Parameters

None.

### Return Value

None (`undefined`).

## Example

Get the position and size of the specified `text` node:

```tsx
lynx
  .createSelectorQuery()
  .select('#my-id')
  .invoke({
    method: 'boundingClientRect',
    success: function (res) {
      console.log(res);
    },
    fail: function (res) {
      console.log(res.code, res.data);
    },
  })
  .exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.exec`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Execute all submitted operations.




---
url: /api/lynx-api/selector-query/selector-query-select-all.md
---

# SelectorQuery: selectAll() method

APISummary
Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.

## Syntax

```ts
selectAll(selector: string): NodesRef;
```

### Parameters

#### selector

CSS selector combination used for matching nodes. All nodes that match the specified selector combination will be returned.

The CSS selector used for matching nodes must be [CSS selectors supported by `select()`](/api/lynx-api/selector-query/selector-query-select.md#selector).

### Return Value

A `NodesRef` object instance representing this query result.

Please note that at this time, `SelectorQuery` will only save the query parameters provided by the user in the `NodesRef` object and will not execute the query immediately. Therefore, it is **NOT feasible** to view node information or determine whether the node can be found in the following way:

```js
let nodesRef = lynx.createSelectorQuery().selectAll('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

## Notices

### Do not use special characters other than numbers, letters, hyphens, and underscores in the id

Special characters may be parsed as part of a CSS selector or combinator.

For example, `selectAll('#m.x')` will be parsed as looking for elements with both `id=m` and `class=x` attributes, rather than looking for an element with `id` as `m.x`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectAll`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Select all nodes that match the specified CSS selector under the root node specified by `SelectorQuery`.




---
url: /api/lynx-api/selector-query/selector-query-select-root.md
---

# SelectorQuery: selectRoot() method

APISummary
Select the root node specified by `SelectorQuery`.

When using `lynx.createSelectorQuery()`, the selected element is the root element `<page>` of the entire page.

## Syntax

```ts
selectRoot(): NodesRef;
```

### Parameters

None.

### Return Value

A `NodesRef` object instance representing this query result.

## Examples

Set grayscale to the entire page:

```tsx
lynx
  .createSelectorQuery()
  .selectRoot()
  .setNativeProps({
    filter: 'grayscale(100%)',
  })
  .exec();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectRoot`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.4 | - |
| iOS | 2.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Select the root node specified by `SelectorQuery`.




---
url: /api/lynx-api/selector-query/selector-query-select-unique-id.md
---

# SelectorQuery: selectUniqueID() method

APISummary
Select nodes by specifying `uid`. It is usually used to select the corresponding node of the event target.

`uid` is a node's unique id. Each node has a dynamically assigned unique `uid`. `uid` can be obtained through the triggered event.

## Syntax

```ts
selectUniqueID(uniqueId: string | number): NodesRef;
```

### Parameters

#### uniqueId

The `uid` of the node to be selected.

### Return Value

A `NodesRef` object instance representing this query result.

## Examples

Add a background color to the target node of the tap event:

```tsx
const onTap = useCallback((event: ReactLynx.ITouchEvent) => {
  lynx
    .createSelectorQuery()
    .selectUniqueID(event.target.uid)
    .setNativeProps({
      'background-color': 'red',
    })
    .exec();
}, []);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.selectUniqueID`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Select nodes by specifying `uid`.




---
url: /api/lynx-api/selector-query/selector-query-select.md
---

# SelectorQuery: select() method

APISummary
Select the first node that matches the specified selector in the descendants of the root node specified in `SelectorQuery`.

## Syntax

```ts
select(selector: string): NodesRef;
```

### Parameters

#### selector

CSS selector combination used for matching nodes. The first node that matches the specified selector combination will be returned.

The CSS selector used for matching nodes must satisfy the following syntax:

##### Selectors

- Id selector `#`

```tsx
// '#my-id'
<view id="my-id" />
```

- Class selector `.`

```tsx
// '.class1'
<view className="class1" />
```

- Tag selector `tag`

```tsx
// 'view'
<view />
```

- Attribute selector (The `props` of a custom component do not belong to `attribute`, therefore the `attribute` selector cannot be used to match the `props` of a custom component.)
- `[attribute]`: Represents elements with an attribute name of attr.
- `[attribute=value]`: Represents elements with an attribute name of attr whose value is exactly value.
- `[attribute*=value]`: Represents elements with an attribute name of attr whose value contains at least one occurrence of value within the string.
- `[attribute^=value]`: Represents elements with an attribute name of attr whose value is prefixed (preceded) by value.
- `[attribute$=value]`: Represents elements with an attribute name of attr whose value is suffixed (followed) by value.

```tsx
// '[src]'
// '[src=xxx]'
// '[data-x]'
// '[data-x=xxx]'
<image src="xxx" data-x="xxx" />
```

- The free combination of the above selectors

```tsx
// 'image#my-id[src=xxx].class1.class2'
<image id="my-id" className="class1 class2" src="xxx" data-x="xxx" />
```

##### Combinators

- Child Element Combinator `>`
  - Search for the direct child nodes of the parent node.

```tsx
// '.the-parent > .the-child'
<view className="the-parent">
  <view className="the-child" />
</view>
```

- Descendant combinator ` ` (space)
  - Search for the descendant nodes of the parent node.

```tsx
// GOOD: '.the-ancestor   .the-descendant'
// BAD:  '.the-ancestor > .the-descendant'
<view className="the-ancestor">
  <view>
    <view className="the-descendant" />
  </view>
</view>
```

- The union of multiple selectors `,`

```tsx
#id1, #id2;
```

### Return Value

A `NodesRef` object instance representing this query result.

Please note that at this time, `SelectorQuery` will only save the query parameters provided by the user in the `NodesRef` object and will not execute the query immediately. Therefore, it is **NOT feasible** to view node information or determine whether the node can be found in the following way:

```js
let nodesRef = lynx.createSelectorQuery().select('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

## Notices

### Do not use special characters other than numbers, letters, hyphens, and underscores in the id

Special characters may be parsed as part of a CSS selector or combinator.

For example, `select('#m.x')` will be parsed as looking for elements with both `id=m` and `class=x` attributes, rather than looking for an element with `id` as `m.x`.

## Troubleshooting

Element manipulations are performed **asynchronously** after [`exec()`](/api/lynx-api/selector-query/selector-query-exec.md) is executed.
Therefore, it is not feasible to view element information or determine if an element can be found using the following methods:

```js
let nodesRef = lynx.createSelectorQuery().select('#the-id');
console.log(nodesRef); // always returning a valid NodesRef object
```

The correct approach is to examine the error information returned by the node operation functions invoked by the user.

### Common Error Code Definitions

```jsx
enum ErrorCode {
  SUCCESS = 0,
  UNKNOWN = 1,
  NODE_NOT_FOUND = 2,          // Node not found in the element tree
  METHOD_NOT_FOUND = 3,        // The specified method is not present on the found UI node
  PARAM_INVALID = 4,           // Invalid arguments as determined by the component implementer
  SELECTOR_NOT_SUPPORTED = 5,  // Usage of unsupported selectors
  NO_UI_FOR_NODE = 6,          // Node found in the element tree, but there is no corresponding UI
}
```

### Error Code 2 with the message "no node found for selector"

Common reasons include:

- An incorrect CSS selector was used;
- The node has not been rendered at the time of the node search.

#### Node Has Not Been Rendered at the Time of the Node Search

A common situation where a node cannot be found is when the node has not been rendered at the time the [`exec()`](/api/lynx-api/selector-query/selector-query-exec.md) function is called, such as when the node is within a conditional statement that is not satisfied.

For example, in the pseudocode below, during the initial render, since `show` is `false`, the `<view id="xxx" />` node will not be rendered. Therefore, attempting to obtain the node in `useEffect()` will fail.

```jsx
import { useEffect, useState } from '@lynx-js/react';

function App() {
  const [show, setShow] = useState(false);

  useEffect(() => {
    lynx
      .createSelectorQuery()
      .select('#xxx')
      .invoke({
        /** Args */
      })
      .exec();
  }, []);

  return show ? <view id="xxx" /> : null;
}
```

### Error Code 3

The specified node was found, but it does not have the corresponding UI method. Check:

- Whether the node indeed has the corresponding UI method.
- If the method name is spelled correctly.
- Whether there is another node with the same name, leading to the actual search finding a different node.

### Error Code 6

The target node exists in the element tree but lacks an actual UI node.
This issue usually occurs with `view` nodes because, for performance reasons, lynx may have optimized the node internally and not actually created it at the UI layer.
If you want to prevent this optimization, try adding an `id` to the target node.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.selector-query.select`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.2 | - |
| iOS | 2.2 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |

**Description:** Select the first node that matches the specified selector in the descendants of the root node specified in `SelectorQuery`.




---
url: /api/lynx-api/performance-api/performance-entry.md
---

# PerformanceEntry

APISummary
`PerformanceEntry` is a base interface used to describe the complete data of performance events. All performance events inherit from and extend it, commonly including [container](/guide/spec.md#container) initialization, page loading, and rendering times.

All performance events are summarized in the figure below:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/performance-entry-3-7-compressed.png)
## Instance Properties

### entryType

```tsx
entryType: string;
```

Represents a string indicating the type of `PerformanceEntry`. The currently supported types are: `init`, `metric`, and `pipeline`, with the following meanings:

- **`init`**: Records performance events for the initialization process before the Lynx page is displayed.
- **`metric`**: Records performance metric events, such as FCP (First Contentful Paint), TTI (Time to Interactive), and ActualFMP (Actual First Meaningful Paint).
- **`pipeline`**: Records performance events during the rendering process.
- **`resource`**: Records performance events for resource loading.

The corresponding subclasses for each entryType value are shown in the table below.

|  entryType |                                                                                                                                                    subclasses                                                                                                                                                    |
| :--------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|   `init`   | [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md), [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md), [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |
|  `metric`  |                                                           [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md), [`MetricActualfmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)                                                          |
| `pipeline` |                  [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md), [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md), [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md)                  |
| `resource` |                                                                                                             [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md)                                                                                                            |

### name

```tsx
name: string;
```

A string representing the name of the `PerformanceEntry`. The value depends on the specific type of the `PerformanceEntry` object. The corresponding names for all subtypes are shown in the table below:

|                                                    subclasses                                                    |                                           name                                           |
| :--------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: |
|          [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md)         |                                        `container`                                       |
|           [`InitLynxviewEntry`](/api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md)          |                                        `lynxview`                                        |
| [`InitBackgroundRuntimeEntry`](/api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md) |                                    `backgroundRuntime`                                   |
|              [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md)             |                                           `fcp`                                          |
|       [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md)       |                                        `actualFmp`                                       |
|               [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md)               | `updateTriggeredByBts`, `updateTriggeredByNative`, `updateGlobalProps`, `setNativeProps` |
|             [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md)            |                  `loadBundle`, `reloadBundleFromNative`, `reloadFromBts`                 |
|             [`LazyBundleEntry`](/api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md)            |                                       `lazyBundle`                                       |

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/init-container-entry.md
---

#Deprecated InitContainerEntry
:::warning
This event has been deprecated since Lynx SDK 3.7. Related data can be obtained from [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) / [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md).
:::

APISummary
The `InitContainerEntry` interface documents key moments related for the [container](/guide/spec.md#container) preparation work before the Lynx page is displayed. It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of container initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-container-entry.png)

:::info
The key moments provided by this entry rely on the container through [`LynxView.setExtraTiming`](/api/lynx-native-api/lynx-view/set-extra-timing.md) provision.
:::

## Examples

This example demonstrates how to retrieve `InitContainerEntry`。

**This is an example below: performance-api**

**Entry:** `src/init-container-entry`
**Bundle:** `dist/init-container-entry.lynx.bundle`

```tsx {10-22}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitContainerEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.css";

export default function InitContainerEntryExample(this: any) {
  const [initContainerEntry, setInitContainerEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "init" && entry.name == "container") {
        // 3. Received "init.container" event.
        const initContainerEntry = entry as InitContainerEntry;
        setInitContainerEntry(JSON.stringify(initContainerEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.container" event.
    observer.observe(["init.container"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitContainerEntry~</text>
      <text className="entry">{initContainerEntry}</text>
    </view>
  );
}

root.render(<InitContainerEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `container`.

### openTime

```tsx
openTime: number;
```

The time when the container starts loading a Lynx page。This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### containerInitStart

```tsx
containerInitStart: number;
```

The time when the container initialization starts. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### containerInitEnd

```tsx
containerInitEnd: number;
```

The time when the container initialization completes. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### prepareTemplateStart

```tsx
prepareTemplateStart: number;
```

The time when the container starts preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparing" means obtaining the TemplateBundle via network download, loading local cache, or any other method. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### prepareTemplateEnd

```tsx
prepareTemplateEnd: number;
```

The time when the container finishes preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparing" means obtaining the TemplateBundle via network download, loading local cache, or any other method. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.init-container-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/init-lynxview-entry.md
---

#Deprecated InitLynxviewEntry
:::warning
This event has been deprecated since Lynx SDK 3.7. Related data can be obtained from [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) / [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md).
:::

APISummary
The `InitLynxviewEntry` interface provides key times regarding the initialization of [LynxView](/guide/spec.md#lynxview). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of lynxview initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-lynxview-entry.png)

## Examples

This example demonstrates how to retrieve `InitLynxviewEntry`。

**This is an example below: performance-api**

**Entry:** `src/init-lynx-view-entry`
**Bundle:** `dist/init-lynx-view-entry.lynx.bundle`

```tsx {10-21}
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitLynxviewEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [initLynxviewEntry, setInitLynxviewEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "init" && entry.name == "lynxview") {
        // 3. Received "init.lynxview" event.
        const initLynxviewEntry = entry as InitLynxviewEntry;
        setInitLynxviewEntry(JSON.stringify(initLynxviewEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.lynxview" event.
    observer.observe(["init.lynxview"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitLynxviewEntry~</text>
      <text className="entry">{initLynxviewEntry}</text>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `lynxview`.

### createLynxStart

```tsx
createLynxStart: number;
```

The time LynxView starts creating. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### createLynxEnd

```tsx
createLynxEnd: number;
```

The time LynxView creation is complete. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.init-lynxview-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/init-background-runtime-entry.md
---

#Deprecated InitBackgroundRuntimeEntry
:::warning
This event has been deprecated since Lynx SDK 3.7. Related data can be obtained from [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) / [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md).
:::

APISummary
The `InitBackgroundRuntimeEntry` interface provides the key moments regarding the initialization of the [Background Thread Runtime](/guide/spec.md#background-thread-runtime). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

In the initialization process, the metrics are defined as shown in the figure below:
![key moments of background thread runtime initialization](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/init-background-runtime-entry.png)

## Examples

This example demonstrates how to retrieve `InitBackgroundRuntimeEntry`。

**This is an example below: performance-api**

**Entry:** `src/init-background-runtime-entry`
**Bundle:** `dist/init-background-runtime-entry.lynx.bundle`

```tsx {11-23}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { InitBackgroundRuntimeEntry, PerformanceEntry } from "@lynx-js/types";

import "./index.css";

export default function InitBackgroundRuntimeEntryExample(this: any) {
  const [initBackgroundRuntimeEntry, setInitBackgroundRuntimeEntry] = useState<string>("");

  function observerPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      if (entry.entryType == "init" && entry.name == "backgroundRuntime") {
        // 3. Received "init.backgroundRuntime" event.
        const initBackgroundRuntimeEntry = entry as InitBackgroundRuntimeEntry;
        setInitBackgroundRuntimeEntry(JSON.stringify(initBackgroundRuntimeEntry, null, 4));
        observer.disconnect();
      }
    });
    // 2. register to listen to the "init.backgroundRuntime" event.
    observer.observe(["init.backgroundRuntime"]);
  }

  useMemo(() => {
    observerPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello InitBackgroundRuntimeEntry~</text>
      <text className="entry">{initBackgroundRuntimeEntry}</text>
    </view>
  );
}

root.render(<InitBackgroundRuntimeEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```tsx
entryType: string;
```

Returns the entry type, which is always `init`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```tsx
name: string;
```

Returns the entry name, which is always `backgroundRuntime`.

### loadCoreStart

```tsx
loadCoreStart: number;
```

The start timestamp for initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### loadCoreEnd

```tsx
loadCoreEnd: number;
```

The end timestamp for initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.init-background-runtime-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |

**Description:** Entry for background runtime initialization performance data.




---
url: /api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md
---

#Deprecated MetricFcpEntry
:::warning
This event has been deprecated since Lynx SDK 3.7. Related data can be obtained from [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md) / [`ReloadBundleEntry`](/api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md).
:::

APISummary
FCP is a key performance metric that measures the time taken for the [first-screen rendering](/guide/spec.md#first-screen-rendering-or-fsr) of lynx app to complete. It refers to the time taken for users to see any content (such as text or images) on a lynx app for the first time. `MetricFcpEntry` interface provides timing information about this metric, inheriting from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

The FCP event is triggered when Lynx completes the rendering of the first frame of the lynx app. For lynx apps that rely on network requests or asynchronous I/O to fetch data, the typical state monitored at FCP is the loading page or a placeholder, as shown in the diagram below:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/performance-metrics-fcp.png)
Depending on different starting points, Lynx provides three metrics: `fcp`, `lynxFcp`, and `totalFcp`. Each metric's definition in the rendering process is illustrated in the diagram below:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/metric-fcp-entry.png)
## Example

This example demonstrates how to obtain a `MetricFcpEntry`.

Lynx calculates the FCP upon completion of the first frame rendering. If you have provided container-related timestamps using [LynxView.setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md), the `MetricFcpEntry` includes `fcp`, `lynxFcp`, and `totalFcp`. Otherwise, the `MetricFcpEntry` only contains `lynxFcp`. After supplementing the [container](/guide/spec.md#container) timestamp, the remaining metrics will be recalculated. Once recalculation is complete, Lynx will send a new `MetricFcpEntry` containing all the metrics.

**This is an example below: performance-api**

**Entry:** `src/fcp-entry`
**Bundle:** `dist/fcp-entry.lynx.bundle`

```tsx {10-20}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { MetricFcpEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.scss";

export default function MetricFcpEntryExample(this: any) {
  const [fcpEntry, setFcpEntry] = useState<string>("");

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "metric" && entry.name == "fcp") {
        // 3. Received "metric.fcp" event.
        const fcpEntry = entry as MetricFcpEntry;
        setFcpEntry(JSON.stringify(fcpEntry, null, 4));
      }
    });
    // 2. Register to listen to the "metric.fcp" event.
    observer.observe(["metric.fcp"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello MetricFcpEntry~</text>
      <text className="entry">{fcpEntry}</text>
    </view>
  );
}

root.render(<MetricFcpEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of performance event; the value for all instances of this class is fixed as `metric`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `fcp`.

### fcp

```ts
fcp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `fcp = LoadBundleEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxFcp

```ts
lynxFcp: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxFcp = LoadBundleEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalFcp

```ts
totalFcp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of the first rendering, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalFcp = LoadBundleEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.metric-fcp-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md
---

#Deprecated MetricActualFmpEntry
:::warning
This event has been deprecated since Lynx SDK 3.7. Related data can be obtained from [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).
:::

APISummary
Actual FMP is a key performance metric that measures the time taken for the rendering of the "real data" of a page to complete. It reflects how quickly users see the actual data on the page. `MetricActualFmpEntry` interface provides timing information about this metric, inheriting from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

You can generate this metric by marking the [lynx pipeline](/guide/spec.md#lynx-pipeline) that contains important elements with [`__lynx_timing_flag="__lynx_timing_actual_fmp"`](/guide/performance/monitor-performance/timing-flag.md).

In the "real data" rendering, the timing for Actual FMP is as follows:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/performance-metrics-actual-fmp.png)
Depending on different starting points, Lynx provides three metrics: `actualFmp`, `lynxActualFmp`, and `totalActualFmp`. Each metric's definition in the rendering process is illustrated in the diagram below:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/metric-actual-fmp-entry.png)
## Example

This example demonstrates how to generate and obtain a `MetricActualFmpEntry`.

Lynx calculates the Actual Fmp when the marked elements have finished rendering. If you have provided container-related timestamps using [LynxView.setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md), the `MetricActualFmpEntry` includes three metrics: `actualFmp`, `lynxActualFmp`, and `totalActualFmp`. Otherwise, the `MetricActualFmpEntry` only contains `lynxActualFmp`. After supplementing the [container](/guide/spec.md#container) timestamp, the remaining metrics will be recalculated. Once recalculation is complete, Lynx will send a new `lynxActualFmp` containing all the metrics.

**This is an example below: performance-api**

**Entry:** `src/actual-fmp-entry`
**Bundle:** `dist/actual-fmp-entry.lynx.bundle`

```tsx {12-22,27,34}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { MetricActualFmpEntry, PerformanceEntry } from "@lynx-js/types";
import "./index.scss";

export default function MetricActualFmpEntryExample(this: any) {
  const [msg, setMsg] = useState<string>("This is the initialization data.");
  const [actualfmpEntry, setActualFMPEntry] = useState<string>("");
  const [hasActualData, setHasActualData] = useState<boolean>(false);

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "metric" && entry.name == "actualFmp") {
        // 3. Received "metric.actualFmp" event.
        const actualfmpEntry = entry as MetricActualFmpEntry;
        setActualFMPEntry("actualfmpEntry : " + JSON.stringify(actualfmpEntry, null, 4));
      }
    });
    // 2. egister to listen to the "metric.actualFmp" event.
    observer.observe(["metric.actualFmp"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMsg("This is the actual data.");
      setHasActualData(true);
    }, 3000);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello MetricActualFmpEntry~</text>
      <text __lynx_timing_flag={hasActualData ? "__lynx_timing_actual_fmp" : ""}>{msg}</text>
      <text className="entry">{actualfmpEntry}</text>
    </view>
  );
}

root.render(<MetricActualFmpEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of performance event; the value for all instances of this class is fixed as `metric`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `actualFmp`.

### actualFmp

```ts
actualFmp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `actualFmp = PipelineEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxActualFmp

```ts
lynxActualFmp: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxActualFmp = PipelineEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalActualFmp

```ts
totalActualFmp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of rendering for components and tags marked with `__lynx_timing_flag="__lynx_timing_actual_fmp"`, with a data type of [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalActualFmp = PipelineEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.metric-actual-fmp-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/pipeline-entry.md
---

# PipelineEntry

APISummary
`PipelineEntry` is responsible for recording performance data at key moments during the [Lynx Pipeline](/guide/spec.md#lynx-pipeline), specifically for [Framework Rendering](/guide/spec.md#framework-rendering) and [Pixel Pipeline](/guide/spec.md#pixel-pipeline). It inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

The Lynx Pipeline refers to the complete process from the trigger of rendering to the final display. This process is divided into four main parts: Load, Parse, Framework Rendering (FrameworkPipeline), and Engine Rendering (PixelPipeline).

Due to the frequent triggering of the Lynx Pipeline, the framework only records the following two cases:

1. **Lynx Pipeline marked with [`__lynx_timing_flag`](/guide/performance/monitor-performance/timing-flag.md)**, which generate performance data as `PipelineEntry`.
2. **Lynx Pipeline triggered by loading and executing a [TemplateBundle](/api/lynx-native-api/template-bundle.md)**, which generate performance data as [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

The following is the flowchart for `PipelineEntry`:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/pipeline-entry-3-7-compressed.png)
## Example

This example demonstrates how to generate and retrieve `PipelineEntry`.

**This is an example below: performance-api**

**Entry:** `src/pipeline-entry`
**Bundle:** `dist/pipeline-entry.lynx.bundle`

```tsx {11-21,34}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [myName, setMyName] = useState<string | undefined>(undefined);

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("PipelineEntry");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; used to distinguish the source of the Pipeline trigger. Possible values include:

- `loadBundle`
- `reloadBundleFromNative`
- `reloadBundleFromBts`
- `updateTriggeredByBts`
- `updateTriggeredByNative`
- `updateGlobalProps`
- `setNativeProps`

### identifier

```ts
identifier: string;
```

A marker for a particular Lynx Pipeline. It can have the following two values:

1. For Lynx Pipelines marked with `__lynx_timing_flag`, **`identifier` equals the value of `__lynx_timing_flag`**.
2. For Lynx Pipelines triggered by loading and executing a `TemplateBundle`, **`identifier` is an empty string**.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

### actualFmp

```ts
actualFmp?: PerformanceMetric;
```

The time taken from preparing a [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering elements and tags with `__lynx_timing_flag="__lynx_timing_actual_fmp"`. The data type is [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `actualFmp = PipelineEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxActualFmp

```ts
lynxActualFmp?: PerformanceMetric;
```

The time taken from loading a [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of rendering elements and tags with `__lynx_timing_flag="__lynx_timing_actual_fmp"`. The data type is [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxActualFmp = PipelineEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalActualFmp

```ts
totalActualFmp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of rendering elements and tags with `__lynx_timing_flag="__lynx_timing_actual_fmp"`. The data type is [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalActualFmp = PipelineEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.pipeline-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/load-bundle-entry.md
---

# LoadBundleEntry

APISummary
_LoadBundle_ refers to the initial frame rendering pipeline triggered by [LynxView](/guide/spec.md#lynxview) loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). `LoadBundleEntry` is used to record the performance data of this rendering pipeline and inherits from [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

The LoadBundle process flowchart is as follows:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/load-bundle-entry-3-7-compressed.png)
:::tip

If you fail to receive `LoadBundleEntry`, it may be due to the following reasons:

**1. Rendering not triggered**

The rendering pipeline is not executed, typically because:

- **LynxView container state issues**: Width/Height is 0, not in the viewport, or not added to the window.
- **Business logic renders no content**: For example, in ReactLynx, the component's `render()` function returns `null` because data is not ready.

**2. Listener registered too late**

`LoadBundleEntry` is triggered only once upon completion of initial rendering. It is recommended to register the listener as early as possible:

- Register in `constructor` for class components.
- register in `useMemo` for functional components.

:::

## Example

This example demonstrates how to obtain a `LoadBundleEntry`.

**This is an example below: performance-api**

**Entry:** `src/load-bundle-entry`
**Bundle:** `dist/load-bundle-entry.lynx.bundle`

```tsx {10-20}
import { root, useMemo, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function LoadBundleEntryExample(this: any) {
  const [loadBundleEntry, setLoadBundleEntry] = useState("");

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline" && entry.name == "loadBundle") {
        // 3. Received "pipeline.loadBundle" event.
        const loadBundleEntry = entry as LoadBundleEntry;
        setLoadBundleEntry(JSON.stringify(loadBundleEntry, null, 4));
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello LoadBundleEntry~</text>
      <ScrollItem title="LoadBundleEntry" value={loadBundleEntry} />
    </view>
  );
}

root.render(<LoadBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific name of the performance event; the value for all instances of this class is fixed as `loadBundle`.

### identifier

```ts
identifier: string;
```

A marker for a particular rendering pipeline; the value for all instances of this class is fixed as an empty string.

### loadBundleStart

```ts
loadBundleStart: number;
```

The timestamp for the start of loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBundleEnd

```ts
loadBundleEnd: number;
```

The timestamp for the end of loading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### parseStart

```ts
parseStart: number;
```

The timestamp for the start of parsing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### parseEnd

```ts
parseEnd: number;
```

The timestamp for the end of parsing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBackgroundStart

```ts
loadBackgroundStart: number;
```

The timestamp for the start of loading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadBackgroundEnd

```ts
loadBackgroundEnd: number;
```

The timestamp for the end of loading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

### loadCoreStart

```ts
loadCoreStart: number;
```

The timestamp for the start of initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadCoreEnd

```ts
loadCoreEnd: number;
```

The timestamp for the end of initializing the [background thread runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### openTime

```ts
openTime?: number;
```

The time when the container starts opening the Lynx page. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### containerInitStart

```ts
containerInitStart?: number;
```

The timestamp for the start of container initialization. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### containerInitEnd

```ts
containerInitEnd?: number;
```

The timestamp for the end of container initialization. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### prepareTemplateStart

```ts
prepareTemplateStart?: number;
```

The time when the container starts preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparation" refers to the container obtaining the TemplateBundle through any means such as network download or loading local cache. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### prepareTemplateEnd

```ts
prepareTemplateEnd?: number;
```

The time when the container completes preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparation" refers to the container obtaining the TemplateBundle through any means such as network download or loading local cache. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### createLynxStart

```ts
createLynxStart: number;
```

The timestamp for the start of creating the LynxView. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### createLynxEnd

```ts
createLynxEnd: number;
```

The timestamp for the end of creating the LynxView. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### fcp

```ts
fcp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to completing the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `fcp = LoadBundleEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxFcp

```ts
lynxFcp: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to completing the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxFcp = LoadBundleEntry.paintEnd - LoadBundleEntry.loadBundleStart`.

### totalFcp

```ts
totalFcp?: PerformanceMetric;
```

The time taken from the user opening the page to completing the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalFcp = LoadBundleEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.load-bundle-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/lazy-bundle-entry.md
---

# LazyBundleEntry

APISummary
Through [lazy loading components](/react/code-splitting.md#lazy-loading-components), developers can render on demand, thereby improving user experience. `LazyBundleEntry` is used to record the performance data of lazy loading components and inherits from [`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md).

## Example

This example demonstrates how to obtain a `LazyBundleEntry`.

**This is an example below: performance-api**

**Entry:** `src/lazy-bundle-entry`
**Bundle:** `dist/lazy-bundle-entry.lynx.bundle`

```tsx {17-22,31-33}
import { lazy, root, Suspense, useState } from "@lynx-js/react";
import type { LazyBundleEntry, PerformanceEntry } from "@lynx-js/types";
import { useEffect } from "react";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

const MyLazyBundle = lazy(() => import("./MyLazyBundle.jsx"));

export default function LazyBundleEntryExample() {
  const [lazyBundleEntry, setLazyBundleEntry] = useState("");
  const [entryName, setEntryName] = useState("Waiting...");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "resource") {
        // 3. Received "resource.lazyBundleEntry" event.
        const lazyBundleEntry = entry as LazyBundleEntry;
        setLazyBundleEntry(JSON.stringify(lazyBundleEntry, null, 4));
        setEntryName("LazyBundleEntry");
      }
    });
    // 2. Register to listen to the "resource" event.
    observer.observe(["resource"]);
  }, []);

  return (
    <view className="container">
      <text className="title">Hello LazyBundleEntry~</text>
      <Suspense fallback={<text className="sub-text">Loading...</text>}>
        <MyLazyBundle />
      </Suspense>
      <ScrollItem title={entryName} value={lazyBundleEntry} />
    </view>
  );
}

root.render(<LazyBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `resource`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The name of the performance event; the value for all instances of this class is fixed as `lazyBundle`.

### componentUrl

```tsx
componentUrl: string;
```

The URL string used to load the lazy loading component.

### size

```tsx
size: number;
```

The resource size of the lazy loading component, in bytes.

### mode

```tsx
mode: string;
```

The mode for loading the lazy loading component, with values: `preload` or `normal`.

### sync

```tsx
sync: boolean;
```

Whether the lazy loading component is rendered synchronously.

### loadSuccess

```tsx
loadSuccess: boolean;
```

Whether the lazy loading component was loaded successfully.

### requireStart

```tsx
requireStart: number;
```

The start timestamp for downloading the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### requireEnd

```tsx
requireEnd: number;
```

The end timestamp for downloading the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### decodeStart

```tsx
decodeStart: number;
```

The start timestamp for decoding the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

### decodeEnd

```tsx
decodeEnd: number;
```

The end timestamp for decoding the lazy loading component.This timestamp is a floating-point Unix timestamp (in milliseconds).

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.lazy-bundle-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-entry/reload-bundle-entry.md
---

# ReloadBundleEntry

APISummary
_ReloadBundle_ refers to the reload rendering pipeline triggered by the native interface `LynxView.reloadTemplate` or the frontend framework interface [`lynx.reload`](/api/lynx-api/lynx/lynx-reload.md), which causes the rendering pipeline of the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to be reloaded and executed. `ReloadBundleEntry` is used to record the performance data for the reload pipeline and inherits from [`PipelineEntry`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md).

The reloadBundle process flowchart is as follows:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/reload-bundle-entry-3-7-compressed.png)
## Example

This example demonstrates how to obtain a `ReloadBundleEntry`.

**This is an example below: performance-api**

**Entry:** `src/reload-bundle-entry`
**Bundle:** `dist/reload-bundle-entry.lynx.bundle`

```tsx {14-25}
import { root, useCallback, useEffect, useState } from "@lynx-js/react";
import type { LoadBundleEntry, PerformanceEntry, PipelineEntry, ReloadBundleEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function ReloadBundleEntryExample() {
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [entryName, setEntryName] = useState("pending");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline.loadBundle" event.
        const pipelineEntry = entry as PipelineEntry;
        setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
        if (entry.name.startsWith("reloadBundle")) {
          const reloadEntry = entry as ReloadBundleEntry;
          setEntryName(reloadEntry.name);
        } else if (entry.name.startsWith("loadBundle")) {
          const loadEntry = entry as LoadBundleEntry;
          setEntryName(loadEntry.name);
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    lynx.reload({}, () => {});
  }, []);

  return (
    <view className="container">
      <text className="title">Hello ReloadBundleEntry~</text>
      <text className="button" bindtap={onTap}>Click To Reload</text>
      <ScrollItem title={entryName} value={pipelineEntry} />
    </view>
  );
}

root.render(<ReloadBundleEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance properties

### [entryType](/api/lynx-api/performance-api/performance-entry.md#entryType)

```ts
entryType: string;
```

The type of the performance event; the value for all instances of this class is fixed as `pipeline`.

### [name](/api/lynx-api/performance-api/performance-entry.md#name)

```ts
name: string;
```

The specific names of the performance events; the value for events triggered by the native interface `LynxView.reloadTemplate` is fixed as `reloadBundleFromNative`; the value for events triggered by the frontend framework interface `lynx.reload` is fixed as `reloadBundleFromBts`.

### identifier

```ts
identifier: string;
```

A marker for a particular rendering pipeline; the value for all instances of this class is fixed as an empty string.

### reloadBundleStart

```ts
reloadBundleStart: number;
```

The timestamp for the start of reloading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBundleEnd

```ts
reloadBundleEnd: number;
```

The timestamp for the end of reloading and executing the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBackgroundStart

```ts
reloadBackgroundStart: number;
```

The timestamp for the start of reloading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### reloadBackgroundEnd

```ts
reloadBackgroundEnd: number;
```

The timestamp for the end of reloading and executing the [background thread scripts](/guide/spec.md#background-thread-script-or-bts) in the [TemplateBundle](/api/lynx-native-api/template-bundle.md). This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineStart

```ts
pipelineStart: number;
```

The timestamp for the start of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### pipelineEnd

```ts
pipelineEnd: number;
```

The timestamp for the end of the rendering pipeline. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderStart

```ts
mtsRenderStart: number;
```

The timestamp for the start of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### mtsRenderEnd

```ts
mtsRenderEnd: number;
```

The timestamp for the end of executing the [main thread scripts](/guide/spec.md#main-thread-script-or-mts) to build the Element Tree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveStart

```ts
resolveStart: number;
```

The timestamp for the start of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### resolveEnd

```ts
resolveEnd: number;
```

The timestamp for the end of calculating [Element](/guide/spec.md#element) styles. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutStart

```ts
layoutStart: number;
```

The timestamp for the start of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutEnd

```ts
layoutEnd: number;
```

The timestamp for the end of [layout](/guide/spec.md#layout) calculations. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteStart

```ts
paintingUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintingUiOperationExecuteEnd

```ts
paintingUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to painting. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteStart

```ts
layoutUiOperationExecuteStart: number;
```

The timestamp for the start of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### layoutUiOperationExecuteEnd

```ts
layoutUiOperationExecuteEnd: number;
```

The timestamp for the end of executing [UI operations](/guide/spec.md#ui-op) related to layout. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### paintEnd

```ts
paintEnd: number;
```

The timestamp for the end of completing the final pixelation based on UI and UITree. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### frameworkPipelineTiming

```ts
frameworkPipelineTiming: FrameworkPipelineTiming[keyof FrameworkPipelineTiming];
```

Performance data for key stages in [Framework Rendering](/guide/spec.md#framework-rendering). The type is [`FrameworkPipelineTiming`](/api/lynx-api/performance-api/framework-pipeline-timing.md).

### hostPlatformTiming

```ts
hostPlatformTiming: AndroidHostPlatformTiming |
  HarmonyHostPlatformTiming |
  IOSHostPlatformTiming;
```

Performance data for platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline), with type [`AndroidHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md) | [`HarmonyHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md) | [`IOSHostPlatformTiming`](/api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md).

### loadCoreStart

```ts
loadCoreStart: number;
```

The timestamp for the start of initializing the [Background Thread Runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### loadCoreEnd

```ts
loadCoreEnd: number;
```

The timestamp for the end of initializing the [Background Thread Runtime](/guide/spec.md#background-thread-runtime) environment. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### openTime

```ts
openTime?: number;
```

The time when the container starts opening the Lynx page. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### containerInitStart

```ts
containerInitStart?: number;
```

The timestamp for the start of container initialization. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### containerInitEnd

```ts
containerInitEnd?: number;
```

The timestamp for the end of container initialization. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### prepareTemplateStart

```ts
prepareTemplateStart?: number;
```

The time when the container starts preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparation" refers to the container obtaining the TemplateBundle through any means such as network download or loading from local cache. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### prepareTemplateEnd

```ts
prepareTemplateEnd?: number;
```

The time when the container finishes preparing the [TemplateBundle](/guide/spec.md#app-bundle-aka-template-bundle). "Preparation" refers to the container obtaining the TemplateBundle through any means such as network download or loading from local cache. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### createLynxStart

```ts
createLynxStart: number;
```

The time when the LynxView starts to be created. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### createLynxEnd

```ts
createLynxEnd: number;
```

The time when the LynxView finishes being created. This timestamp is represented as a floating-point Unix timestamp (in milliseconds) with three decimal places. For example: 1739594612307.429.

### fcp

```ts
fcp?: PerformanceMetric;
```

The time taken from preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `fcp = ReloadBundleEntry.paintEnd - InitContainerEntry.prepareTemplateStart`.

### lynxFcp

```ts
lynxFcp?: PerformanceMetric;
```

The time taken from loading the [TemplateBundle](/api/lynx-native-api/template-bundle.md) to the completion of the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `lynxFcp = ReloadBundleEntry.paintEnd - ReloadBundleEntry.loadBundleStart`.

### totalFcp

```ts
totalFcp?: PerformanceMetric;
```

The time taken from the user opening the page to the completion of the first rendering, with data type [`PerformanceMetric`](/api/lynx-api/performance-api/performance-metric.md).

Calculation formula: `totalFcp = ReloadBundleEntry.paintEnd - InitContainerEntry.openTime`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-entry.reload-bundle-entry`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-observer.md
---

# PerformanceObserver

APISummary
The `PerformanceObserver` is used to observe performance events and receive notifications when [Lynx Engine](/guide/spec.md#engine) generates [performance entries](/api/lynx-api/performance-api/performance-entry.md).
It must be created through [`lynx.performance.createObserver()`](/api/lynx-api/lynx/lynx-performance.md#createobserver) and bind with a callback function for handling received performance entries upon creation.

## Instance methods

[`PerformanceObserver.observe()`](/api/lynx-api/performance-api/performance-observer/observe.md)

Specify a set of performance entry types to observe and start observing.

[`PerformanceObserver.disconnect()`](/api/lynx-api/performance-api/performance-observer/disconnect.md)

Stop receiving performance entries.

## Examples

### Creating a PerformanceObserver

The following example creates a `PerformanceObserver` watching for [`metric.fcp`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`pipeline`](/api/lynx-api/performance-api/performance-entry/pipeline-entry.md) entries.

**This is an example below: performance-api**

**Entry:** `src/simple-observe`
```tsx {11-30}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function SimpleObserveExample(this: any) {
  const [receivedEntries, setReceivedEntries] = useState<Set<string>>(new Set<string>());

  useMemo(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fsp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fsp") {
        entryType = "MetricFspEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fsp" and "pipeline" event.
    observer.observe(["metric.fsp", "pipeline"]);
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver</text>
      </view>
      <view className="card">
        <text className="section-title">Received PerformanceEntry:</text>
        <view className="entries-container">
          {Array.from(receivedEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<SimpleObserveExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-observer`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-observer/observe.md
---

# PerformanceObserver: observe() method

APISummary
Specifies types of performance events to observe and starts observing. The callback function set when creating the `PerformanceObserver` will be invoked when a matching
[`PerformanceEntry`](/api/lynx-api/performance-api/performance-entry.md) is received.

## Syntax

```ts
observe(entryIdentifiers: string[]): void
```

### Parameters

#### entryIdentifiers

```ts
entryIdentifiers: string[];
```

A string list of identifiers for the `PerformanceEntry` to be observed.

You can use **entryType** or **entryType.name** as identifiers. For example, you can use `"metric"` to listen to performance events for the entire metric type,
including [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md). Alternatively, you can use `"metric.fcp"` to listen only to the `MetricFcpEntry` performance event.

Refer to [`PerformanceEntry.entryType`](/api/lynx-api/performance-api/performance-entry.md#entryType) and [`PerformanceEntry.name`](/api/lynx-api/performance-api/performance-entry.md#name) for available types
and names. Unrecognized types will be ignored. If no valid types are found, `observe()` will not function.

:::tip
It is recommended to call this method during initialization, such as in the constructor of a root component or within the [`useMemo`](/api/react/Function.useMemo.md) Hook,
to ensure it is called as early as possible when the component or page loads, to avoid missing any data.
:::

### Return Value

None (`undefined`)

## Examples

### Observing all performance events under certain entryTypes

This example creates a `PerformanceObserver` that observes the entire `PerformanceEntry` of types through `["metric", "pipeline"]`.

**This is an example below: performance-api**

**Entry:** `src/performance-observer-observe`
**Bundle:** `dist/performance-observer-observe.lynx.bundle`

```tsx {12-38}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [receivedTypeEntries, setReceivedTypeEntries] = useState<Set<string>>(new Set<string>());
  const [receivedSpecificEntries, setReceivedSpecificEntries] = useState<Set<string>>(new Set<string>());

  function observerAllEntryTypePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric") {
        if (entry.name == "fcp") {
          entryType = "MetricFcpEntry";
        } else if (entry.name == "actualFmp") {
          entryType = "MetricActualFmpEntry";
        }
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedTypeEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric" and "pipeline" event.
    observer.observe(["metric", "pipeline"]);
  }

  function observeSpecificPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedSpecificEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }

  useMemo(() => {
    observerAllEntryTypePerformanceEntry();
    observeSpecificPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver::observe()</text>
      </view>
      <view className="card">
        <text className="section-title">Receive All EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedTypeEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
      <view className="card">
        <text className="section-title">Receive Specific EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedSpecificEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Observing specific performance events

This example creates a `PerformanceObserver` that observes `MetricFcpEntry` and the entire `PerformanceEntry` of type `pipeline` through `["metric.fcp", "pipeline"]`.

**This is an example below: performance-api**

**Entry:** `src/performance-observer-observe`
**Bundle:** `dist/performance-observer-observe.lynx.bundle`

```tsx {42-61}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [receivedTypeEntries, setReceivedTypeEntries] = useState<Set<string>>(new Set<string>());
  const [receivedSpecificEntries, setReceivedSpecificEntries] = useState<Set<string>>(new Set<string>());

  function observerAllEntryTypePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      console.log(JSON.stringify(entry));
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric") {
        if (entry.name == "fcp") {
          entryType = "MetricFcpEntry";
        } else if (entry.name == "actualFmp") {
          entryType = "MetricActualFmpEntry";
        }
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedTypeEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric" and "pipeline" event.
    observer.observe(["metric", "pipeline"]);
  }

  function observeSpecificPerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process "metric.fcp" and "pipeline"
      let entryType: string | undefined;
      if (entry.entryType == "metric" && entry.name == "fcp") {
        entryType = "MetricFcpEntry";
      } else if (entry.entryType == "pipeline") {
        entryType = "PipelineEntry";
      }
      if (entryType) {
        setReceivedSpecificEntries(prevEntries => {
          const newEntries = new Set(prevEntries);
          newEntries.add(entryType);
          return newEntries;
        });
      }
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["metric.fcp", "pipeline"]);
  }

  useMemo(() => {
    observerAllEntryTypePerformanceEntry();
    observeSpecificPerformanceEntry();
  }, []);

  return (
    <view className="container">
      <view className="title-container">
        <text className="title">Hello PerformanceObserver::observe()</text>
      </view>
      <view className="card">
        <text className="section-title">Receive All EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedTypeEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
      <view className="card">
        <text className="section-title">Receive Specific EntryType Events:</text>
        <view className="entries-container">
          {Array.from(receivedSpecificEntries).map((entryName, index) => (
            <text
              key={index}
              className="entry-item"
            >
              {entryName}
            </text>
          ))}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-observer.observe`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-observer/disconnect.md
---

# PerformanceObserver: disconnect() method

APISummary
Stop receiving performance events.

## Syntax

```ts
disconnect();
```

### Parameters

None

### Return Value

None (`undefined`)

## Examples

The following example disconnects the `PerformanceObserver` to disable receiving any more performance events.

**This is an example below: performance-api**

**Entry:** `src/performance-observer-disconnect`
**Bundle:** `dist/performance-observer-disconnect.lynx.bundle`

```tsx {17-18}
import * as React from "@lynx-js/react";
import { root, useMemo, useState } from "@lynx-js/react";
import type { PerformanceEntry } from "@lynx-js/types";
import "../common/common.css";
import "./index.css";

export default function InitLynxviewEntryExample(this: any) {
  const [hasReceivedEntries, setHasReceivedEntries] = useState<boolean>(false);

  function observePerformanceEntry() {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      // 3. process performance entries
      setHasReceivedEntries(true);
      console.log(JSON.stringify(entry));
      // 4. stop receive more performance entries if needed
      observer.disconnect();
    });
    // 2. register to listen to the "metric.fcp" and "pipeline" event.
    observer.observe(["pipeline"]);
  }

  useMemo(() => {
    observePerformanceEntry();
  }, []);

  return (
    <view className="container">
      <text className="title">Hello PerformanceObserver::disconnect()</text>
      <view className="card">
        <text className="section-title">Is PerformanceObserver running?</text>
        <view className="entries-container">
          {hasReceivedEntries
            ? <text className="entry">Disconnect</text>
            : <text className="entry-item">Observing</text>}
        </view>
      </view>
    </view>
  );
}

root.render(<InitLynxviewEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-observer.disconnect`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/performance-metric.md
---

# PerformanceMetric

APISummary
Describes the type that includes the performance metric name, metric value, and start/end timestamps.

In Lynx, several metric types are provided, such as [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md). Each metric type contains multiple metrics based on different starting points (for example, `MetricFcpEntry` includes metrics like `fcp`, `lynxFcp`, and `totalFcp`). To better describe the duration and timestamps of each metric, the `PerformanceMetric` type is designed.

## Attributes

### name

```ts
name: string;
```

The name of the metric, such as `fcp`, `lynxFcp`, `totalFcp`, etc.

### duration

```ts
duration: number;
```

The metric value in milliseconds with a microsecond precision(0.001ms). An example value is 100.099.

The calculation formula is: `duration = endTimestamp - startTimestamp`.

### startTimestampName

```ts
startTimestampName: string;
```

The name of the metric's start timestamp, such as `loadBundleStart` in [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

### startTimestamp

```ts
startTimestamp: number;
```

The start timestamp of the metric, an Unix timestamp in milliseconds with a microsecond precision(0.001ms). An example value is 1739594612307.429.

### endTimestampName

```ts
endTimestampName: string;
```

The name of the metric's end timestamp, such as `paintEnd` in [`LoadBundleEntry`](/api/lynx-api/performance-api/performance-entry/load-bundle-entry.md).

### endTimestamp

```ts
endTimestamp: number;
```

The end timestamp of the metric, an Unix timestamp in milliseconds with a microsecond precision(0.001ms). An example value is 1739594612307.429.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.performance-metric`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/framework-pipeline-timing.md
---

# FrameworkPipelineTiming

APISummary
This interface describes the performance data of key stages in [framework rendering](/guide/spec.md#framework-rendering).

## Instance Properties

### dsl

```tsx
dsl: string;
```

A string describing the DSL type, with a default value of `reactlynx`.

### stage

```tsx
stage: string;
```

A string describing the type of framework data update process, with possible values `hydrate` and `update`. `hydrate` refers to the process of calibrating and updating [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) data using [background thread](/guide/spec.md#background-thread-aka-off-main-thread) data, while `update` refers to updates triggered in `useEffect`. For more information, see [ReactLynx Lifecycle](/react/lifecycle.md).

### diffVdomStart

```tsx
diffVdomStart: number;
```

The timestamp when the framework starts VDom Diff on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### diffVdomEnd

```tsx
diffVdomEnd: number;
```

The timestamp when the framework ends VDom Diff on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### packChangesStart

```tsx
packChangesStart: number;
```

The timestamp when the framework starts serializing change information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### packChangesEnd

```tsx
packChangesEnd: number;
```

The timestamp when the framework ends serializing change information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### parseChangesStart

```tsx
parseChangesStart: number;
```

The timestamp when the framework starts deserializing change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### parseChangesEnd

```tsx
parseChangesEnd: number;
```

The timestamp when the framework ends deserializing change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### patchChangesStart

```tsx
patchChangesStart: number;
```

The timestamp when the framework starts applying change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### patchChangesEnd

```tsx
patchChangesEnd: number;
```

The timestamp when the framework ends applying change information on the [main thread](/guide/spec.md#main-thread-or-lynx-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### hydrateParseSnapshotStart

```tsx
hydrateParseSnapshotStart: number;
```

The timestamp when the framework starts deserializing [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

:::tip
This property is only valid when `stage` is `hydrate`.
:::

### hydrateParseSnapshotEnd

```tsx
hydrateParseSnapshotEnd: number;
```

The timestamp when the framework ends deserializing [main thread](/guide/spec.md#main-thread-or-lynx-main-thread) information on the [background thread](/guide/spec.md#background-thread-aka-off-main-thread). This timestamp is a floating-point Unix timestamp (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

:::tip
This property is only valid when `stage` is `hydrate`.
:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.framework-pipeline-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/host-platform-timing/android-host-platform-timing.md
---

# AndroidHostPlatformTiming

APISummary
This interface describes the performance data specific to Android platform's Measure, Layout, and Draw operations in the [Lynx Pipeline](/guide/spec.md#lynx-pipeline), as shown in the following diagram:

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/host-platform-timing.png)
## Examples

This example shows how to generate and obtain `AndroidHostPlatformTiming`.

**This is an example below: performance-api**

**Entry:** `src/host-platform-timing`
**Bundle:** `dist/host-platform-timing.lynx.bundle`

```tsx {21-21}
import { root, useEffect, useState } from "@lynx-js/react";
import type { PerformanceEntry, PipelineEntry } from "@lynx-js/types";
import { ScrollItem } from "../common/scroll-item/index.jsx";
import "./index.scss";

export default function PipelineEntryExample() {
  const [myName, setMyName] = useState<string | undefined>(undefined);
  const [pipelineEntry, setPipelineEntry] = useState("");
  const [hostPlatformTiming, setHostPlatformTiming] = useState("");

  useEffect(() => {
    "background-only";
    // 1. Create a performance observer.
    const observer = lynx.performance.createObserver((entry: PerformanceEntry) => {
      if (entry.entryType == "pipeline") {
        // 3. Received "pipeline" event of "myPipeline".
        const pipelineEntry = entry as PipelineEntry;
        // `PerformanceEntry.identifier` is equal to `view.__lynx_timing_flag`.
        if (pipelineEntry.identifier == "myNamePipeline") {
          setPipelineEntry(JSON.stringify(pipelineEntry, null, 4));
          setHostPlatformTiming(JSON.stringify(pipelineEntry.hostPlatformTiming, null, 4));
        }
      }
    });
    // 2. Register to listen to the "pipeline" event.
    observer.observe(["pipeline"]);

    // Update real data after simulating a network request.
    setTimeout(() => {
      setMyName("HostPlatformTiming");
    }, 2000);
  }, []);

  return (
    <view className="container">
      <text className="title" __lynx_timing_flag={myName ? "myNamePipeline" : ""}>Hello {myName}~</text>
      <ScrollItem title="HostPlatformTiming" value={hostPlatformTiming} height="220px" />
      <ScrollItem title="PipelineEntry" value={pipelineEntry} />
    </view>
  );
}

root.render(<PipelineEntryExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `Android`.

### measureStart

```tsx
measureStart: number;
```

The timestamp when the first execution of [LynxView](/guide/spec.md#lynxview)'s [onMeasure](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### measureEnd

```tsx
measureEnd: number;
```

The timestamp when the last execution of [LynxView](/guide/spec.md#lynxview)'s [`onMeasure`](https://developer.android.com/reference/android/view/View#onMeasure\(int,%20int\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### layoutStart

```tsx
layoutStart: number;
```

The timestamp when the first execution of [LynxView](/guide/spec.md#lynxview)'s [`onLayout`](https://developer.android.com/reference/android/view/View#onLayout\(boolean,%20int,%20int,%20int,%20int\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### layoutEnd

```tsx
layoutEnd: number;
```

The timestamp when the last execution of [LynxView](/guide/spec.md#lynxview)'s [`onLayout`](https://developer.android.com/reference/android/view/View#onLayout\(boolean,%20int,%20int,%20int,%20int\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### drawStart

```tsx
drawStart: number;
```

The timestamp when the execution of [LynxView](/guide/spec.md#lynxview)'s [`dispatchDraw`](https://developer.android.com/reference/android/view/View#dispatchDraw\(android.graphics.Canvas\)) starts in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

### drawEnd

```tsx
drawEnd: number;
```

The timestamp when the execution of [LynxView](/guide/spec.md#lynxview)'s [`dispatchDraw`](https://developer.android.com/reference/android/view/View#dispatchDraw\(android.graphics.Canvas\)) ends in a Lynx Pipeline. This timestamp is a Unix timestamp represented as a floating-point number (in milliseconds), accurate to three decimal places. For example: 1739594612307.429.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.host-platform-timing.android-host-platform-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/host-platform-timing/harmony-host-platform-timing.md
---

# HarmonyHostPlatformTiming

APISummary
This interface describes performance data for Harmony platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline).

## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `Harmony`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.host-platform-timing.harmony-host-platform-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-api/performance-api/host-platform-timing/ios-host-platform-timing.md
---

# IOSHostPlatformTiming

APISummary
This interface describes performance data for iOS platform-specific key stages in [Lynx Pipeline](/guide/spec.md#lynx-pipeline).

## Instance Properties

### hostPlatformType

```tsx
hostPlatformType: string;
```

A string describing the Host Platform type, with default value: `iOS`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-api.performance-api.host-platform-timing.ios-host-platform-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ❌ No | - |




---
url: /api/lynx-native-api/lynx-view.md
---

# Overview

## LynxView

### [addLynxViewClient](/api/lynx-native-api/lynx-view/add-lynx-view-client.md)

- [Syntax](/api/lynx-native-api/lynx-view/add-lynx-view-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/add-lynx-view-client.md#compatibility)

### [destroy](/api/lynx-native-api/lynx-view/destroy.md)

- [Syntax](/api/lynx-native-api/lynx-view/destroy.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/destroy.md#compatibility)

### [enableAutoLayout](/api/lynx-native-api/lynx-view/enable-auto-layout.md)

- [Syntax](/api/lynx-native-api/lynx-view/enable-auto-layout.md#syntax)
- [Notes](/api/lynx-native-api/lynx-view/enable-auto-layout.md#notes)

### [findUIByIdSelector](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-ui-by-id-selector.md#compatibility)

### [findUIByName](/api/lynx-native-api/lynx-view/find-ui-by-name.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-ui-by-name.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-ui-by-name.md#compatibility)

### [findViewByIdSelector](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-view-by-id-selector.md#compatibility)

### [findViewByName](/api/lynx-native-api/lynx-view/find-view-by-name.md)

- [Syntax](/api/lynx-native-api/lynx-view/find-view-by-name.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/find-view-by-name.md#compatibility)

### [loadTemplate](/api/lynx-native-api/lynx-view/load-template.md)

- [Syntax](/api/lynx-native-api/lynx-view/load-template.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/load-template.md#compatibility)

### [`<lynx-view>`](/api/lynx-native-api/lynx-view/lynx-view.md)

- [lynx-view](/api/lynx-native-api/lynx-view/lynx-view.md#lynx-view)
- [FAQ](/api/lynx-native-api/lynx-view/lynx-view.md#faq)
- [Compatibility](/api/lynx-native-api/lynx-view/lynx-view.md#compatibility)

### [reload](/api/lynx-native-api/lynx-view/reload.md)

- [api: lynx-native-api/lynx-view/reload](/api/lynx-native-api/lynx-view/reload.md#api-lynx-native-apilynx-viewreload)
- [Syntax](/api/lynx-native-api/lynx-view/reload.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/reload.md#compatibility)

### [removeLynxViewClient](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md)

- [Syntax](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/remove-lynx-view-client.md#compatibility)

### [sendGlobalEvent](/api/lynx-native-api/lynx-view/send-global-event.md)

- [Syntax](/api/lynx-native-api/lynx-view/send-global-event.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/send-global-event.md#compatibility)

### [setExtraTiming](/api/lynx-native-api/lynx-view/set-extra-timing.md)

- [Syntax](/api/lynx-native-api/lynx-view/set-extra-timing.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/set-extra-timing.md#compatibility)

### [updateFontScale](/api/lynx-native-api/lynx-view/update-font-scale.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-font-scale.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-font-scale.md#compatibility)

### [updateMetaData](/api/lynx-native-api/lynx-view/update-meta-data.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-meta-data.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-meta-data.md#compatibility)

### [updateViewport](/api/lynx-native-api/lynx-view/update-viewport.md)

- [Syntax](/api/lynx-native-api/lynx-view/update-viewport.md#syntax)
- [Compatibility](/api/lynx-native-api/lynx-view/update-viewport.md#compatibility)



---
url: /api/lynx-native-api/lynx-view/add-lynx-view-client.md
---

# addLynxViewClient

APISummary
Register lifecycle event observer for `LynxView`.

## Syntax

### Android

```java
public void addLynxViewClient(LynxViewClient client);
```

#### Parameters

- `client`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle

### iOS

```objc
- (void)addLifecycleClient:(nonnull id<LynxViewBaseLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle.

### Harmony

#### Field

LynxView has clients member:

- `clients: LynxViewClient[]`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the `LynxView` lifecycle.

On the HarmonyOS platfrom, you need to pass your implemented LynxViewClient as a parameter during the initialization of LynxView:

```typescript
@Entry
@Component
struct Index {
  private clients: EntryLynxClient[] = [new EntryLynxClient()];

  build() {
    Column() {
      LynxView({
        clients: this.clients,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```

### Desktop (C++)

```cpp
void AddClient(std::shared_ptr<lynx::pub::LynxViewClient> client);
```

#### Parameters

- `client`: The lifecycle observer registered to the `LynxView` instance. The same client instance is retained by `LynxView` until it is removed.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.add-lynx-view-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** register lifecycle observer for lynxView




---
url: /api/lynx-native-api/lynx-view/destroy.md
---

# destroy

APISummary
After `LynxView` becomes unavailable, you need to actively call this method to release the `LynxView` memory, otherwise there will be a memory leak.

## Syntax

### Android

```java
public void destroy();
```

### Desktop (C++)

Desktop C++ API does not expose a standalone `destroy()` method. Release the `LynxView` by destroying or resetting the owning C++ object.

```cpp
std::unique_ptr<lynx::pub::LynxView> view = builder.Build();
// ...
view.reset();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** manually destroy lynxView instance




---
url: /api/lynx-native-api/lynx-view/enable-auto-layout.md
---

# enableAutoLayout

When enabled, the size calculated by iOS AutoLayout will take effect on LynxView.

## Syntax

### iOS

```objc
@property(nonatomic, assign) bool enableAutoLayout;
```

#### Parameter Description

`enableAutoLayout`: Boolean switch

- The default value is `false`. When the value is `false`, LynxView will ignore the size results calculated by the AutoLayout engine.
- When the value is `true`, LynxView will use the size results calculated by the AutoLayout engine.

#### Example Code

```objc
- (void)setupMainLynxView {
  self.mainLynxView.translatesAutoresizingMaskIntoConstraints = NO;
  [NSLayoutConstraint activateConstraints:@[
    [self.mainLynxView.topAnchor constraintEqualToAnchor:self.autoLayoutSwitch.bottomAnchor
                                                constant:20],
    [self.mainLynxView.leadingAnchor constraintEqualToAnchor:self.view.leadingAnchor],
    [self.mainLynxView.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor],
    [self.mainLynxView.bottomAnchor
        constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor]
  ]];

  self.mainLynxView.enableAutoLayout = true;
}
```

## Notes

When enabled, `LynxView` will automatically use the results calculated by the AutoLayout engine as the view size during layout. If `updateViewport` was previously used to set the view size, the settings from `updateViewport` will be overwritten.

Related documentation: Please refer to [updateViewport](/api/lynx-native-api/lynx-view/update-viewport.md).



---
url: /api/lynx-native-api/lynx-view/find-ui-by-id-selector.md
---

# findUIByIdSelector

APISummary
Find `LynxUI` nodes based on the idSelector attribute.

## Syntax

### Android

```java
public LynxBaseUI findUIByIdSelector(String id);
```

#### Parameters

- `id`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the idSelector attribute.

### iOS

```objc
- (nullable LynxUI *)uiWithIdSelector:(nonnull NSString *)idSelector;
```

#### Parameters

- `idSelector`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the idSelector attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-ui-by-id-selector`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** find ui by idselector




---
url: /api/lynx-native-api/lynx-view/find-ui-by-name.md
---

# findUIByName

APISummary
Find `LynxUI` nodes based on the name attribute.

## Syntax

### Android

```java
public LynxBaseUI findUIByName(String name);
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the name attribute.

### iOS

```objc
- (nullable LynxUI *)uiWithName:(nonnull NSString *)name;
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `LynxUI` node corresponding to the name attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-ui-by-name`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** find ui by name




---
url: /api/lynx-native-api/lynx-view/find-view-by-id-selector.md
---

# findViewByIdSelector

APISummary
Find `UIView` based on `idSelector` property.

## Syntax

### Android

```java
public View findViewByIdSelector(String id);
```

#### Parameters

- `id`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the idSelector attribute.

### iOS

```objc
- (nullable UIView *)viewWithIdSelector:(nonnull NSString *)idSelector;
```

#### Parameters

- `idSelector`: The id attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the idSelector attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-view-by-id-selector`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** find view by idselector




---
url: /api/lynx-native-api/lynx-view/find-view-by-name.md
---

# findViewByName

APISummary
Find `UIView` based on name attribute.

## Syntax

### Android

```java
public View findViewByName(String name);
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the name attribute.

### iOS

```objc
- (nullable UIView *)findViewWithName:(nonnull NSString *)name;
```

#### Parameters

- `name`: The name attribute of the view specified by the front end in the layout file.

#### Return

- The `UIView` node corresponding to the name attribute.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.find-view-by-name`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** find view by name




---
url: /api/lynx-native-api/lynx-view/load-template.md
---

# loadTemplate

APISummary
Using [`LynxLoadMeta`](/api/lynx-native-api/lynx-load-meta.md) to render `LynxView`, it is the main entrance for the client to load `Lynx` templates.

## Syntax

### Android

```java
public void loadTemplate(@NonNull LynxLoadMeta meta);
```

#### Parameters

- `meta`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

### iOS

```objc
- (void)loadTemplate:(nonnull LynxLoadMeta *)meta;
```

#### Parameters

- `meta`: Lynx template loads metadata, and developers use this data structure to specify optional data loaded by the template.

### Harmony

LynxView has the following members:

- `url: String `: Template file path.
- `buffer: ArrayBuffer`: The binary file data of the template.
- `templateBundle: TemplateBundle`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data.
- `metaData: MetaData`: Initial data specified by the client during the first screen loading process.
- `loadOption: LynxLoadOption`: Additional configuration information when loading templates.

```typescript
@Entry
@Component
struct Index {
  private url: string = 'playground/main.lynx.bundle';
  private buffer: ArrayBuffer = getTemplateBuffer();
  private metaData = new MetaData(
    new TemplateData('{"text":"TD"}'),
    new TemplateData({ "theme": "Light" }));

  build() {
    Column() {
      LynxView({
        url: this.url,
        buffer: this.buffer,
        metadata: this.metaData,
      }).width('100%').height('100%');
    }
    .size({ width: '100%', height: '100%' })
  }
}
```

### Web

```typescript
const lynxView = document.createElement('lynx-view');
lynxView.url = 'path/to/your/template.bundle';
```

### Desktop (C++)

```cpp
void LoadTemplate(std::shared_ptr<lynx::pub::LynxLoadMeta> load_meta);
```

#### Parameters

- `load_meta`: The load metadata used to provide the template URL, binary data, template bundle, initial data, and global props.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.load-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | use the <code>url</code> property; ⚠️ Partial implementation |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** load a lynx template file by LynxView.




---
url: /api/lynx-native-api/lynx-view/lynx-view.md
---

# `<lynx-view>`

APISummary
`<lynx-view>` is a container component that loads and displays Lynx templates. It can be used in web applications to render Lynx templates.

After completing the above integration, you can achieve more flexible interaction control through the APIs provided by Lynx for Web. Here is a detailed description of the core APIs:

## lynx-view

### Attributes

| Name           | Required | Description                                                                                                                                             |
| :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| url            | Yes      | URL of the Rspeedy output (URLs of other chunks will be automatically injected and launched during compilation)                                         |
| globalProps    | No       | [GlobalProps](/api/lynx-api/lynx/lynx-global-props.md) for card initialization                                                                          |
| initData       | No       | InitData for card initialization                                                                                                                        |
| browser-config | No       | Configuring `pixelRatio`, `pixelWidth`, `pixelHeight` allowing the `systemInfo` payload to be dynamically configured at the instance level.             |
| transform-vw   | No       | Enable `vw` transformation, enabling container relative custom properties for `vw` units. E.g. `1vw` will be transformed to `calc(1 * var(--vw-unit))`. |
| transform-vh   | No       | Enable `vh` transformation, enabling container relative custom properties for `vh` units. E.g. `1vh` will be transformed to `calc(1 * var(--vh-unit))`. |

### Properties

#### nativeModulesMap

Custom [NativeModule](/guide/use-native-modules.md) where key is the module name and value is the module implementation (an ESM URL):

```ts
type NativeModulesMap = Record<string, string>;
```

Example:

```ts
const nativeModulesMap = {
  CustomModule: URL.createObjectURL(
    new Blob(
      [
        `export default function(NativeModules, NativeModulesCall) {
    return {
      async getColor(data, callback) {
        const color = await NativeModulesCall('getColor', data);
        callback(color);
      },
    }
  };`,
      ],
      { type: 'text/javascript' },
    ),
  ),
};
lynxView.nativeModulesMap = nativeModulesMap;
```

#### onNativeModulesCall

Entry point for handling NativeModules (JSB, etc.) related calls:

```ts
(name: string, data: any, moduleName: string) => Promise<any> | any;
```

Example:

```ts
// Handle NativeModule.bridge.call('request')
lynxView.onNativeModulesCall = (name, data, moduleName) => {
  if (moduleName === 'bridge') {
    if (name === 'request') {
      // ...

      // return data will be automatically processed as callback data
      return {};
    }
  }
};
```

#### browserConfig

Set `browserConfig` allowing the `systemInfo` payload to be dynamically configured at the instance level.

```ts
lynxView.browserConfig = {
  pixelRatio: 2,
  pixelWidth: 375,
  pixelHeight: 812,
};
```

### Events

#### error

Error message notification:

```ts
type LynxError = CustomEvent<{
  error: Error;
  sourceMap: {
    offset: {
      // Line offset
      line: number;
      // Column offset
      col: number;
    };
  };
  release: string;
  fileName: 'lepus.js' | 'app-service.js';
}>;

lynxView.addEventListener('error', (err: LynxError) => {
  // ...
});
```

### Methods

#### updateData

[See details](/api/lynx-native-api/lynx-view/update-meta-data.md)

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void
```

#### updateGlobalProps

[See details](/api/lynx-api/main-thread/lynx-global-props.md)

```ts
updateGlobalProps(data: Cloneable): void;
```

#### sendGlobalEvent

[See details](/api/lynx-native-api/lynx-view/send-global-event.md)

```ts
sendGlobalEvent(eventName: string, params: Cloneable[]): void;
```

### Width and Height

:::note
The internal layout of lynx-view will be forced out of the external layout flow
:::

We will force all lynx-view elements to apply [CSS Containment](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment).

That is, by default, you need to set a width and height for lynx-view. The width and height can be allocated by `flex-grow` or specified as a percentage, but cannot be "stretched". Setting width and height is a strongly recommended practice and also a best practice for performance.

In some cases where you really need the width or height to be determined by the content of lynx-view, you can set `height="auto"` or `width="auto"` to enable the automatic width/height listener. In this case, the internal layout of lynx-view remains independent of the external layout flow.

## FAQ

### Runtime error: `Uncaught SecurityError: Failed to construct 'Worker': Script at 'xxx' cannot be accessed from origin 'xxx'.`

This is because Worker loading remote scripts needs to comply with the [Same-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), and the JS resources of the project are generally deployed on CDN, causing cross-origin issues.

This can be solved by introducing [remote-web-worker](https://github.com/jantimon/remote-web-worker):

```ts
// The import position must be before @lynx-js/web-core
import 'remote-web-worker';

import '@lynx-js/web-core/client';
document.body.innerHTML = `
<lynx-view
    style="height:100vh; width:100vw;"
    url="http://localhost:3000/main/index.main.bundle"
>
</lynx-view>`;
```

### Performance Optimization

We provide an RSBuild plugin for performance optimization. You can introduce [this plugin](https://www.npmjs.com/package/@lynx-js/web-platform-rsbuild-plugin) in your web project.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.lynx-view-custom-element`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** <code>lynx-view</code> The custom element of LynxView.


## Migrating from older versions

If you are upgrading to `@lynx-js/web-core@0.20.0`, notice that there are significant breaking changes due to an architectural upgrade.

### Changes to initialization

You no longer need to import CSS manually, nor do you need `@lynx-js/web-elements`. The initialization is simplified:

```ts
// Before:
import '@lynx-js/web-core/index.css';
import '@lynx-js/web-elements/index.css';
import '@lynx-js/web-core';
import '@lynx-js/web-elements/all';

// After:
import '@lynx-js/web-core/client';
```

### Changes to API

The following `<lynx-view>` properties are removed and no longer supported:

- `thread-strategy`
- `customTemplateLoader`
- `overrideLynxTagToHTMLTagMap`
- `inject-head-links`



---
url: /api/lynx-native-api/lynx-view/reload.md
---

## api: lynx-native-api/lynx-view/reload

# reload

APISummary
Reload the current page.

## Syntax

### Web

```ts
reload(): void;
```

### Desktop (C++)

```cpp
void ReloadTemplate(std::shared_ptr<lynx::pub::LynxTemplateData> data,
                    std::shared_ptr<lynx::pub::LynxTemplateData> global_props);
```

#### Parameters

- `data`: The template data used for reload.
- `global_props`: The global props used for reload. Pass `nullptr` when not needed.

## Compatibility

Missing API QueryEither a query must be provided as the `query` prop to the `<APITable />`, or it will be retrieved from the `api` field in the frontmatter of the current page.




---
url: /api/lynx-native-api/lynx-view/remove-lynx-view-client.md
---

# removeLynxViewClient

APISummary
Remove `LynxView` lifecycle event monitoring.

## Syntax

### Android

```java
public void removeLynxViewClient(LynxViewClient client);
```

#### Parameters

- `client`: The structure implemented by the client and registered to the `LynxView` instance is used to obtain the callbacks of each process in the LynxView life cycle.

### Desktop (C++)

```cpp
void RemoveClient(std::shared_ptr<lynx::pub::LynxViewClient> client);
```

#### Parameters

- `client`: The lifecycle observer previously registered with `AddClient`. Passing the same shared client instance removes it from the `LynxView` lifecycle observer list.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.remove-lynx-view-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** remove lifecycle observer of lynxView




---
url: /api/lynx-native-api/lynx-view/send-global-event.md
---

# sendGlobalEvent

APISummary
Send global events to the front end through the client, and the front end can listen to the event through `GlobalEventEmitter`.

## Syntax

### Android

```java
public void sendGlobalEvent(String name, JavaOnlyArray params);
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

### iOS

```objc
- (void)sendGlobalEvent:(nonnull NSString *)name withParams:(nullable NSArray *)params;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

### Web

```ts
sendGlobalEvent(eventName: string, params: Cloneable[]): void;
```

#### Parameters

- `eventName`: Global event name.
- `params`: Parameters carried by global events.

### Desktop (C++)

```cpp
void SendGlobalEvent(const std::string& name, const std::string& json);
```

#### Parameters

- `name`: Global event name.
- `json`: The event payload serialized as a JSON string.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ✅ Yes | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** send global event to js enviroment




---
url: /api/lynx-native-api/lynx-view/set-extra-timing.md
---

# setExtraTiming

APISummary
This interface is used to supplement key performance data before loading the Lynx page, specifically including the following items from [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md):

- Page open time (`openTime`)
- Timestamp for the start of preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) (`prepareTemplateStart`)
- Timestamp for the end of preparing the TemplateBundle (`prepareTemplateEnd`)
- Timestamp for the start of [container](/guide/spec.md#container) initialization (`containerInitStart`)
- Timestamp for the end of container initialization (`containerInitEnd`)

Upon successfully updating all timestamps using this interface, the `InitContainerEntry` performance event will be triggered. Depending on the timing of the configuration, it may also trigger the calculation of `fcp`, `totalFcp`, `actualFmp`, and `totalActualFmp` metrics, along with dispatching new performance events for [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

:::caution
Timestamps within extraTiming cannot be overwritten, meaning that multiple calls to this interface attempting to repeatedly update a timestamp will yield no effect.
:::

## Syntax

### Android

```java
public void setExtraTiming(TimingHandler.ExtraTimingInfo extraTiming);
```

#### Parameters

- `extraTiming`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `ExtraTimingInfo` is as follows:

```java
public static class ExtraTimingInfo {
    // Page open time, corresponds to openTime in InitContainerEntry.
    public long mOpenTime = 0;
    // Timestamp for the start of preparing the TemplateBundle, corresponds to prepareTemplateStart in InitContainerEntry.
    public long mPrepareTemplateStart = 0;
    // Timestamp for the end of preparing the TemplateBundle, corresponds to prepareTemplateEnd in InitContainerEntry.
    public long mPrepareTemplateEnd = 0;
    // Timestamp for the start of container initialization, corresponds to containerInitStart in InitContainerEntry.
    public long mContainerInitStart = 0;
    // Timestamp for the end of container initialization, corresponds to containerInitEnd in InitContainerEntry.
    public long mContainerInitEnd = 0;
}
```

### iOS

```objc
- (void)setExtraTiming:(LynxExtraTiming *_Nonnull)timing;
```

#### Parameters

- `timing`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `LynxExtraTiming` is as follows:

```objc
@interface LynxExtraTiming : NSObject

// Page open time, corresponds to openTime in InitContainerEntry.
@property(nonatomic, assign) uint64_t openTime;
// Timestamp for the start of preparing the TemplateBundle, corresponds to prepareTemplateStart in InitContainerEntry.
@property(nonatomic, assign) uint64_t prepareTemplateStart;
// Timestamp for the end of preparing the TemplateBundle, corresponds to prepareTemplateEnd in InitContainerEntry.
@property(nonatomic, assign) uint64_t prepareTemplateEnd;
// Timestamp for the start of container initialization, corresponds to containerInitStart in InitContainerEntry.
@property(nonatomic, assign) uint64_t containerInitStart;
// Timestamp for the end of container initialization, corresponds to containerInitEnd in InitContainerEntry.
@property(nonatomic, assign) uint64_t containerInitEnd;

@end
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.set-extra-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** set extra timing from outside.




---
url: /api/lynx-native-api/lynx-view/update-font-scale.md
---

# updateFontScale

APISummary
Changing the font scaling ratio in client settings will automatically change the text size.

## Syntax

### Android

```java
public void updateFontScale(float scale);
```

#### Parameters

- `scale`: The new font scaling ratio.

### iOS

```objc
- (void)updateFontScale:(CGFloat)scale;
```

#### Parameters

- `scale`: The new font scaling ratio.

### Desktop (C++)

```cpp
void SetFontScale(float scale);
```

#### Parameters

- `scale`: The new font scaling ratio.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-font-scale`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** update font scale of lynxView




---
url: /api/lynx-native-api/lynx-view/update-meta-data.md
---

# updateMetaData

APISummary
Using [LynxUpdateMeta](/api/lynx-native-api/lynx-update-meta.md) to update `LynxView`, it is the main entrance for the client to update template data.

## Syntax

### Android

```java
public void updateMetaData(LynxUpdateMeta meta);
```

#### Parameters

- `meta`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

### iOS

```objc
- (void)updateMetaData:(nonnull LynxUpdateMeta *)meta;
```

#### Parameters

- `meta`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

### Web

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void;
updateGlobalProps(data: Cloneable): void;
```

#### Parameters

- `data`: Data to be updated, should be `structuredClone` compatible.

### Desktop (C++)

```cpp
void UpdateData(std::shared_ptr<lynx::pub::LynxUpdateMeta> update_meta);
```

#### Parameters

- `update_meta`: The update metadata used to provide template data and global props.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-meta-data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** update lynx page by new data.




---
url: /api/lynx-native-api/lynx-view/update-viewport.md
---

# updateViewport

APISummary
The client updates the `LynxView` view size.

## Syntax

### Android

```java
public void updateViewport(int widthMeasureSpec, int heightMeasureSpec);
```

#### Parameters

- `widthMeasureSpec`: Current `LynxView` width.
- `heightMeasureSpec`: Current `LynxView` height.

### iOS

```objc
- (void)updateViewportWithPreferredLayoutWidth:(CGFloat)preferredLayoutWidth
                         preferredLayoutHeight:(CGFloat)preferredLayoutHeight
                                    needLayout:(BOOL)needLayout;
```

#### Parameters

- `preferredLayoutWidth`: Current `LynxView` width.
- `preferredLayoutHeight`: Current `LynxView` height.
- `needLayout`: Whether layout needs to be triggered.

### Desktop (C++)

Desktop public API uses `SetFrame(...)` for the view rectangle, and exposes `UpdateScreenMetrics(...)` separately for screen metrics.

```cpp
void SetFrame(float x, float y, float width, float height);
```

#### Parameters

- `x`: The x coordinate of the `LynxView`.
- `y`: The y coordinate of the `LynxView`.
- `width`: Current `LynxView` width.
- `height`: Current `LynxView` height.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view.update-viewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** update viewport of lynxView




---
url: /api/lynx-native-api/lynx-view-client/on-data-updated.md
---

# onDataUpdated

APISummary
Called when data update, but the view may not be updated.

## Syntax

### Android

```java
public void onDataUpdated();
```

### iOS

```objc
- (void)lynxViewDidUpdate:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onDataUpdated(): void;
```

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnDataUpdated() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-data-updated`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when data update, but the view may not be updated.




---
url: /api/lynx-native-api/lynx-view-client/on-destroy.md
---

# onDestroy

APISummary
Called after the page is destroyed.

## Syntax

### Android

```java
public void onDestroy();
```

:::note

- The callback executed in the main thread.

:::

### Harmony

```typescript
public onDestroy(): void;
```

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnDestroy() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called after the page is destroyed.




---
url: /api/lynx-native-api/lynx-view-client/on-first-load-perf-ready.md
---

# onFirstLoadPerfReady

APISummary
Performance data statistics callback after the first load is completed.

## Syntax

### Android

```java
public void onFirstLoadPerfReady(LynxPerfMetric metric);
```

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-first-load-perf-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Performance data statistics callback after the first load is completed.




---
url: /api/lynx-native-api/lynx-view-client/on-first-screen.md
---

# onFirstScreen

APISummary
Called when first screen layout completed.

## Syntax

### Android

```java
public void onFirstScreen();
```

### iOS

```objc
- (void)lynxViewDidFirstScreen:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- You can get performance during loading process of the LynxView at this time.

:::

### Harmony

```typescript
public onFirstScreen(): void;
```

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnFirstScreen() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-first-screen`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when first screen layout completed.




---
url: /api/lynx-native-api/lynx-view-client/on-fling.md
---

# onFling

APISummary
Called when inertial scrolling starts after releasing the finger.

## Syntax

### Android

```java
public void onFling(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-fling`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when inertial scrolling starts after releasing the finger.




---
url: /api/lynx-native-api/lynx-view-client/on-flush-finish.md
---

# onFlushFinish

APISummary
Called when UI flush end in async render mode.

## Syntax

### Android

```java
public void onFlushFinish(FlushInfo flushInfo);
```

#### Parameters

- `flushInfo`: Contains the begin and end timings of the flush, and whether it is a synchronous flush.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-flush-finish`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when UI flush end in async render mode.




---
url: /api/lynx-native-api/lynx-view-client/on-key-event.md
---

# onKeyEvent

APISummary
Report all android key events with flag indicating whether has been handled.

## Syntax

### Android

```java
public void onKeyEvent(KeyEvent event, boolean handled);
```

#### Parameters

- `event`: The android key.
- `handled`: Indicate whether the event has been handled(consumed) by lynx.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-key-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Report all android key events with flag indicating whether has been handled.




---
url: /api/lynx-native-api/lynx-view-client/on-load-success.md
---

# onLoadSuccess

APISummary
Called when page load finish.

## Syntax

### Android

```java
public void onLoadSuccess();
```

### iOS

```objc
- (void)lynxView:(LynxView *)view didLoadFinishedWithUrl:(NSString *)url;
```

#### Parameters

- `view`: The LynxView instance.
- `url`: The page URL.

:::note

- This method is called once for each content loading request.

:::

### Harmony

```typescript
public onLoadSuccess(url: string): void;
```

#### Parameters

- `url`: The page url.

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnLoadSuccess() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-load-success`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when page load finish.




---
url: /api/lynx-native-api/lynx-view-client/on-lynx-event.md
---

# onLynxEvent

APISummary
Report Lynx events that sended to frontend.

## Syntax

### Android

```java
public void onLynxEvent(LynxEventDetail detail);
```

#### Parameters

- `detail`: LynxEvent that will send to frontend, including eventName, lynxview, etc.

### iOS

```objc
- (void)onLynxEvent:(LynxEventDetail *)event;
```

#### Parameters

- `event`: LynxEvent that will send to frontend, including eventName, lynxview, etc.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-lynx-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Report Lynx events that sended to frontend.




---
url: /api/lynx-native-api/lynx-view-client/on-lynx-view-and-js-runtime-destroy.md
---

# onLynxViewAndJSRuntimeDestroy

APISummary
Called when lynx view and js runtime destroy.

## Syntax

### Android

```java
public void onLynxViewAndJSRuntimeDestroy();
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-lynx-view-and-js-runtime-destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when lynx view and js runtime destroy.




---
url: /api/lynx-native-api/lynx-view-client/on-module-method-invoked.md
---

# onModuleMethodInvoked

APISummary
Called when module method invocation completed.

## Syntax

### Android

```java
public void onModuleMethodInvoked(String module, String method, int error_code);
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if module method invocation failed.

### iOS

```objc
- (void)lynxView:(LynxView *)view
    didInvokeMethod:(NSString *)method
           inModule:(NSString *)module
          errorCode:(int)code;
```

#### Parameters

- `view`: The LynxView instance.
- `method`: Method name.
- `module`: Module name.
- `code`: Error code if module method invocation failed.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-module-method-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when module method invocation completed.




---
url: /api/lynx-native-api/lynx-view-client/on-page-start.md
---

# onPageStart

APISummary
Called when page start loading.

## Syntax

### Android

```java
public void onPageStart(@Nullable String url);
```

#### Parameters

- `url`: The page URL

### iOS

```objc
- (void)lynxViewDidStartLoading:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- This method is called once for each content loading request.

:::

### Harmony

```typescript
public onPageStarted(lynxContext: LynxContext, pipelineInfo: LynxPipelineInfo): void;
```

#### Parameters

- `lynxContext`: The LynxContext which has started loading
- `pipelineInfo`: The information about the pixel pipeline

:::note

- This method will be executed before the main process of lynx so do not execute overlycomplex logic in this method.

:::

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnPageStart(const char* url) override;
};
```

#### Parameters

- `url`: The page URL.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-page-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when page start loading.




---
url: /api/lynx-native-api/lynx-view-client/on-page-update.md
---

# onPageUpdate

APISummary
Called when page update.

## Syntax

### Android

```java
public void onPageUpdate();
```

### iOS

```objc
- (void)lynxViewDidPageUpdate:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onPageUpdate(): void;
```

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnPageUpdated() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-page-update`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when page update.




---
url: /api/lynx-native-api/lynx-view-client/on-performance-event.md
---

# onPerformanceEvent

APISummary
Notify the client that a performance event has been sent. It will be called every time a performance event is generated, including but not limited to container initialization, engine rendering, rendering metrics update, etc.

## Syntax

### Android

```java
public void onPerformanceEvent(@NonNull PerformanceEntry entry);
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

### iOS

```objc
- (void)onPerformanceEvent:(nonnull LynxPerformanceEntry *)entry;
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

### Harmony

```typescript
public onPerformanceEvent(entry: PerformanceEntry): void;
```

#### Parameters

- `entry`: The [PerformanceEntry](/api/lynx-api/performance-api/performance-entry.md) about the performance event.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-performance-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Notify the client that a performance event has been sent. It will be called every time a performance event is generated, including but not limited to container initialization, engine rendering, rendering metrics update, etc.




---
url: /api/lynx-native-api/lynx-view-client/on-piper-invoked.md
---

# onPiperInvoked

APISummary
Called when JSBridge invoked.

## Syntax

### Android

```java
public void onPiperInvoked(Map<String, Object> info);
```

#### Parameters

- `info`: JSBridge's information. `url: String`: Lynx's url; `module-name: String`: module's name; `method-name: String`: method's name; `params: List<Object>`: (Optional) other necessary parameters.

### iOS

```objc
- (void)onPiperInvoked:(NSDictionary *)info;
```

#### Parameters

- `info`: Piper's information. `url: NSString`: Lynx's url; `module-name: NSString`: module's name; `method-name: NSString`: method's name; `params: NSArray`: (Optional) other necessary parameters.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-piper-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when JSBridge invoked.




---
url: /api/lynx-native-api/lynx-view-client/on-received-error.md
---

# onReceivedError

APISummary
Called when error received.

## Syntax

### Android

```java
public void onReceivedError(LynxError error);
```

#### Parameters

- `error`: The type and information of the error.

### Harmony

```typescript
public onReceivedError(error: LynxError): void;
```

#### Parameters

- `error`: The type and information of the error.

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnReceivedError(int error_code, const char* message) override;
};
```

#### Parameters

- `error_code`: The error code.
- `message`: The error message.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-java-error.md
---

# onReceivedJavaError

APISummary
Called when java error received.

## Syntax

### Android

```java
public void onReceivedJavaError(LynxError error);
```

#### Parameters

- `error`: The type and information of the error.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-java-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when java error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-js-error.md
---

# onReceivedJSError

APISummary
Called when JS error received.

## Syntax

### Android

```java
public void onReceivedJSError(LynxError jsError);
```

#### Parameters

- `jsError`: JS exception information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-js-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when JS error received.




---
url: /api/lynx-native-api/lynx-view-client/on-received-native-error.md
---

# onReceivedNativeError

APISummary
Called when C++ layer error received.

## Syntax

### Android

```java
public void onReceivedNativeError(LynxError nativeError);
```

#### Parameters

- `nativeError`: Native exception information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-received-native-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when C++ layer error received.




---
url: /api/lynx-native-api/lynx-view-client/on-report-component-info.md
---

# onReportComponentInfo

APISummary
Return the used component tagName.

## Syntax

### Android

```java
public void onReportComponentInfo(Set<String> mComponentSet);
```

#### Parameters

- `mComponentSet`: The set of component tagName.

### iOS

```objc
- (void)lynxView:(LynxView *)view didReportComponentInfo:(NSSet<NSString *> *)componentSet;
```

#### Parameters

- `view`: The LynxView instance.
- `componentSet`: The set of component tagName.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-report-component-info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Return the used component tagName.




---
url: /api/lynx-native-api/lynx-view-client/on-runtime-ready.md
---

# onRuntimeReady

APISummary
Called when JS environment preparation completed.

## Syntax

### Android

```java
public void onRuntimeReady();
```

:::note

- The callback is in an asynchronous thread.

:::

### iOS

```objc
- (void)lynxViewDidConstructJSRuntime:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

### Harmony

```typescript
public onRuntimeReady(): void;
```

### Desktop (C++)

```cpp
class YourViewClient : public lynx::pub::LynxViewClient {
 public:
  void OnRuntimeReady() override;
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-runtime-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Called when JS environment preparation completed.




---
url: /api/lynx-native-api/lynx-view-client/on-scroll-start.md
---

# onScrollStart

APISummary
Called when the UI start scrolling.

## Syntax

### Android

```java
public void onScrollStart(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-scroll-start`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when the UI start scrolling.




---
url: /api/lynx-native-api/lynx-view-client/on-scroll-stop.md
---

# onScrollStop

APISummary
Called when the UI finished scrolling.

## Syntax

### Android

```java
public void onScrollStop(ScrollInfo info);
```

#### Parameters

- `info`: Contains scroll parameters, including the instance of the scrolling view, and the front-end specified id and name.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-scroll-stop`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when the UI finished scrolling.




---
url: /api/lynx-native-api/lynx-view-client/on-tasm-finished-by-native.md
---

# onTASMFinishedByNative

APISummary
Called when native layout finish in ui or most\_on\_tasm mode, or diff finish in multi\_thread mode.

## Syntax

### Android

```java
public void onTASMFinishedByNative();
```

### iOS

```objc
- (void)lynxViewOnTasmFinishByNative:(LynxView *)view;
```

#### Parameters

- `view`: The LynxView instance.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-tasm-finished-by-native`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when native layout finish in ui or most_on_tasm mode, or diff finish in multi_thread mode.




---
url: /api/lynx-native-api/lynx-view-client/on-template-bundle-ready.md
---

# onTemplateBundleReady

APISummary
Provide a reusable TemplateBundle after template is decode.

## Syntax

### Android

```java
public void onTemplateBundleReady(@NonNull TemplateBundle bundle);
```

#### Parameters

- `bundle`: The recycled template bundle, it is nonnull but could be invalid.

:::note

- This callback is disabled by default, and you can enable it through the DUMP\_ELEMENT option or RECYCLE\_TEMPLATE\_BUNDLE option in LynxLoadMeta.

:::

### iOS

```objc
- (void)onTemplateBundleReady:(LynxTemplateBundle *)bundle;
```

#### Parameters

- `bundle`: the recycled template bundle, it is nonnull but could be invalid

:::note

- This callback is disabled by default, and you can enable it through the enableRecycleTemplateBundle option in LynxLoadMeta.

:::

### Harmony

```typescript
public onTemplateBundleReady(bundle: TemplateBundle): void;
```

#### Parameters

- `bundle`: The recycled template bundle, it is nonnull but could be invalid.

:::note

- This callback is disabled by default, and you can enable it through theDUMP\_ELEMENT option or RECYCLE\_TEMPLATE\_BUNDLE option in LynxLoadMeta.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-template-bundle-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Provide a reusable TemplateBundle after template is decode.




---
url: /api/lynx-native-api/lynx-view-client/on-update-data-without-change.md
---

# onUpdateDataWithoutChange

APISummary
If there is no need to update the UI after calling [`updateData`](/api/lynx-native-api/lynx-view/update-meta-data.md), this method is called back.

## Syntax

### Harmony

```typescript
public onUpdateDataWithoutChange(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-update-data-without-change`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** If there is no need to update the UI after calling updateData, this method is called back.




---
url: /api/lynx-native-api/lynx-view-client/on-update-perf-ready.md
---

# onUpdatePerfReady

APISummary
Performance data statistics callback after the interface update is completed.

## Syntax

### Android

```java
public void onUpdatePerfReady(LynxPerfMetric metric);
```

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

### iOS

```objc
- (void)lynxView:(LynxView *)view didReceiveUpdatePerf:(LynxPerformance *)perf;
```

#### Parameters

- `view`: The LynxView instance.

:::note

- The timing of the callback is not fixed due to differences in rendering threads, and should not be used as a starting point for any business side. The callback is in the main thread.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-view-client.on-update-perf-ready`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Performance data statistics callback after the interface update is completed.




---
url: /api/lynx-native-api/lynx-background-runtime.md
---

# LynxBackgroundRuntime

LynxBackgroundRuntime is Lynx's off-main-thread runtime. It executes script logic that does not directly affect screen pixel rendering, such as business data processing, networking, and Native Module calls. It sits at the same level as `LynxView`: `LynxView` renders UI, while `LynxBackgroundRuntime` runs non-rendering scripts.

## What It’s For

- Runs business logic that doesn’t render pixels
- Handles networking and Native Module calls off the UI thread
- Complements `LynxView` without interfering with rendering

## Core APIs

- [Evaluate Script](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#L1-1)
- [Evaluate Bundle Script](/api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md#L1-1)
- [Send Global Event](/api/lynx-native-api/lynx-background-runtime/send-global-event.md#L1-1)
- [Add Lifecycle Client](/api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md#L1-1) / [Remove Lifecycle Client](/api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md#L1-1)
- [Destroy](/api/lynx-native-api/lynx-background-runtime/destroy.md#L1-1)
- [Call JS Function](/api/lynx-native-api/lynx-background-runtime/call-js-function.md#L1-1)



---
url: /api/lynx-native-api/lynx-background-runtime/add-lynx-background-runtime-client.md
---

# addLynxBackgroundRuntimeClient

APISummary
Register lifecycle event listeners for `LynxBackgroundRuntime`.

## Syntax

### Android

```java
public void addLynxBackgroundRuntimeClient(LynxBackgroundRuntimeClient client);
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### iOS

```objc
- (void)addLifecycleClient:(nonnull id<LynxBackgroundRuntimeLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### Harmony

```ts
public addLifecycleClient(client: LynxBackgroundRuntimeClient): void;
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.add-lynx-background-runtime-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** register lifecycle observer for background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/call-js-function.md
---

# callJSFunction

APISummary
Invoke a JavaScript function from `LynxBackgroundRuntime`.

## Syntax

### Android

```java
public void callFunction(String module, String method, JavaOnlyArray arguments);
```

#### Parameters

- `module`: Target JS module name.
- `method`: Method name in the module.
- `arguments`: Arguments array for the function.

### iOS

```objc
- (void)callFunction:(nonnull NSString *)moduleName
          withMethod:(nonnull NSString *)methodName
          withParams:(nullable NSArray *)params;
```

#### Parameters

- `moduleName`: Target JS module name.
- `methodName`: Method name in the module.
- `params`: Parameters array for the function.

### Harmony

```ts
callJSFunction(module: string, method: string, params: Object[]): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.call-js-function`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** invoke js function from background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/destroy.md
---

# destroy

APISummary
Destroy `LynxBackgroundRuntime` and release all resources related to the runtime.

## Syntax

### Android

```java
public void destroy();
```

### iOS

rely on garbage collect.

### Harmony

rely on garbage collect.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.destroy`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** manually destroy background runtime instance




---
url: /api/lynx-native-api/lynx-background-runtime/evaluate-java-script.md
---

# evaluateJavaScript

APISummary
Run background script logic.

## Syntax

### Android

```java
public void evaluateJavaScript(String url, @NonNull String sources);
public void evaluateTemplateBundle(String url, @NonNull TemplateBundle bundle, @NonNull String js_file);
```

#### Parameters

- `url`: Unique identifier for the script.
- `sources`: Script content.
- `bundle`: Pre-parsed `TemplateBundle` containing the script.
- `js_file`: Related JS file name inside the bundle.

### iOS

```objc
- (void)evaluateJavaScript:(NSString *)url withSources:(NSString *)sources;
- (void)evaluateTemplateBundle:(NSString *)url
                   widthBundle:(LynxTemplateBundle *)bundle
                    withJSFile:(NSString *)jsFile;
```

#### Parameters

- `url`: Unique identifier for the script.
- `sources`: Script content.
- `bundle`: Pre-parsed `LynxTemplateBundle` containing the script.
- `jsFile`: Related JS file name inside the bundle.

### Harmony

```ts
evaluateJavaScript(url: string, sources: string): void;
evaluateBundleScript(url: string, bundle: TemplateBundle, jsFileName: string): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.evaluate-java-script`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** evaluate background runtime script




---
url: /api/lynx-native-api/lynx-background-runtime/remove-lynx-background-runtime-client.md
---

# removeLynxBackgroundRuntimeClient

APISummary
Remove lifecycle event listeners from `LynxBackgroundRuntime` (counterpart of `addLynxBackgroundRuntimeClient`).

## Syntax

### Android

```java
public void removeLynxBackgroundRuntimeClient(LynxBackgroundRuntimeClient client);
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### iOS

```objc
- (void)removeLifecycleClient:(nonnull id<LynxBackgroundRuntimeLifecycle>)lifecycleClient;
```

#### Parameters

- `lifecycleClient`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

### Harmony

```ts
public removeLifecycleClient(client: LynxBackgroundRuntimeClient): void;
```

#### Parameters

- `client`: The client implementation registered to the `LynxBackgroundRuntime` instance for receiving lifecycle callbacks.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.remove-lynx-background-runtime-client`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** remove lifecycle observer for background runtime




---
url: /api/lynx-native-api/lynx-background-runtime/send-global-event.md
---

# sendGlobalEvent

APISummary
Send a global event from `LynxBackgroundRuntime` to the frontend. The frontend can listen via `GlobalEventEmitter`.

## Syntax

### Android

```java
public void sendGlobalEvent(String name, JavaOnlyArray params);
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by the event.

### iOS

```objc
- (void)sendGlobalEvent:(nonnull NSString *)name withParams:(nullable NSArray *)params;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by the event.

### Harmony

```ts
runtime.sendGlobalEvent('eventName', []);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** send global event to js enviroment from background runtime




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-evaluate-java-script-end.md
---

# onEvaluateJavaScriptEnd

APISummary
Called when background script evaluation finishes.

## Syntax

### Android

```java
public void onEvaluateJavaScriptEnd(String url);
```

### iOS

```objc
- (void)runtime:(LynxBackgroundRuntime *)runtime didEvaluateJavaScriptEnd:(NSString *)url;
```

### Harmony

```ts
public onEvaluateJavaScriptEnd(url: string): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-evaluate-java-script-end`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when background script evaluation finished.




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-module-method-invoked.md
---

# onModuleMethodInvoked

APISummary
Called when a module method invocation is completed in the background runtime.

## Syntax

### Android

```java
public void onModuleMethodInvoked(String module, String method, int error_code);
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if the invocation failed.

### Harmony

```ts
public onModuleMethodInvoked(module: string, method: string, error_code: number): void;
```

#### Parameters

- `module`: Module name.
- `method`: Method name.
- `error_code`: Error code if the invocation failed.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-module-method-invoked`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when a module method invocation completed in background runtime.




---
url: /api/lynx-native-api/lynx-background-runtime-client/on-received-error.md
---

# onReceivedError

APISummary
Called when an error is received in the background runtime. The error may originate from JS or native code.

## Syntax

### Android

```java
public void onReceivedError(LynxError error);
```

#### Parameters

- `error`: Error information.

### iOS

```objc
- (void)runtime:(LynxBackgroundRuntime *)runtime didReceiveError:(NSError *)error;
```

#### Parameters

- `error`: Error information.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-background-runtime-client.on-received-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.1 | - |
| iOS | 3.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Called when an error is received in background runtime.




---
url: /api/lynx-native-api/lynx-context/send-global-event.md
---

# sendGlobalEvent

APISummary
Send global events to the front end through the client, and the front end can listen to the event through `GlobalEventEmitter`.

## Syntax

### Harmony

```typescript
sendGlobalEvent(name: string, params: Object[]): void;
```

#### Parameters

- `name`: Global event name.
- `params`: Parameters carried by global events.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.send-global-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 1.0 | - |
| iOS | 1.0 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** send global event to js enviroment




---
url: /api/lynx-native-api/lynx-context/set-extra-timing.md
---

# setExtraTiming

APISummary
This interface is used to supplement key performance data before loading the Lynx page, specifically including the following items from [`InitContainerEntry`](/api/lynx-api/performance-api/performance-entry/init-container-entry.md):

- Page open time (`openTime`)
- Timestamp for the start of preparing the [TemplateBundle](/api/lynx-native-api/template-bundle.md) (`prepareTemplateStart`)
- Timestamp for the end of preparing the TemplateBundle (`prepareTemplateEnd`)
- Timestamp for the start of [container](/guide/spec.md#container) initialization (`containerInitStart`)
- Timestamp for the end of container initialization (`containerInitEnd`)

Upon successfully updating all timestamps using this interface, the `InitContainerEntry` performance event will be triggered. Depending on the timing of the configuration, it may also trigger the calculation of `fcp`, `totalFcp`, `actualFmp`, and `totalActualFmp` metrics, along with dispatching new performance events for [`MetricFcpEntry`](/api/lynx-api/performance-api/performance-entry/metric-fcp-entry.md) and [`MetricActualFmpEntry`](/api/lynx-api/performance-api/performance-entry/metric-actual-fmp-entry.md).

:::caution
Timestamps within extraTiming cannot be overwritten, meaning that multiple calls to this interface attempting to repeatedly update a timestamp will yield no effect.
:::

## Syntax

### Harmony

```typescript
public setExtraTiming(extraTiming: LynxExtraTiming): void;
```

#### Parameters

- `extraTiming`: Used to supplement key performance data before loading the Lynx page.

The specific definition of `LynxExtraTiming` is as follows:

```typescript
export class LynxExtraTiming {
  public static readonly OPEN_TIME = 'openTime';
  public static readonly CONTAINER_INIT_START = 'containerInitStart';
  public static readonly CONTAINER_INIT_END = 'containerInitEnd';
  public static readonly PREPARE_TEMPLATE_START = 'prepareTemplateStart';
  public static readonly PREPARE_TEMPLATE_END = 'prepareTemplateEnd';

  public openTime: number = 0;
  public containerInitStart: number = 0;
  public containerInitEnd: number = 0;
  public prepareTemplateStart: number = 0;
  public prepareTemplateEnd: number = 0;
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.set-extra-timing`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.3 | - |
| iOS | 2.3 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** set extra timing from outside.




---
url: /api/lynx-native-api/lynx-context/update-font-scale.md
---

# updateFontScale

APISummary
Changing the font scaling ratio in client settings will automatically change the text size.

## Syntax

### Harmony

```typescript
updateFontScale(scale: number): void;
```

#### Parameters

- `scale`: Font scaling.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-font-scale`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** update font scale of lynxView




---
url: /api/lynx-native-api/lynx-context/update-meta-data.md
---

# updateMetaData

APISummary
Using [LynxUpdateMeta](/api/lynx-native-api/lynx-update-meta.md) to update `LynxView`, it is the main entrance for the client to update template data.

## Syntax

### Harmony

```typescript
updateMetaData(data: MetaData): void;
```

#### Parameters

- `data`: Lynx template update metadata, developers use this data structure to specify the optional data content of the update template.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-meta-data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.13 | - |
| iOS | 2.13 | - |
| HarmonyOS | 3.4 | - |
| Web | ✅ Yes | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** update lynx page by new data.




---
url: /api/lynx-native-api/lynx-context/update-viewport.md
---

# updateViewport

APISummary
The client updates the `LynxView` view size.

## Syntax

### Harmony

```typescript
public updateViewport(width: number, widthMode: number, height: number, heightMode: number): void;
```

#### Parameters

- `width`: Current `LynxView` width.
- `widthMode`: The measure mode for width. 0: Indefinite, 1: Definite, 2: AtMost.
- `height`: Current `LynxView` height.
- `heightMode`: The measure mode for height. 0: Indefinite, 1: Definite, 2: AtMost.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-context.update-viewport`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.1 | - |
| iOS | 2.1 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** update viewport of lynxView




---
url: /api/lynx-native-api/lynx-env.md
---

# LynxEnv

## LynxEnv

### [trimMemory](/api/lynx-native-api/lynx-env/trim-memory.md)

- [Syntax](/api/lynx-native-api/lynx-env/trim-memory.md#syntax)
- [Parameters](/api/lynx-native-api/lynx-env/trim-memory.md#parameters)
- [Compatibility](/api/lynx-native-api/lynx-env/trim-memory.md#compatibility)



---
url: /api/lynx-native-api/lynx-env/trim-memory.md
---

# trimMemory

APISummary
Dispatches a memory pressure signal to registered callbacks. Use this to notify Lynx to reclaim resources or apply degradation strategies when the system is under memory pressure.

## Syntax

### Android

```java
@AnyThread
public void trimMemory(@MemoryPressureLevel int pressure);
```

### iOS

```objc
- (void)trimMemory:(LynxMemoryPressureLevel)pressure;
```

### Harmony

```ts
public trimMemory(pressure: MemoryPressureLevel): void;
```

## Parameters

- `pressure`: Memory pressure level, one of `MemoryPressureLevel`.
  - `MEMORY_PRESSURE_LEVEL_NONE`: No problems, enough memory; typically not sent via callback.
  - `MEMORY_PRESSURE_LEVEL_MODERATE`: Free buffers that are cheap to re-allocate and not immediately needed.
  - `MEMORY_PRESSURE_LEVEL_CRITICAL`: Free all possible memory; otherwise the process may be killed by the system, incurring cold start cost.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-env.trim-memory`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |
| HarmonyOS | 3.8 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** dispatch memory pressure signal to registered callbacks




---
url: /api/lynx-native-api/lynx-extension-module.md
---

# LynxExtensionModule

APISummary
`LynxExtensionModule` is the Desktop-only extension entry in the public embedder API. It lets the host hook into `LynxView` and BTS runtime lifecycle, expose NAPI exports, schedule BTS tasks, observe VSync, and register native views.

:::info

This API is Desktop only. It is supported on macOS and Windows, and is not part of the Android, iOS, Harmony, or Web native API surfaces.

:::

## Quick Access

Register an extension module globally through `LynxEnv::RegisterExtensionModule(...)`:

```cpp title="register_extension_module.cc"
#include "lynx_env.h"
#include "lynx_extension_module.h"
#include "lynx_view.h"

class DemoExtensionModule : public lynx::pub::LynxExtensionModule {
 public:
  void OnRuntimeAttach(
      Napi::Env env,
      std::unique_ptr<lynx::pub::VSyncObserver> vsync_observer) override {
    vsync_observer_ = std::move(vsync_observer);
  }

 private:
  std::unique_ptr<lynx::pub::VSyncObserver> vsync_observer_;
};

void RegisterExtensionModule() {
  auto& env = lynx::pub::LynxEnv::GetInstance();
  env.RegisterExtensionModule("DemoExtensionModule",
                              &CreateDemoExtensionModule,
                              false,
                              nullptr);
}
```

## Lifecycle

`LynxExtensionModule` exposes lifecycle callbacks across the UI thread and BTS thread:

- `OnLynxViewCreate(...)`: called on the UI thread when a `LynxView` instance is created.
- `OnLynxViewDestroy()`: called on the UI thread before the `LynxView` instance is destroyed.
- `OnRuntimeInit()`: called on the UI thread when the BTS runtime instance is created.
- `OnRuntimeAttach(Napi::Env env, std::unique_ptr<VSyncObserver> vsync_observer)`: called on the BTS thread when the runtime is attached.
- `OnRuntimeReady(Napi::Env env, Napi::Value lynx, const char* url)`: called on the BTS thread when the runtime is ready.
- `OnRuntimeDetach()`: called on the BTS thread when the runtime is detached.
- `OnEnterForeground()`: called on the UI thread when the application enters foreground.
- `OnEnterBackground()`: called on the UI thread when the application enters background.
- `Destroy()`: called on the BTS thread before the extension module instance is released.

## Runtime Utilities

`LynxExtensionModule` also exposes Desktop runtime helpers:

- `PostTaskToRuntime(...)`: posts work to the BTS thread.
- `IsRunningTasksOnBTSThread()`: checks whether the current execution is already on the BTS thread.
- `SetNapiModuleCreator(...)`: installs the NAPI exports creator for the module.
- `SetNapiInstanceData(...)` / `GetNapiInstanceData(...)`: stores and reads keyed NAPI instance data.
- `Retain()` / `Release()`: adjusts the lifetime of the module instance.

`VSyncObserver`, received in `OnRuntimeAttach(...)`, provides:

- `RequestAnimationFrame(...)`
- `RequestBeforeAnimationFrame(...)`
- `RegisterAfterAnimationFrameListener(...)`

## Native View as Extension Capability

Native view capability belongs to the Desktop extension surface rather than a separate native API owner.

Use `LynxNativeView` when you need to embed a platform view or external texture inside the Lynx view tree. The C++ base class exposes these callbacks:

- `OnCreate()`
- `OnAttach()`
- `OnDetach()`
- `OnDestroy()`
- `OnLayoutChanged(...)`
- `OnPropertiesChanged(...)`
- `OnMotionEvent(...)`
- `OnFocusChanged(...)`
- `OnMethodInvoked(...)`

It also exposes helper methods such as:

- `TriggerEvent(...)`
- `RequestFocus()`
- `MarkDirty()`
- `PresentSurface(...)`
- `AcquireSurface(...)`
- `SwapBack()`

### Register Native View

You can register a native view in three common places:

- Globally through `LynxView::Builder::RegisterNativeView<T>(...)`
- Per view through `LynxView::RegisterNativeView<T>(...)`
- Inside an extension module during `OnLynxViewCreate(...)`

The extension-module pattern is useful when a native view should always be installed together with the extension itself. In practice, this registration is usually performed from `OnLynxViewCreate(...)`:

```cpp title="cef_extension_module.cc"
#include "lynx_view.h"

class CEFExtensionModule : public lynx::pub::LynxExtensionModule {
 public:
  void InstallNativeView(lynx::pub::LynxView& view) {
    view.RegisterNativeView<CEFWebView>("x-webview");
  }
};
```

A standalone native view implementation typically subclasses `LynxNativeView`:

```cpp title="fake_view.h"
#include "lynx_native_view.h"

class FakeView : public lynx::pub::LynxNativeView {
 public:
  bool OnCreate() override { return true; }

  void OnLayoutChanged(float left,
                       float top,
                       float width,
                       float height,
                       float pixel_ratio) override {
    lynx::pub::LynxValue detail(lynx::pub::LynxValue::kCreateAsMapTag);
    detail.SetProperty("width", lynx::pub::LynxValue(width));
    detail.SetProperty("height", lynx::pub::LynxValue(height));
    TriggerEvent("resize", std::move(detail));
  }

  void OnMethodInvoked(const char* method,
                       const lynx::pub::LynxValue& attrs,
                       std::function<void(int, lynx::pub::LynxValue&&)> callback) override {
    callback(kSuccess, lynx::pub::LynxValue(lynx::pub::LynxValue::kCreateAsNullTag));
  }
};
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-extension-module`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Desktop-only extension module entry for lifecycle hooks, NAPI binding, VSync, and native view registration.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/cancel.md
---

# cancel

APISummary
Cancel the request of the requiring resource.

## Syntax

### Android

```java
public void cancel(LynxResourceRequest request);
```

#### Parameters

- `request`: the requiring request.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
abstract cancel(request: LynxResourceRequest): void;
```

#### Parameters

- `request`: Request to be canceled.

### Desktop (C++)

Desktop public API cancels a resource fetch by request ID:

```cpp
virtual void Cancel(lynx_resource_request_id request_id);
```

#### Parameters

- `request_id`: The ID of the request to cancel.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.cancel`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Cancel the request of the requiring resource.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource-path.md
---

# fetchResourcePath

APISummary
`LynxEngine` internally calls this method to obtain the path of the common resource on the local disk, and the return result is required to be of `String` type.

## Syntax

### Android

```java
public abstract void fetchResourcePath(
    LynxResourceRequest request, LynxResourceCallback<String> callback);
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Path on the disk of the requiring resource.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchResourcePath:(nonnull LynxResourceRequest *)request
                           onComplete:(LynxGenericResourcePathCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Path on the disk of the requiring resource.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchResourcePath(request: LynxResourceRequest, callback: AsyncCallback<string>): void;
```

#### Parameters

- `request`: Request to obtain the path of the common resource on the local disk.
- `callback`: with path on the disk of the requiring resource.

### Desktop (C++)

```cpp
virtual void FetchResourcePath(
    std::shared_ptr<lynx::pub::LynxResourceRequest> request,
    std::shared_ptr<lynx::pub::LynxResourceResponse> response);
```

#### Parameters

- `request`: Request for the resource path being fetched.
- `response`: Response object to be populated by the host.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-resource-path`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** LynxEngine internally calls this method to obtain the path of the common resource on the local disk, and the return result is required to be of String type.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-resource.md
---

# fetchResource

APISummary
`LynxEngine` internally calls this method to obtain the general resource content, and the return result is required to be the resource content `byte[]` type.

## Syntax

### Android

```java
public abstract void fetchResource(
    LynxResourceRequest request, LynxResourceCallback<byte[]> callback);
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Contents of the requiring resource.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchResource:(nonnull LynxResourceRequest *)request
                       onComplete:(LynxGenericResourceCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring resource.
- `callback`: Contents of the requiring resource.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchResource(request: LynxResourceRequest, callback: AsyncCallback<ArrayBuffer>): void;
```

#### Parameters

- `request`: Request to obtain the general resource content.
- `callback`: Containing contents of the requiring resource.

### Desktop (C++)

```cpp
virtual void FetchResource(std::shared_ptr<lynx::pub::LynxResourceRequest> request,
                           std::shared_ptr<lynx::pub::LynxResourceResponse> response);
```

#### Parameters

- `request`: Request for the resource being fetched.
- `response`: Response object to be populated by the host.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-resource`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** LynxEngine internally calls this method to obtain the general resource content, and the return result is required to be the resource content byte[] type.




---
url: /api/lynx-native-api/lynx-generic-resource-fetcher/fetch-stream.md
---

# fetchStream

APISummary
`LynxEngine` internally calls this method to obtain resource content in a streaming manner.

## Syntax

### Android

```java
public void fetchStream(LynxResourceRequest request, StreamDelegate delegate);
```

#### Parameters

- `request`: Request for the requiring resource.
- `delegate`: Streaming of the requiring resource.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchStream:(nonnull LynxResourceRequest *)request
                     withStream:(nonnull id<LynxResourceStreamLoadDelegate>)delegate;
```

#### Parameters

- `request`: Request for the requiring resource.
- `delegate`: Streaming of the requiring resource.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
fetchStream(request: LynxResourceRequest, delegate: LynxStreamDelegate): void;
```

#### Parameters

- `request`: Request to obtain resource content in a streaming manner.
- `delegate`: streaming of the requiring resource.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-generic-resource-fetcher.fetch-stream`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain resource content in a streaming manner.




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/fetch-image.md
---

# fetchImage

APISummary
`LynxEngine` will use this method to obtain the bitmap information of the image, and the return content must be of `Closeable` type.

## Syntax

### Android

```java
public void fetchImage(LynxResourceRequest request, LynxResourceCallback<Closeable> callback);
```

#### Parameters

- `request`: Request for the resource.
- `callback`: Response with the needed drawable.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (dispatch_block_t)fetchUIImage:(LynxResourceRequest *_Nonnull)request
                      onComplete:(LynxMediaResourceCompletionBlock _Nonnull)response;
```

#### Parameters

- `request`: Request for the resource.
- `response`: Response with the needed drawable.

:::note

- This method is optional to be implemented.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.fetch-image`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** LynxEngine will use this method to obtain the bitmap information of the image, and the return content must be of Closeable type.




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/is-local-resource.md
---

# isLocalResource

APISummary
`LynxEngine` internally calls this method to determine whether the resource path exists on disk.

## Syntax

### Android

```java
public OptionalBool isLocalResource(String url);
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path and UNDEFINED if not sure.

:::note

- This method is optional to be implemented.

:::

### iOS

```objc
- (LynxResourceOptionalBool)isLocalResource:(NSURL *_Nonnull)url;
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path and UNDEFINED if not sure.

:::note

- This method is optional to be implemented.

:::

### Harmony

```typescript
isLocalResource(url: string): LynxOptionalBool;
```

#### Parameters

- `url`: Input path.

#### Return

- TRUE if is a local path, FALSE if not a local path, UNDEFINED if not sure.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.is-local-resource`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** LynxEngine internally calls this method to determine whether the resource path exists on disk.




---
url: /api/lynx-native-api/lynx-media-resource-fetcher/should-redirect-url.md
---

# shouldRedirectUrl

APISummary
`LynxEngine` redirects the image path by calling this method internally, and the return result is required to be of `String` type

## Syntax

### Android

```java
public abstract String shouldRedirectUrl(LynxResourceRequest request);
```

#### Parameters

- `request`: Request for the resource.
- `callback`: The target url.

:::note

- This method must be implemented.

:::

### iOS

```objc
- (NSString *_Nonnull)shouldRedirectUrl:(LynxResourceRequest *_Nonnull)request;
```

#### Parameters

- `request`: Request for the resource.
- `callback`: The target url.

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract shouldRedirectUrl(request: LynxResourceRequest): string;
```

#### Parameters

- `request`: Request to be redirected.

#### Return

- The target url.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-media-resource-fetcher.should-redirect-url`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** LynxEngine redirects the image path by calling this method internally, and the return result is required to be of String type.




---
url: /api/lynx-native-api/lynx-template-resource-fetcher/fetch-template.md
---

# fetchTemplate

APISummary
`LynxEngine` internally calls this method to obtain the contents of Bundle and Lazy Bundle. The returned result type can contain `byte[]` or `TemplateBundle`.

## Syntax

### Android

```java
public abstract void fetchTemplate(
    LynxResourceRequest request, LynxResourceCallback<TemplateProviderResult> callback);
```

#### Parameters

- `request`: Request for the requiring content file.
- `callback`: Response with the requiring content file: byteArray or TemplateBundle

:::note

- This method must be implemented.

:::

### iOS

```objc
- (void)fetchTemplate:(LynxResourceRequest *_Nonnull)request
           onComplete:(LynxTemplateResourceCompletionBlock _Nonnull)callback;
```

#### Parameters

- `request`: Request for the requiring content file.
- `callback`: Response with the requiring content file: byteArray or TemplateBundle

:::note

- This method must be implemented.

:::

### Harmony

```typescript
abstract fetchTemplate(request: LynxResourceRequest, callback: AsyncCallback<TemplateProviderResult>): void;
```

#### Parameters

- `request`: Request to obtain the contents of Bundle and Lazy Bundle
- `callback`: Response with the requiring content file in ArrayBuffer type.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.lynx-template-resource-fetcher.fetch-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** LynxEngine internally calls this method to obtain the contents of Bundle and Lazy Bundle. The returned result type can contain byte[] or TemplateBundle.




---
url: /api/lynx-native-api/template-bundle.md
---

# Overview

## TemplateBundle

### [fromTemplateAsyncWithOption](/api/lynx-native-api/template-bundle/from-template-async-with-option.md)

- [Syntax](/api/lynx-native-api/template-bundle/from-template-async-with-option.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/from-template-async-with-option.md#compatibility)

### [fromTemplateAsync](/api/lynx-native-api/template-bundle/from-template-async.md)

- [Syntax](/api/lynx-native-api/template-bundle/from-template-async.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/from-template-async.md#compatibility)

### [fromTemplate](/api/lynx-native-api/template-bundle/from-template.md)

- [Syntax](/api/lynx-native-api/template-bundle/from-template.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/from-template.md#compatibility)

### [getErrorMessage](/api/lynx-native-api/template-bundle/get-error-message.md)

- [Syntax](/api/lynx-native-api/template-bundle/get-error-message.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/get-error-message.md#compatibility)

### [getExtraInfo](/api/lynx-native-api/template-bundle/get-extra-info.md)

- [Syntax](/api/lynx-native-api/template-bundle/get-extra-info.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/get-extra-info.md#compatibility)

### [getTemplateSize](/api/lynx-native-api/template-bundle/get-template-size.md)

- [Syntax](/api/lynx-native-api/template-bundle/get-template-size.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/get-template-size.md#compatibility)

### [isElementBundleValid](/api/lynx-native-api/template-bundle/is-element-bundle-valid.md)

- [Syntax](/api/lynx-native-api/template-bundle/is-element-bundle-valid.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/is-element-bundle-valid.md#compatibility)

### [isValid](/api/lynx-native-api/template-bundle/is-valid.md)

- [Syntax](/api/lynx-native-api/template-bundle/is-valid.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/is-valid.md#compatibility)

### [postJsCacheGenerationTask](/api/lynx-native-api/template-bundle/post-js-cache-generation-task.md)

- [Syntax](/api/lynx-native-api/template-bundle/post-js-cache-generation-task.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/post-js-cache-generation-task.md#compatibility)

### [release](/api/lynx-native-api/template-bundle/release.md)

- [Syntax](/api/lynx-native-api/template-bundle/release.md#syntax)
- [Compatibility](/api/lynx-native-api/template-bundle/release.md#compatibility)



---
url: /api/lynx-native-api/template-bundle/from-template-async-with-option.md
---

# fromTemplateAsyncWithOption

APISummary
Asynchronously creates a TemplateBundle from a template binary data with options. This method avoids blocking the main thread.

## Syntax

### Harmony

```typescript
public static async fromTemplateAsyncWithOption(template: ArrayBuffer, option: TemplateBundleOption): Promise<TemplateBundle>;
```

#### Parameters

- `template`: The template binary content.
- `option`: The TemplateBundleOption object.

#### Return

- A promise that resolves with the new TemplateBundle object.

:::note

- Due to ArkTS being restricted to run on the app’s main thread, we provide an asynchronous TemplateBundle creation API to reduce blocking time from main-thread I/O operations. On other platforms, developers can decide whether to run on a background thread without requiring a special asynchronous API.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template-async-with-option`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.6 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Asynchronously creates a TemplateBundle from a template binary data with options. This method avoids blocking the main thread.




---
url: /api/lynx-native-api/template-bundle/from-template-async.md
---

# fromTemplateAsync

APISummary
Asynchronously creates a TemplateBundle from a template binary data. This method avoids blocking the main thread.

## Syntax

### Harmony

```typescript
public static async fromTemplateAsync(template: ArrayBuffer): Promise<TemplateBundle>;
```

#### Parameters

- `template`: ArrayBuffer, a buffer of template binary data.

#### Return

- A promise that resolves with a new TemplateBundle object.

:::note

- Due to ArkTS being restricted to run on the app’s main thread, we provide an asynchronous TemplateBundle creation API to reduce blocking time from main-thread I/O operations. On other platforms, developers can decide whether to run on a background thread without requiring a special asynchronous API.

:::

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template-async`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.6 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Asynchronously creates a TemplateBundle from a template binary data. This method avoids blocking the main thread.




---
url: /api/lynx-native-api/template-bundle/from-template.md
---

# fromTemplate

APISummary
Input Lynx template binary content and return the parsed `TemplateBundle` object.

## Syntax

### Android

```java
public static TemplateBundle fromTemplate(byte[] template);
```

#### Parameters

- `template`: Template binary content.

#### Return

- The `TemplateBundle` object.

:::note

- When the input `template` is `null`, this method returns `null` directly.
- When the input `template` is not a correct `Lynx` template data, an invalid `TemplateBundle` is returned.

:::

### iOS

```objc
- (instancetype _Nullable)initWithTemplate:(nonnull NSData *)tem;
```

#### Parameters

- `tem`: Template binary content.

#### Return

- The `TemplateBundle` object.

:::note

- When the input `tem` is not a correct `Lynx` template data, or is `nil`, an invalid `TemplateBundle` is returned

:::

### Harmony

```typescript
public static async fromTemplate(template: ArrayBuffer): Promise<TemplateBundle>;
```

#### Parameters

- `template`: Template binary content.

#### Return

- TemplateBundle in promise.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.from-template`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Input Lynx template binary content and return the parsed TemplateBundle object.




---
url: /api/lynx-native-api/template-bundle/get-error-message.md
---

# getErrorMessage

APISummary
When `TemplateBundle` is an invalid object, use this method to obtain the exception information that occurred during template parsing.

## Syntax

### Android

```java
public String getErrorMessage();
```

#### Return

- The exception information.

### iOS

```objc
- (NSString *_Nullable)errorMsg;
```

#### Return

- The exception information, if `nil` is returned, it proves that the `LynxTemplateBundle` is normal

### Harmony

```typescript
public getErrorMessage(): string;
```

#### Return

- The exception information during template parsing.

### Desktop (C++)

```cpp
std::string GetErrorMessage();
```

#### Return

- The parsing error message. An empty string means the bundle is valid.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-error-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** When TemplateBundle is an invalid object, use this method to obtain the exception information that occurred during template parsing.




---
url: /api/lynx-native-api/template-bundle/get-extra-info.md
---

# getExtraInfo

APISummary
Read the content of the `extraInfo` field configured in the `pageConfig` of the front-end template.

## Syntax

### Android

```java
public Map<String, Object> getExtraInfo();
```

#### Return

- When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `null`, else it returns the `extraInfo` field.

### iOS

```objc
- (NSDictionary *_Nullable)extraInfo;
```

#### Return

- When the front-end does not configure `extraInfo` or is called on an empty `TemplateBundle` object, it returns `nil`, else it returns the `extraInfo` field.

### Harmony

```typescript
public getExtraInfo(): Map<string, Object>;
```

#### Return

- When the front-end does not configure extraInfo or is called on an empty TemplateBundle object, it returns null.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-extra-info`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Read the content of the extraInfo field configured in the pageConfig of the front-end template.




---
url: /api/lynx-native-api/template-bundle/get-template-size.md
---

# getTemplateSize

APISummary
Get the size of current template.

## Syntax

### Harmony

```typescript
public getTemplateSize(): number;
```

#### Return

- Template size.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.get-template-size`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Get the size of current template.




---
url: /api/lynx-native-api/template-bundle/is-element-bundle-valid.md
---

# isElementBundleValid

APISummary
Whether the TemplateBundle contains a Valid ElementBundle.

## Syntax

### Android

```java
public boolean isElementBundleValid();
```

#### Return

- True if valid, else false.

### iOS

```objc
- (BOOL)isElementBundleValid;
```

#### Return

- True if the TemplateBundle contains a Valid ElementBundle, otherwise false.

### Harmony

```typescript
public isElementBundleValid(): boolean;
```

#### Return

- True if valid, else false.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.is-element-bundle-valid`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Whether the TemplateBundle contains a Valid ElementBundle.




---
url: /api/lynx-native-api/template-bundle/is-valid.md
---

# isValid

APISummary
Determines whether the current `TemplateBundle` object is valid.

## Syntax

### Android

```java
public boolean isValid();
```

#### Return

- `true` if the current `TemplateBundle` object is valid, else `false`.

### Desktop (C++)

```cpp
bool IsValid() const;
```

#### Return

- `true` if the current `LynxTemplateBundle` object is valid, else `false`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.is-valid`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Determines whether the current TemplateBundle object is valid.




---
url: /api/lynx-native-api/template-bundle/post-js-cache-generation-task.md
---

# postJsCacheGenerationTask

APISummary
Start a sub-thread task to generate the `js code cache` of the current template.

## Syntax

### Android

```java
public void postJsCacheGenerationTask(String bytecodeSourceUrl, boolean useV8);
```

#### Parameters

- `bytecodeSourceUrl`: The `url` of the current template.
- `useV8`: Whether to generate `V8 Code Cache`, otherwise generate `QuickJS Code Cache`.

### iOS

```objc
- (void)postJsCacheGenerationTask:(nonnull NSString *)bytecodeSourceUrl;
```

#### Parameters

- `bytecodeSourceUrl`: The source url of the template.

### Harmony

```typescript
public postJsCacheGenerationTask(bytecodeSourceUrl: string, useV8: boolean): void;
```

#### Parameters

- `bytecodeSourceUrl`: The url of the current template.
- `useV8`: Whether to generate V8 Code Cache, otherwise generate QuickJS Code Cache.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.post-js-cache-generation-task`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Start a sub-thread task to generate the js code cache of the current template.




---
url: /api/lynx-native-api/template-bundle/release.md
---

# release

APISummary
Release the `Native` memory held by the current `TemplateBundle` object. After executing the `release` method, the `TemplateBundle` will become the `inValid` state.

## Syntax

### Android

```java
public void release();
```

### Desktop (C++)

Desktop C++ API does not expose a standalone `release()` method. `LynxTemplateBundle` releases the underlying handle in its destructor:

```cpp
{
  lynx::pub::LynxTemplateBundle bundle(content, length, dtor, opaque);
}  // release happens in ~LynxTemplateBundle()
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-bundle.release`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Release the Native memory held by the current TemplateBundle object. After executing the release method, the TemplateBundle will become the inValid state.




---
url: /api/lynx-native-api/template-data/constructor.md
---

# constructor

APISummary
Input data in string, key-value or json format and return the parsed `TemplateData` object.

## Syntax

### Harmony

```typescript
constructor(input: string | Record<string, Object> | Object, processor: string);
```

#### Parameters

- `input`: String, key-value or json type data.
- `processor`: Data processor.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.constructor`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Input data in string, key-value or json format and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/data.md
---

# data

APISummary
Get the data in `TemplateData` object.

## Syntax

### Harmony

```typescript
data(): void;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.data`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Get the data in TemplateData object.




---
url: /api/lynx-native-api/template-data/from-map.md
---

# fromMap

APISummary
Input data in key-value format and return the parsed `TemplateData` object.

## Syntax

### Android

```java
public static TemplateData fromMap(Map<String, Object> data);
```

#### Parameters

- `data`: `Map` type data.

#### Return

- `TemplateData` constructed by `data`.

### iOS

```objc
- (instancetype)initWithDictionary:(NSDictionary *)dictionary;
```

#### Parameters

- `dictionary`: `NSDictionary*` type data.

#### Return

- `TemplateData` constructed by `data`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.from-map`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Input data in key-value format and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/from-string.md
---

# fromString

APISummary
Input data in json and return the parsed `TemplateData` object.

## Syntax

### Android

```java
public static TemplateData fromString(String json);
```

#### Parameters

- `json`: `String` type data in json format.

#### Return

- `TemplateData` constructed by `json`.

### iOS

```objc
- (instancetype)initWithJson:(NSString *)json;
```

#### Parameters

- `json`: `NSString*` type data in json format.

#### Return

- `TemplateData` constructed by `json`.

### Desktop (C++)

Desktop public API constructs `LynxTemplateData` directly from the JSON string:

```cpp
auto data = std::make_shared<lynx::pub::LynxTemplateData>(json);
```

#### Parameters

- `json`: The JSON string used to create the template data.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.from-string`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Input data in json and return the parsed TemplateData object.




---
url: /api/lynx-native-api/template-data/mark-state.md
---

# markState

APISummary
Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in [UpdateData](/api/lynx-native-api/lynx-view/update-meta-data.md), the corresponding dataProcessor will be found based on this name for data preprocessing.

## Syntax

### Android

```java
public void markState(String name);
```

#### Parameters

- `name`: Marked name.

### iOS

```objc
- (void)markState:(NSString *)name;
```

#### Parameters

- `name`: Marked name.

### Desktop (C++)

```cpp
void MarkState(const std::string& name);
```

#### Parameters

- `name`: The data processor name associated with the current `LynxTemplateData`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.mark-state`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** Mark the current TemplateData with the associated dataProcessor name. When this TemplateData is used in UpdateData, the corresponding dataProcessor will be found based on this name for data preprocessing.




---
url: /api/lynx-native-api/template-data/merge.md
---

# merge

APISummary
Merge the incoming data with the current data.

## Syntax

### Harmony

```typescript
merge(data: string | Record<string, Object> | Object): void;
```

#### Parameters

- `data`: Incoming data in string, key-value or json format.

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.template-data.merge`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | ❌ No | - |
| iOS | ❌ No | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | ❌ No | - |
| Clay Windows | ❌ No | - |

**Description:** Merge the incoming data with the current data.




---
url: /api/lynx-native-api/lynx-load-meta.md
---

# LynxLoadMeta

APISummary
`LynxLoadMeta` is the metadata structure used by `LynxView` to load templates. It will be used as the input parameter of [loadTemplate](/api/lynx-native-api/lynx-view/load-template.md). Users can use `LynxLoadMeta` to specify many parameters of loading templates, such as specifying template content, template initial data, and other additional configuration information;

## Android:

### Field

- `url: String `: Template file path;
- `binaryData: byte[]`: The binary file data of the template;
- `bundle: TemplateBundle`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data;
- `initialData: TemplateData`: Initial data specified by the client during the first screen loading process;
- `globalProps: TemplateData`: Global properties, which will be synchronized to the template after the template is loaded.
- `loadMode: LynxLoadMode`: Loading mode, the default value is `LynxLoadMode.NORMAL`.
- `loadOptions: EnumSet<LynxLoadOption>`: Additional configuration information when loading templates;
- `lynxViewConfig: Map<String, String>`: Page Config information passed in when loading the template.

:::info

url, binaryData, bundle are the required parameters for template loading. You can pass only one or all of them. The priority relationship is as follows:
bundle > binaryData > url

:::

:::info

loadOptions is additional configuration information when loading a template. Currently the following configuration items are supported:

- **RECYCLE\_TEMPLATE\_BUNDLE**: After LynxView uses url or binaryData to load the template, it supports returning a TemplateBundle to the calling business party through LynxViewClient;
- **DUMP\_ELEMENT**: When LynxView loads a Bundle, copy the ElementBundle to the TemplateBundle and pass it back through the LynxViewClient;

:::

:::info

loadMode is the loading mode of the template. Currently, the following configuration items are supported:

- **NORMAL**: Default loading mode.
- **PRE\_PAINTING**: Suspend JS events when loading the template. Events will be sent during update, and layout will be blocked until the update is complete.
- **PRE\_PAINTING\_DRAW**: Suspend JS events when loading the template. Events will be sent during update.

:::

### Construction

To construct a `LynxLoadMeta` object on the `Android` platform, you need to use `LynxLoadMeta.Builder`:

```java
LynxLoadMeta.Builder builder = new LynxLoadMeta.Builder();
builder.setUrl();
builder.setBinaryData();
builder.setTemplateBundle();
builder.setInitialData();
builder.setGlobalProps();
builder.setLoadMode();
builder.addLoadOption();
builder.setLynxViewConfig();
LynxLoadMeta meta = builder.build();
```

## iOS

### Field

- `url: NSString*`: Template file path;
- `binaryData: NSData*`: The binary file data of the template;
- `templateBundle: LynxTemplateBundle*`: [TemplateBundle](/api/lynx-native-api/template-bundle.md) object parsed in advance by the template's binary file data;
- `initialData: LynxTemplateData*`: Initial data specified by the client during the first screen loading process;
- `globalProps: LynxTemplateData*`: Global properties, which will be synchronized to the template after the template is loaded.
- `loadMode: LynxLoadMode`: Loading mode, the default value is `LynxLoadModeNormal`.
- `loadOption: LynxLoadOption`: Additional configuration information when loading templates;
- `lynxViewConfig: NSMutableDictionary<NSString*, id>*`: Page Config information passed in when loading the template.

:::info

url, binaryData, templateBundle are the required parameters for template loading. You can pass only one or all of them. The priority relationship is as follows:
templateBundle > binaryData > url

:::

:::info

loadOption is additional configuration information when loading a template. Currently the following configuration items are supported:

- **RECYCLE\_TEMPLATE\_BUNDLE**: After LynxView uses url or binaryData to load the template, it supports returning a TemplateBundle to the calling business party through LynxViewClient;
- **DUMP\_ELEMENT**: When LynxView loads a Bundle , copy the ElementBundle to the TemplateBundle and pass it back through the LynxViewClient;

:::

:::info

loadMode is the loading mode of the template. Currently, the following configuration items are supported:

- **LynxLoadModeNormal**: Default loading mode.
- **LynxLoadModePrePainting**: Suspend JS events when loading the template. Events will be sent during update, and layout will be blocked until the update is complete.

:::

### Construction

On the iOS platform, you can construct a LynxLoadMeta object as follows:

```objective-c
LynxLoadMeta* meta = [LynxLoadMeta init];
meta.url = @"";
meta.binaryData = nil;
meta.templateBundle = nil;
meta.initialData = nil;
meta.globalProps = nil;
meta.loadMode = LynxLoadModeNormal;
meta.loadOption = LynxLoadOptionDumpElement | LynxLoadOptionRecycleTemplateBundle;
meta.lynxViewConfig = nil;
```

## Desktop (C++)

Construct `LynxLoadMeta` with the default constructor and configure it through setters:

```cpp
auto meta = std::make_shared<lynx::pub::LynxLoadMeta>();
meta->SetUrl(url);
meta->SetBinaryData(bytes);
meta->SetTemplateBundle(bundle);
meta->SetInitialData(initial_data);
meta->SetGlobalProps(global_props);
```

Desktop public API follows the same precedence for template source selection:

`template_bundle > binary_data > url`



---
url: /api/lynx-native-api/lynx-update-meta.md
---

# LynxUpdateMeta

APISummary
LynxUpdateMeta is the metadata structure used by LynxView to update template data. It will serve as the input parameter for [UpdateData](/api/lynx-native-api/lynx-view/update-meta-data.md). Users can specify various parameters required for the update through LynxUpdateMeta, such as template data and globalProps, among others.

## Android:

### Field

LynxUpdateMeta has the following members:

- `updateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the Android platform, you need to use LynxUpdateMeta.Builder to construct a LynxUpdateMeta object:

```java
LynxUpdateMeta.Builder builder = new LynxUpdateMeta.Builder();
builder.setUpdatedData(data);
builder.setUpdatedGlobalProps(globalProps);
LynxUpdateMeta meta = builder.build();
```

## iOS

### Field

LynxUpdateMeta has the following members:

- `updateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the iOS platform, construct the LynxLoadMeta object as follows:

```objective-c
LynxUpdateMeta* meta = [LynxUpdateMeta init];
meta.data = nil;
meta.globalProps = nil;
```

## Harmony

### Field

MetaData has the following members:

- `templateData: TemplateData`: The content of the data to update the template;
- `globalProps: TemplateData`: The globalProps content for updating the template;

### Construction

On the HarmonyOS platform, construct the MetaData object as follows:

```typescript
metaData = new MetaData(
  new TemplateData('{"text":"TD"}'),
  new TemplateData({ "theme": "Light" }));
```

## Web

```ts
export type Cloneable<T = string | number | null | boolean | undefined> =
  | T
  | Record<string, T>
  | T[];

updateData(
  data: Cloneable,
  updateDataType: UpdateDataType,
  callback?: () => void,
): void;
updateGlobalProps(data: Cloneable): void;
```

#### Parameters

- `data`: Data to be updated, should be `structuredClone` compatible.

## Desktop (C++)

Construct `LynxUpdateMeta` with the default constructor and configure it through setters:

```cpp
auto meta = std::make_shared<lynx::pub::LynxUpdateMeta>();
meta->SetUpdateData(data);
meta->SetGlobalProps(global_props);
```



---
url: /api/lynx-native-api/lynx-service.md
---

# LynxService API

APISummary
## Introduction

Lynx Service provides Lynx Engine with host-specific capabilities, including image, log, and [FetchAPI](/guide/interaction/networking.md#fetch-api) capabilities.
Different hosts have specific requirements for their own image, log, and network libraries, so Lynx Engine opens up autonomous access capabilities for such scenarios through the LynxService API.

## Overall Design

Lynx Engine and Lynx Service adopt a dependency-separation design. In terms of the dependency relationship, Lynx Service depends on the LynxService API provided by Lynx Engine to implement itself, while Lynx Engine does not depend on LynxService. At runtime, Lynx Engine will search for the registered Lynx Service through the service lookup mechanism and call it via the LynxService API.

## LynxService API

The LynxService API is provided by Lynx Engine and is designed to specify the capabilities of LynxService. Lynx Service needs to correctly implement itself in accordance with the requirements of the LynxService API to ensure that Lynx Engine can properly use this basic capability.

## 1. Quick Access

Lynx provides a default implementation of Lynx Service, which can be directly [accessed](/guide/start/integrate-with-existing-apps.md)

## 2. Lynx Service Customization

If there are custom requirements, you can also quickly implement and register relevant content according to your own needs. The following will take log service as an example to introduce how to implement and register a custom Lynx Service:

### Interface Implementation

**iOS**

- 1. Implement `LynxServiceLogProtocol`
```objective-c title="YourLogService.h"
#import <Lynx/LynxService.h>
#import <Lynx/LynxServiceLogProtocol.h>

// Implement LynxServiceLogProtocol
@interface YourLogService : NSObject <LynxServiceLogProtocol>
@end
```
- 2. Use the `LynxServiceRegister` to achieve automatic registration.
- 3. Implement `serviceBizID` and `serviceScope`. These two methods have no practical significance and will be removed later.
- 4. Implement `serviceType`. It is required to return the type implemented by this Service. See LynxService.h for details.
- 5. (Recommended) Implement `sharedInstance` to make it a singleton class. Based on the current Lynx Service design, only one instance of a certain type of Service will be used globally. It is recommended to implement it as a singleton class.
- 6. Implement all the interfaces required by `LynxServiceLogProtocol`.
```objective-c title="YourLogService.mm"
#import "YourLogService.h"

[[maybe_unused]] void logWrite(unsigned int level, const char *tag, const char *format) {
  if (format == NULL) {
    return;
  }
  NSLog(@"[%s] %s", tag == NULL ? "" : tag, format);
}

// Use the LynxServiceRegister macro to achieve automatic registration
@LynxServiceRegister(LynxLogService);

// Implement LynxLogService
@implementation LynxLogService

// Irrelevant property, will be removed later
+ (NSString*)serviceBizID {
  return DEFAULT_LYNX_SERVICE;
}

// Irrelevant property, will be removed later
+ (LynxServiceScope)serviceScope {
  return LynxServiceScopeDefault;
}

// Return the corresponding service type for runtime lookup
+ (NSUInteger)serviceType {
  return kLynxServiceLog;
}

// Recommended: Implement as a singleton
+ (instancetype)sharedInstance {
  static dispatch_once_t onceToken;
  static YourLogService *logService;
  dispatch_once(&onceToken, ^{
    logService = [[YourLogService alloc] init];
  });
  return logService;
}

// Implement all the interfaces required by LynxServiceLogProtocol
- (void *)getWriteFunction {
  return (void *)logWrite;
}

@end
```


**Android**

Implement `ILynxLogService`:
```kotlin title="YourLogService.kt"
object YourLogService : ILynxLogService {
  private var logOutputChannel: LogOutputChannelType = LogOutputChannelType.Platform

  override fun logByPlatform(
    level: Int,
    tag: String,
    msg: String,
  ) {
    // Implemention
  }

  override fun isLogOutputByPlatform(): Boolean = logOutputChannel == LogOutputChannelType.Platform

  override fun getDefaultWriteFunction(): Long = 0

  override fun switchLogToSystem(enableSystemLog: Boolean) {}

  override fun getLogToSystemStatus(): Boolean = false
}
```


**Harmony**

Implement `ILynxLogService`:
```typescript title="YourLogService.ets"
import { ILynxLogService } from '@lynx/lynx';

export class YourLogService implements ILynxLogService {
  static instance = new YourLogService();

  logByPlatform(level: number, tag: string, message: string): void {
    console.log(`level: ${level} tag: ${tag} message: ${message}`);
  }

  isLogOutputByPlatform(): boolean {
    return true;
  }

  getDefaultWriteFunction(): number {
    return 0;
  }
}
```


**Desktop C++**

Implement a concrete Desktop service class. The following example uses `LynxHttpService`; `LynxSecurityService` and `LynxEventReporterService` follow the same pattern and override their own abstract entrypoints.
```cpp title="YourHttpService.h"
#include "lynx/platform/embedder/public/lynx_http_service.h"

class YourHttpService : public lynx::pub::LynxHttpService {
 public:
  void Request(std::shared_ptr<lynx::pub::LynxHttpRequest> request,
               std::shared_ptr<lynx::pub::LynxHttpResponse> response) override {
    response->SetStatusCode(200);
    response->SetStatusText("OK");
    response->Complete();
  }
};
```
Use the corresponding abstract class for each service type:
- `LynxHttpService`: override `Request(...)`
- `LynxSecurityService`: override `VerifyTASM(...)`
- `LynxEventReporterService`: override `OnEvent(...)`

### Service Register

**iOS**

Lynx Service has an automatic registration mechanism in iOS. In the implementation stage, the `LynxServiceRegister` macro has been used to complete the quick automatic registration.
If you use your own implementation of Lynx Service, please delete the [default implementation](/guide/start/integrate-with-existing-apps.md?platform=ios) provided by Lynx.
```diff title="Podfile" {1-5}
pod 'LynxService', '{versionJson.LYNX_VERSION}', :subspecs => [
      'Image',
-     'Log',
      'Http',
  ]
```


**Android**

Replace the implementation of log service in `LynxServiceCenter` in the [integration documentation](/guide/start/integrate-with-existing-apps.md?platform=android) with your implementation.
```diff
- LynxServiceCenter.inst().registerService(ILynxLogService::class.java, LynxLogService)
+ LynxServiceCenter.inst().registerService(ILynxLogService::class.java, YourLogService)
```
And delete related dependencies
```diff title="build.gradle"
dependencies {
-   // integrating log-service
-   implementation "engineer.lynx.test2:lynx-service-log:0.0.1"
}
```


**Harmony**

Replace the implementation of log service in `LynxServiceCenter` in the [integration documentation](/guide/start/integrate-with-existing-apps.md?platform=harmony) with your implementation.
```diff
- LynxServiceCenter.registerService(LynxServiceType.Log, LynxLogService.instance);
+ LynxServiceCenter.registerService(LynxServiceType.Log, YourLogService.instance);
```
And delete related dependencies
```diff title="oh-package.json5"
"dependencies": {
- "@lynx/lynx_log_service": "0.0.1",
}
```


**Desktop C++**

Register the implemented service through `LynxServiceCenter`:
```cpp
auto service = std::make_shared<YourHttpService>();
lynx::pub::LynxServiceCenter::GetInstance().RegisterService(service);
```
The registered service type is determined by the concrete service class:
- `LynxHttpService` -> `kServiceTypeHttp`
- `LynxSecurityService` -> `kServiceTypeSecurity`
- `LynxEventReporterService` -> `kServiceTypeEventReporter`


**Compatibility Table**
**Query:** `lynx-native-api.lynx-service.lynx-service`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.8 | - |
| iOS | 2.8 | - |
| HarmonyOS | 3.4 | - |
| Web | ❌ No | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** LynxService API




---
url: /api/lynx-native-api/trace-event.md
---

# TraceEvent

APISummary
`TraceEvent` is a performance instrumentation utility provided by Lynx. Developers can use TraceEvent to flexibly insert trace points in client-side code, recording the execution timing and duration of key functions, tasks, rendering processes, and more.

## Android

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```java
public static void beginSection(String category, String name)
public static void beginSection(String category, String name, Map<String, String> args)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args (optional)

Custom arguments for the trace event.

#### Examples

```java
TraceEvent.beginSection("render", "measure-layout");
// ... your code ...
TraceEvent.endSection("render", "measure-layout");

// With custom arguments
Map<String, String> args = new HashMap();
args.put("component", "Image");
args.put("size", "large");
TraceEvent.beginSection("render", "draw-image", args);
// ... your code ...
TraceEvent.endSection("render", "draw-image");
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```java
public static void endSection(String category, String name)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### Examples

```java
TraceEvent.beginSection("logic", "parse-data");
// ... your code ...
TraceEvent.endSection("logic", "parse-data");
```

### instant

Marks an instant trace event.

```java
public static void instant(String category, String name)
public static void instant(String category, String name, Map<String, String> args)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```java
TraceEvent.instant("network", "request-started");

// With custom arguments
Map<String, String> args = new HashMap<>();
args.put("url", "https://example.com");
args.put("method", "GET");
TraceEvent.instant("network", "request-finished", args);
```

## iOS

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```objective-c
+ (void)beginSection:(NSString *)category withName:(NSString *)name
+ (void)beginSection:(NSString *)category withName:(NSString *)name debugInfo:(NSDictionary *)args
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```objective-c
[LynxTraceEvent beginSection:@"render" withName:@"measure-layout"];
// ... your code ...
[LynxTraceEvent endSection:@"render" withName:@"measure-layout"];

// With custom arguments
[LynxTraceEvent beginSection:@"render" withName:@"draw-image" debugInfo:@{@"component": @"Image", @"size": @"large"}];
// ... your code ...
[LynxTraceEvent endSection:@"render" withName:@"draw-image"];
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```objective-c
+ (void)endSection:(NSString *)category withName:(NSString *)name
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### Examples

```objective-c
[LynxTraceEvent beginSection:@"logic" withName:@"parse-data"];
// ... your code ...
[LynxTraceEvent endSection:@"logic" withName:@"parse-data"];
```

### instant

Marks an instant trace event.

```java
+ (void)instant:(NSString *)category withName:(NSString *)name
+ (void)instant:(NSString *)category withName:(NSString *)name debugInfo:(NSDictionary *)args
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```objective-c
[LynxTraceEvent instant:@"network" withName:@"request-started"];
// With custom arguments
[LynxTraceEvent instant:@"network" withName:@"request-finished" debugInfo:@{@"url": @"https://example.com", @"method": @"GET"}];
```

## Harmony

### beginSection

Marks the start of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```javascript
static void beginSection(traceCategory: TraceCategory, name: string, args?: Record<string, string>)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

```javascript
export enum TraceCategory {
  Lynx = 'lynx',
  Vitals = 'vitals',
  Other = 'other'
}
```

##### name

The name of the trace event.

#### args (optional)

Custom arguments for the trace event.

#### Examples

```javascript
TraceEvent.beginSection(TraceCategory.Other, "measure-layout");
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "measure-layout");

// With custom arguments
const args: Record<string, string> = {
  "src": "https://example.com",
  "size": "large"
}
TraceEvent.beginSection(TraceCategory.Other, "draw-image", args);
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "draw-image");
```

### endSection

Marks the end of a [trace event](https://perfetto.dev/docs/instrumentation/track-events).

```javascript
static void endSection(traceCategory: TraceCategory, name: string)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

```javascript
export enum TraceCategory {
  Lynx = 'lynx',
  Vitals = 'vitals',
  Other = 'other'
}
```

##### name

The name of the trace event.

#### Examples

```javascript
TraceEvent.beginSection(TraceCategory.Other, "parse-data");
// ... your code ...
TraceEvent.endSection(TraceCategory.Other, "parse-data");
```

### instant

Marks an instant trace event.

```javascript
static instant(traceCategory: TraceCategory, name: string, args?: Record<string, string>)
```

#### Parameters

##### category

The [category](https://perfetto.dev/docs/instrumentation/track-events#category-configuration) of the trace event.

##### name

The name of the trace event.

#### args(optional)

Custom arguments for the trace event.

#### Examples

```javascript
TraceEvent.instant(TraceCategory.Other, "request-started");

// With custom arguments
const args: Record<string, string> = {
  "url": "https://example.com",
  "method": "GET"
}
TraceEvent.instant(TraceCategory.Other, "request-finished", args);
```

## Desktop (C API)

Desktop public embedder API exposes trace helpers through C API macros.

### beginSection

Marks the start of a trace section. It must be paired with `LYNX_CAPI_TRACE_END` using the same category and name.

```c
LYNX_CAPI_TRACE_BEGIN(category, name);
```

### endSection

Marks the end of a trace section.

```c
LYNX_CAPI_TRACE_END(category, name);
```

### instant

Records an instant trace event.

```c
LYNX_CAPI_TRACE_INSTANT(category, name);
```

### counter

Records a counter trace event.

```c
LYNX_CAPI_TRACE_COUNTER(category, name, value, incremental);
```

#### Examples

```c
void DecodeImage() {
  LYNX_CAPI_TRACE_BEGIN("image", "DecodeImage");
  // ... your code ...
  LYNX_CAPI_TRACE_END("image", "DecodeImage");
}

LYNX_CAPI_TRACE_INSTANT("network", "RequestStarted");
LYNX_CAPI_TRACE_COUNTER("cache", "EntryCount", 42, false);
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-native-api.trace-event`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |

**Description:** TraceEvent




---
url: /api/lynx-devtool-native-api/cdp-event-listener.md
---

# CDPEventListener

APISummary
A **protocol (or interface)** used to receive [CDP](https://chromedevtools.github.io/devtools-protocol/) **Event** messages sent by DevTool.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
@protocol CDPEventListener <NSObject>

@required
- (void)onEvent:(nonnull NSString *)event;

@end
```

### Android

```java title="CDPEventListener.java"
public interface CDPEventListener {
  void onEvent(String event);
}
```

### Parameters

- `event`: A JSON string containing the CDP Event content.

## Data Format

| Field  | Type   | Description                                                                                  |
| :----- | :----- | :------------------------------------------------------------------------------------------- |
| method | string | Event name, please refer to [CDP](https://chromedevtools.github.io/devtools-protocol/)       |
| params | object | Event parameters, please refer to [CDP](https://chromedevtools.github.io/devtools-protocol/) |

For example, the data for [`Page.screencastFrame`](https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-screencastFrame) is as follows:

```json
{
  "method": "Page.screencastFrame",
  "params": {
    "data": "...",
    "metadata": {
      "deviceHeight": 200.0,
      "deviceWidth": 100.0,
      "offsetTop": 0.0,
      "pageScaleFactor": 1.0,
      "scrollOffsetX": 0.0,
      "scrollOffsetY": 0.0
    }
  }
}
```

## Usage Example

### Steps

1. [Implement `CDPEventListener`](#syntax).
2. [Get the `LynxBaseInspectorOwner` instance](/api/lynx-devtool-native-api/lynx-base-inspector-owner.md#get-the-lynxbaseinspectorowner-instance).
3. Call the [`addCDPEventListener`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md) method to add the message listener.

### Code Example

The following example adds a CDP Event listener named `TestListener` and sends a `Page.startScreencast` message via `invokeCDPFromSDK` to enable screen capture functionality.

As a result, the `TestCDPEventListener` will receive `Page.screencastFrame` message.

#### iOS

```objective-c title="TestCDPEventListener.h" {1-3}
#import <Lynx/LynxBaseInspectorOwner.h>

@interface TestCDPEventListener : NSObject <CDPEventListener>

@property(nonatomic, readonly, nonnull) NSString *name;

- (instancetype)initWithName:(NSString * _Nonnull )name;

@end
```

```objective-c title="TestCDPEventListener.m" {12-14}
#import "TestCDPEventListener.h"

@implementation TestCDPEventListener

- (instancetype)initWithName:(NSString *)name {
  if (self = [super init]) {
    _name = name;
  }
  return self;
}

- (void)onEvent:(nonnull NSString *)event {
  NSLog(@"onEvent: %@", event);
}

@end
```

```objective-c title="ViewController.m" {2-4,11,15-21,24-38,51-53}
#import <Lynx/LynxView.h>
#import <Lynx/LynxBaseInspectorOwner.h>

#import "TestCDPEventListener.h"

@interface LynxViewLifecycleClient : NSObject <LynxViewLifecycle>
@property(nonatomic, weak) LynxView* lynxView;
@end

@implementation LynxViewLifecycleClient {
  TestCDPEventListener* _listener;
}

- (void)lynxView:(LynxView *)view didLoadFinishedWithUrl:(NSString *)url {
  [self addCDPEventListener:@"TestListener"];
  __weak __typeof(self) weakSelf = self;
  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(10 * NSEC_PER_SEC)),
                 dispatch_get_main_queue(), ^{
                   __strong __typeof(weakSelf) strongSelf = weakSelf;
                   [strongSelf removeCDPEventListener:@"TestListener"];
                 });
}

- (void)addCDPEventListener:(NSString *)name {
  __strong LynxView* view = self.lynxView;
  id<LynxBaseInspectorOwner> owner = [view baseInspectorOwner];
  _listener = [[TestCDPEventListener alloc] initWithName:name];
  [owner addCDPEventListener:name withListener:_listener];
  NSString *method = @"{\"id\":1,\"method\":\"Page.startScreencast\",\"params\":{\"format\":\"jpeg\",\"mode\":\"fullscreen\"}}";
  [owner invokeCDPFromSDK:method withCallback:^(NSString *result){
  }];
}

- (void)removeCDPEventListener:(NSString *)name {
  __strong LynxView* view = self.lynxView;
  id<LynxBaseInspectorOwner> owner = [view baseInspectorOwner];
  [owner removeCDPEventListener:name];
}

@end

@implementation ViewController {
  LynxViewLifecycleClient *_client;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  _client = [LynxViewLifecycleClient new];
  _client.lynxView = lynxView;
  [lynxView addLifecycleClient:_client];
}

@end
```

#### Android

```java title="TestCDPEventListener.java" {3,5,17-19}
import android.util.Log;

import com.lynx.devtoolwrapper.CDPEventListener;

public class TestCDPEventListener implements CDPEventListener {
  private final String name;

  public TestCDPEventListener(String name) {
    this.name = name;
  }

  public String getName() {
    return name;
  }

  @Override
  public void onEvent(String event) {
    Log.i("TestCDPEventListener", "onEvent: " + event);
  }
}
```

```java title="MainActivity.java" {4,11,18,21,26-44}
import android.os.Handler;
import android.os.Looper;

import com.lynx.devtoolwrapper.LynxBaseInspectorOwner;
import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewClient;

import java.lang.ref.WeakReference;

public class MainActivity extends Activity {
  private TestCDPEventListener mTestCDPEventListener = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...

    lynxView.addLynxViewClient(new LynxViewClient() {
      @Override
      public void onLoadSuccess() {
        addCDPEventListener(lynxView, "TestListener");
      }
    });
  }

  private void addCDPEventListener(LynxView lynxView, String name) {
    LynxBaseInspectorOwner owner = lynxView.getBaseInspectorOwner();
    if (owner == null) {
      return;
    }
    mTestCDPEventListener = new TestCDPEventListener(name);
    owner.addCDPEventListener(name, mTestCDPEventListener);

    String method = "{\"id\":1,\"method\":\"Page.startScreencast\",\"params\":{\"format\":\"jpeg\",\"mode\":\"fullscreen\"}}";
    owner.invokeCDPFromSDK(method, result -> {
    });

    Handler mainHandler = new Handler(Looper.getMainLooper());
    WeakReference<LynxBaseInspectorOwner> weakOwner = new WeakReference<>(owner);
    mainHandler.postDelayed(() -> {
      LynxBaseInspectorOwner strongOwner = weakOwner.get();
      strongOwner.removeCDPEventListener(name);
    }, 10000);
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.cdp-event-listener`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |

**Description:** CDPEventListener




---
url: /api/lynx-devtool-native-api/cdp-result-callback.md
---

# CDPResultCallback

APISummary
A callback for receiving the asynchronous result from [`invokeCDPFromSDK`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md).

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
typedef void (^CDPResultCallback)(NSString *result);
```

### Android

```java title="CDPResultCallback.java"
public interface CDPResultCallback {
  void onResult(String result);
}
```

### Parameters

- `result`: A JSON string containing the CDP Method result.

## Return Data Format

A JSON-formatted string.

| Field  | Type   | Description                                                                                                                                                                      |
| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id     | number | Message ID, which is consistent with the value passed in [`invokeCDPFromSDK`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#request-data-format) |
| result | object | Method return value, please refer to [CDP](https://chromedevtools.github.io/devtools-protocol/)                                                                                  |

For example, the return data for [`DOM.getDocument`](https://chromedevtools.github.io/devtools-protocol/tot/DOM/#method-getDocument) is as follows:

```json
{
  "id" : 1,
  "result" : {
    "root" : {
      "attributes" : [],
      "backendNodeId" : 11,
      "childNodeCount" : 1,
      "children" : [
         ...
      ],
      "localName" : "",
      "nodeId" : 11,
      "nodeName" : "#document",
      "nodeType" : 9,
      "nodeValue" : ""
   }
}
```

## Usage Example

Please refer to [`invokeCDPFromSDK`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.cdp-result-callback`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |

**Description:** CDPResultCallback




---
url: /api/lynx-devtool-native-api/customized-message.md
---

# CustomizedMessage

APISummary
Encapsulates the debugging message to be sent.

To learn how to send debugging messages, please refer to [`sendMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md).

## Syntax

### iOS

```objective-c title="CustomizedMessage.h"
@interface CustomizedMessage : NSObject

@property(nonatomic, readwrite) NSString *type;
@property(nonatomic, readwrite) NSString *data;

@end
```

### Android

```java title="CustomizedMessage.java"
public class CustomizedMessage {
  public CustomizedMessage(String type, String data);
}
```

### Parameters

- `type`: The type of message to send, such as [CDP](https://chromedevtools.github.io/devtools-protocol/) or other custom message types.
- `data`: The message data to send.

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.customized-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | ❌ No | - |

**Description:** CustomizedMessage




---
url: /api/lynx-devtool-native-api/global-props-updated-observer.md
---

# GlobalPropsUpdatedObserver

APISummary
A **protocol (or interface)** used to receive updates to GlobalProps.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
@protocol GlobalPropsUpdatedObserver <NSObject>

- (void)onGlobalPropsUpdated:(NSDictionary *)props;

@end
```

### Android

```java title="GlobalPropsObserver.java"
public interface GlobalPropsObserver {
  void onGlobalPropsUpdated(Map globalProps);
}
```

### Parameters

- `globalProps`: The updated GlobalProps, containing key-value pairs for all properties.

## Usage Example

### Implementation Steps

1. [Implement `GlobalPropsUpdatedObserver`](#syntax).
2. [Get the `LynxBaseInspectorOwner` instance](/api/lynx-devtool-native-api/lynx-base-inspector-owner.md#get-the-lynxbaseinspectorowner-instance).
3. [Register `GlobalPropsUpdatedObserver`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md).

### Code Example

#### iOS

```objective-c title="TestGlobalPropsUpdatedObserver.h" {1,3}
#import <Lynx/LynxBaseInspectorOwner.h>

@interface TestGlobalPropsUpdatedObserver : NSObject <GlobalPropsUpdatedObserver>
@end
```

```objective-c title="TestGlobalPropsUpdatedObserver.m" {5-7}
#import "TestGlobalPropsUpdatedObserver.h"

@implementation TestGlobalPropsUpdatedObserver

- (void)onGlobalPropsUpdated:(NSDictionary *)props {
  NSLog(@"onGlobalPropsUpdated: %@", props);
}

@end
```

```objective-c title="ViewController.m" {2-4,13-18}
#import <Lynx/LynxView.h>
#import <Lynx/LynxBaseInspectorOwner.h>

#import "TestGlobalPropsUpdatedObserver.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView updateGlobalPropsWithDictionary:@{@"key1": @"value1"}];
  id<LynxBaseInspectorOwner> owner = lynxView.baseInspectorOwner;
  TestGlobalPropsUpdatedObserver* observer =
      [[TestGlobalPropsUpdatedObserver alloc] init];
  [owner setGlobalPropsUpdatedObserver:observer];
  [lynxView updateGlobalPropsWithDictionary:@{@"key2": @"value2"}];
}

@end
```

#### Android

```java title="MainActivity.java" {3-4,16,19-37}
import android.util.Log;

import com.lynx.devtoolwrapper.GlobalPropsObserver;
import com.lynx.devtoolwrapper.LynxBaseInspectorOwner;

import java.util.HashMap;
import java.util.Map;

public class MainActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...

    registerGlobalPropsUpdatedObserver(lynxView);
  }

  private void registerGlobalPropsUpdatedObserver(LynxView lynxView) {
    LynxBaseInspectorOwner owner = lynxView.getBaseInspectorOwner();
    if (owner == null) {
      return;
    }
    lynxView.updateGlobalProps(new HashMap<String, Object>() {{
      put("key1", "value1");
    }});
    GlobalPropsObserver observer = new GlobalPropsObserver() {
      @Override
      public void onGlobalPropsUpdated(Map globalProps) {
        Log.i("MainActivity", "onGlobalPropsUpdated: " + globalProps.toString());
      }
    };
    owner.registerGlobalPropsUpdatedObserver(observer);
    lynxView.updateGlobalProps(new HashMap<String, Object>() {{
      put("key2", "value2");
    }});
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.global-props-updated-observer`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |

**Description:** GlobalPropsUpdatedObserver




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner.md
---

# LynxBaseInspectorOwner

APISummary
`LynxBaseInspectorOwner` exposes a set of debugging-related public APIs for each `LynxView` instance, enabling developers to customize or extend its built-in debugging capabilities.

## Get the `LynxBaseInspectorOwner` Instance

### iOS

```objective-c title="LynxView.h"
@property(nonatomic, readonly, nullable) id<LynxBaseInspectorOwner> baseInspectorOwner;
```

### Android

```java title="LynxView.java"
public LynxBaseInspectorOwner getBaseInspectorOwner();
```

### Harmony

```ts title="LynxContext.ets"
public getBaseInspectorOwner(): LynxBaseInspectorOwner | null;
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.LynxBaseInspectorOwner`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.5 | - |

**Description:** getBaseInspectorOwner




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md
---

# addCDPEventListener

APISummary
Adds a listener for [CDP](https://chromedevtools.github.io/devtools-protocol/) **Event** messages.

This can be used with the [`invokeCDPFromSDK`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md) method to listen for CDP messages sent from DevTool.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)addCDPEventListener:(nonnull NSString *)name
               withListener:(nonnull id<CDPEventListener>)listener;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void addCDPEventListener(final String name, final CDPEventListener listener);
```

### Parameters

- `name`: A unique identifier for the listener, used for subsequent [removal](/api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md).
- `listener`: An object that implements [`CDPEventListener`](/api/lynx-devtool-native-api/cdp-event-listener.md) to receive Event messages.

:::warning

1. DevTool only holds a weak reference to `CDPEventListener`. Developers need to manage its lifecycle.
2. Multiple listeners can be set by calling this method multiple times, but if a listener with the same name is set, the previous one will be overwritten.

:::

## Usage Example

Please refer to [`CDPEventListener`](/api/lynx-devtool-native-api/cdp-event-listener.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.add-cdp-event-listener`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |

**Description:** addCDPEventListener




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md
---

# getConsoleObject

APISummary
For Object type console messages, this method can be used to retrieve its detailed information.

To learn how to obtain this data, please refer to [`LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md).

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)getConsoleObject:(NSString *_Nonnull)objectId
           needStringify:(BOOL)stringify
           resultHandler:(void (^_Nonnull)(NSString *_Nonnull detail))handler;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void getConsoleObject(String objectId, boolean needStringify, Callback callback);
```

### Harmony

```ts title="LynxBaseInspectorOwner.ets"
getConsoleObject(objectId: string, needStringify: boolean, callback: (detail: string) => void): void;
```

### Parameters

- `objectId`: The unique identifier of the Object to be retrieved. Please refer to [`objectId`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#argument).
- `stringify` / `needStringify`: Whether the Object needs to be serialized into a string.
  - If `true`, it is equivalent to calling the `JSON.stringify` method.
  - If `false`, it returns only **the top-level properties of the Object (non-recursive)**. If a property's value is another Object, only its basic information is returned. You must call this method again with the new `objectId` to retrieve its internal properties.
- `handler` / `callback`: A callback that receives the result as a single String parameter.

## Data Format

All data is in the form of a JSON formatted string.

- If `needStringify` is `true`: Returns the **complete** serialized JSON string of the Object.
- If `needStringify` is `false`: Returns **the top-level properties of the Object (non-recursive)**. It is an array, and the format of each element is as follows:

  | Field | Type                                                                                 | Description    |
  | :---- | :----------------------------------------------------------------------------------- | :------------- |
  | name  | string                                                                               | Property name  |
  | value | [argument](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#argument) | Property value |

### Example

Please refer to [`LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#example).

## Usage Example

Please refer to [`LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.get-console-object`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.5 | - |

**Description:** getConsoleObject




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md
---

# invokeCDPFromSDK

APISummary
Sends a [CDP](https://chromedevtools.github.io/devtools-protocol/) **Method** to DevTool and asynchronously receives the result.

This can be used simultaneously with the [DevTool desktop application](/guide/devtool.md#running-the-devtool-desktop-application-on-a-development-device) without interfering with each other.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)invokeCDPFromSDK:(NSString *)msg withCallback:(CDPResultCallback)callback;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void invokeCDPFromSDK(final String cdpMsg, final CDPResultCallback callback);
```

### Parameters

- `msg` / `cdpMsg`: The message to send, a JSON string formatted as a CDP Method.
- `callback`: A callback that conforms to the [`CDPResultCallback`](/api/lynx-devtool-native-api/cdp-result-callback.md) definition, used to receive the result.

## Request Data Format

A JSON-formatted string.

| Field  | Type   | Description                                                                                   |
| :----- | :----- | :-------------------------------------------------------------------------------------------- |
| id     | number | Message ID                                                                                    |
| method | string | Method name, please refer to [CDP](https://chromedevtools.github.io/devtools-protocol/)       |
| params | object | Method parameters, please refer to [CDP](https://chromedevtools.github.io/devtools-protocol/) |

For example, the request data for [`DOM.getDocument`](https://chromedevtools.github.io/devtools-protocol/tot/DOM/#method-getDocument) is as follows:

```json
{
  "id": 1,
  "method": "DOM.getDocument",
  "params": {}
}
```

## Usage Example

### Implementation Steps

1. [Implement `CDPResultCallback`](/api/lynx-devtool-native-api/cdp-result-callback.md).
2. [Get the `LynxBaseInspectorOwner` instance](/api/lynx-devtool-native-api/lynx-base-inspector-owner.md#get-the-lynxbaseinspectorowner-instance).
3. Call the [`invokeCDPFromSDK`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/invoke-cdp-from-sdk.md#syntax) method to send the message.

### Code Example

The following example code demonstrates the complete process of calling the `DOM.getDocument` CDP Method after the `LynxView` has successfully loaded.

#### iOS

```objective-c title="ViewController.m" {2,11,14-21,34-36}
#import <Lynx/LynxView.h>
#import <Lynx/LynxBaseInspectorOwner.h>

@interface LynxViewLifecycleClient : NSObject <LynxViewLifecycle>
@property(nonatomic, weak) LynxView* lynxView;
@end

@implementation LynxViewLifecycleClient

- (void)lynxView:(LynxView *)view didLoadFinishedWithUrl:(NSString *)url {
  [self invokeCDPMethod];
}

- (void)invokeCDPMethod {
  __strong LynxView* view = self.lynxView;
  id<LynxBaseInspectorOwner> owner = [view baseInspectorOwner];
  NSString *method = @"{\"id\":1,\"method\":\"DOM.getDocument\",\"params\":{}}";
  [owner invokeCDPFromSDK:method withCallback:^(NSString* result){
           NSLog(@"CDPResultCallback: %@", result);
         }];
}

@end

@implementation ViewController {
  LynxViewLifecycleClient *_client;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  _client = [LynxViewLifecycleClient new];
  _client.lynxView = lynxView;
  [lynxView addLifecycleClient:_client];
}

@end
```

#### Android

```java title="MainActivity.java" {3-4,15,18,23-35}
import android.util.Log;

import com.lynx.devtoolwrapper.CDPResultCallback;
import com.lynx.devtoolwrapper.LynxBaseInspectorOwner;
import com.lynx.tasm.LynxView;
import com.lynx.tasm.LynxViewClient;

public class MainActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...

    lynxView.addLynxViewClient(new LynxViewClient() {
      @Override
      public void onLoadSuccess() {
        invokeCDPMethod(lynxView);
      }
    });
  }

  private void invokeCDPMethod(LynxView lynxView) {
    LynxBaseInspectorOwner owner = lynxView.getBaseInspectorOwner();
    if (owner == null) {
      return;
    }
    String method = "{\"id\":1,\"method\":\"DOM.getDocument\",\"params\":{}}";
    owner.invokeCDPFromSDK(method, new CDPResultCallback() {
      @Override
      public void onResult(String result) {
        Log.i("MainActivity", "CDPResultCallback: " + result);
      }
    });
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.invoke-cdp-from-sdk`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |

**Description:** invokeCDPFromSDK




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/reload.md
---

# reload

APISummary
Reloads the current page, or loads a new template to replace the current page.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)reloadLynxView:(BOOL)ignoreCache;
- (void)reloadLynxView:(BOOL)ignoreCache
          withTemplate:(nullable NSString *)templateBin
         fromFragments:(BOOL)fromFragments
              withSize:(int32_t)size;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void reload(boolean ignoreCache);
void reload(boolean ignoreCache, String templateBin, boolean fromTemplateFragments, int templateSize);
```

### Parameters

- `ignoreCache`: Whether to ignore the cache. If `true`, rendering-related caches will be cleared.
- `templateBin`: A Base64-encoded Lynx template string (nullable or empty).
  - **When calling the first `reload` method, or when this parameter is `null` or an empty string**: The page's original template is reloaded.
  - **When this parameter is a valid Base64 string**: The new template contained in the string is loaded, which can be used for redirection.
- `fromFragments` / `fromTemplateFragments`: Whether to load the template file in fragments.
  - **For internal use only.** External calls should always set this to `false`.
- `size` / `templateSize`: When `fromFragments` is `true`, specifies the total size of the template file in bytes.
  - **For internal use only.** External calls should always set this to `0`.

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.reload`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |

**Description:** reload




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/remove-cdp-event-listener.md
---

# removeCDPEventListener

APISummary
Removes a listener for [CDP](https://chromedevtools.github.io/devtools-protocol/) **Event** messages.

This method is the counterpart to [`addCDPEventListener`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md). You should call it to remove the listener when you no longer need to listen for messages.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)removeCDPEventListener:(nonnull NSString *)name;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void removeCDPEventListener(final String name);
```

### Parameters

- `name`: The unique identifier of the listener, consistent with the `name` passed in [`addCDPEventListener`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/add-cdp-event-listener.md#parameters).

## Usage Example

Please refer to [`CDPEventListener`](/api/lynx-devtool-native-api/cdp-event-listener.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.remove-cdp-event-listener`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.5 | - |
| iOS | 3.5 | - |

**Description:** removeCDPEventListener




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md
---

# sendMessage

APISummary
Sends a debugging message of a specified type to the communication peer (e.g., the [DevTool Desktop Application](/guide/devtool.md#run-lynx-devtool-desktop-application)).

It works with the [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md) method to enable two-way communication.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwnerNG.h"
- (void)sendMessage:(nonnull CustomizedMessage *)message;
```

#### Parameters

- `message`: The message to send, of type [`CustomizedMessage`](/api/lynx-devtool-native-api/customized-message.md).

### Android

```java title="LynxBaseInspectorOwnerNG.java"
void sendMessage(CustomizedMessage message);
```

#### Parameters

- `message`: The message to send, of type [`CustomizedMessage`](/api/lynx-devtool-native-api/customized-message.md).

### Harmony

```ts title="LynxBaseInspectorOwner.ets"
sendMessage(type: string, message: string): void;
```

#### Parameters

- `type`: The type of message to send, such as [CDP](https://chromedevtools.github.io/devtools-protocol/) or other custom message types.
- `message`: The message data to send.

## Usage Example

Please refer to [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.send-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.8 | - |

**Description:** sendMessage




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/set-global-props-updated-observer.md
---

# setGlobalPropsUpdatedObserver

APISummary
Registers an observer for GlobalProps to listen for updates.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)setGlobalPropsUpdatedObserver:(id<GlobalPropsUpdatedObserver>)observer;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void registerGlobalPropsUpdatedObserver(GlobalPropsObserver observer);
```

### Parameters

- `observer`: An object that implements [`GlobalPropsUpdatedObserver`](/api/lynx-devtool-native-api/global-props-updated-observer.md).

## Usage Example

For an example, see [`GlobalPropsUpdatedObserver`](/api/lynx-devtool-native-api/global-props-updated-observer.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.set-global-props-updated-observer`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.8 | - |
| iOS | 3.8 | - |

**Description:** setGlobalPropsUpdatedObserver




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md
---

# setLynxInspectorConsoleDelegate

APISummary
Registers a console listener for a `LynxView` instance to listen for all console messages from that instance.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwner.h"
- (void)setLynxInspectorConsoleDelegate:(id _Nonnull)delegate;
```

### Android

```java title="LynxBaseInspectorOwner.java"
void setLynxInspectorConsoleDelegate(Object delegate);
```

### Harmony

```ts title="LynxBaseInspectorOwner.ets"
setLynxInspectorConsoleDelegate(delegate: LynxInspectorConsoleDelegate): void;
```

### Parameters

- `delegate`: An object that implements [`LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#syntax).

## Usage Example

Please refer to [`LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.set-lynx-inspector-console-delegate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.5 | - |

**Description:** setLynxInspectorConsoleDelegate




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md
---

# subscribeMessage

APISummary
Registers a handler for a specified debugging message type to receive and process messages of that type.

It works with the [`sendMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/send-message.md) method to enable two-way communication with the message sender (e.g., the [DevTool Desktop Application](/guide/devtool.md#run-lynx-devtool-desktop-application)).

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwnerNG.h"
- (void)subscribeMessage:(nonnull NSString *)type withHandler:(nonnull id<MessageHandler>)handler;
```

### Android

```java title="LynxBaseInspectorOwnerNG.java"
void subscribeMessage(String type, MessageHandler handler);
```

### Harmony

```ts title="LynxBaseInspectorOwner.ets"
subscribeMessage(type: string, handler: MessageHandler): void;
```

### Parameters

- `type`: The type of message to subscribe to, such as [CDP](https://chromedevtools.github.io/devtools-protocol/) or other custom message types.
- `handler`: An object that implements [`MessageHandler`](/api/lynx-devtool-native-api/message-handler.md) to receive debugging messages.

:::warning
DevTool only holds a weak reference to the `MessageHandler` object. Developers need to manage its lifecycle.
:::

## Usage Example

### Implementation Steps

1. [Implement `MessageHandler`](/api/lynx-devtool-native-api/message-handler.md) to process incoming debugging messages.
2. [Get the `LynxBaseInspectorOwner` instance](/api/lynx-devtool-native-api/lynx-base-inspector-owner.md#get-the-lynxbaseinspectorowner-instance). On iOS and Android, it needs to be cast to the `LynxBaseInspectorOwnerNG` type.
3. Call the [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#syntax) method to subscribe to debugging messages of the specified type.

### Code Example

The following example code subscribes to CDP messages. When a [`Page.enable`](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-enable) message is received, it sends a [`Log.entryAdded`](https://chromedevtools.github.io/devtools-protocol/tot/Log/#event-entryAdded) message with the content `Hello, Lynx DevTool!`.

As a result, this log will be displayed in the [Console](/guide/devtool/panels/console-panel.md) panel of the [DevTool Desktop Application](/guide/devtool.md#run-lynx-devtool-desktop-application).

![Subscribe Message](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/devtool-native-api-subscribe-message.png)
#### iOS

```objective-c title="TestMessageHandler.h" {1,3}
#import <Lynx/LynxBaseInspectorOwnerNG.h>

@interface TestMessageHandler : NSObject <MessageHandler>

- (instancetype)initWithInspectorOwner:(id<LynxBaseInspectorOwnerNG>)owner;

@end
```

```objective-c title="TestMessageHandler.m" {2,18-50}
#import <UIKit/UIKit.h>
#import <Lynx/CustomizedMessage.h>

#import "TestMessageHandler.h"

@implementation TestMessageHandler {
  __weak id<LynxBaseInspectorOwnerNG> _owner;
}

- (instancetype)initWithInspectorOwner:(id<LynxBaseInspectorOwnerNG>)owner {
  self = [super init];
  if (self) {
    _owner = owner;
  }
  return self;
}

- (void)onMessage:(nonnull NSString *)message {
  NSData *data = [message dataUsingEncoding:NSUTF8StringEncoding];
  NSDictionary *dic = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];

  if ([[dic objectForKey:@"method"] isEqualToString:@"Page.enable"]) {
    id<LynxBaseInspectorOwnerNG> strongOwner = _owner;
    if (!strongOwner) {
      return;
    }

    long long timestamp = (long long)([[NSDate date] timeIntervalSince1970] * 1000);
    NSDictionary *logJSON = @{
      @"method": @"Log.entryAdded",
      @"params": @{
        @"entry": @{
          @"level": @"info",
          @"source": @"javascript",
          @"text": @"Hello, Lynx DevTool!",
          @"timestamp": @(timestamp)
        }
      }
    };

    NSData *logData = [NSJSONSerialization dataWithJSONObject:logJSON options:0 error:nil];
    NSString *logString = [[NSString alloc] initWithData:logData encoding:NSUTF8StringEncoding];
    if (logString) {
      CustomizedMessage *customizedMessage = [[CustomizedMessage alloc] init];
      customizedMessage.type = @"CDP";
      customizedMessage.data = logString;
      [strongOwner sendMessage:customizedMessage];
    }
  }
}

@end
```

```objective-c title="ViewController.m" {2-4,7,15-23}
#import <Lynx/LynxView.h>
#import <Lynx/LynxBaseInspectorOwner.h>

#import "TestMessageHandler.h"

@implementation ViewController {
  TestMessageHandler *_handler;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  id<LynxBaseInspectorOwnerNG> owner = (id<LynxBaseInspectorOwnerNG>)lynxView.baseInspectorOwner;
  _handler = [[TestMessageHandler alloc] initWithInspectorOwner:owner];
  [owner subscribeMessage:@"CDP" withHandler:_handler];
  __weak id<LynxBaseInspectorOwnerNG> weakOwner = owner;
  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(10 * NSEC_PER_SEC)),
                 dispatch_get_main_queue(), ^{
                   id<LynxBaseInspectorOwnerNG> strongOwner = weakOwner;
                   [strongOwner unsubscribeMessage:@"CDP"];
                 });
}

@end
```

#### Android

```java title="TestMessageHandler.java" {1-3,10,18-40}
import com.lynx.devtoolwrapper.CustomizedMessage;
import com.lynx.devtoolwrapper.LynxBaseInspectorOwnerNG;
import com.lynx.devtoolwrapper.MessageHandler;

import java.lang.ref.WeakReference;

import org.json.JSONException;
import org.json.JSONObject;

public class TestMessageHandler implements MessageHandler {
  private final WeakReference<LynxBaseInspectorOwnerNG> mOwner;

  public TestMessageHandler(LynxBaseInspectorOwnerNG owner) {
    mOwner = new WeakReference<>(owner);
  }

  @Override
  public void onMessage(String message) {
    try {
      JSONObject jsonObject = new JSONObject(message);
      String method = jsonObject.getString("method");
      if ("Page.enable".equals(method)) {
        LynxBaseInspectorOwnerNG owner = mOwner.get();
        if (owner == null) {
          return;
        }
        JSONObject logJSON = new JSONObject();
        logJSON.put("method", "Log.entryAdded");
        logJSON.put("params", new JSONObject().put("entry", new JSONObject()
            .put("level", "info")
            .put("source", "javascript")
            .put("text", "Hello, Lynx DevTool!")
            .put("timestamp", System.currentTimeMillis())));
        CustomizedMessage customizedMessage = new CustomizedMessage("CDP", logJSON.toString());
        owner.sendMessage(customizedMessage);
      }
    } catch (JSONException e) {
      // ...
    }
  }
}
```

```java title="MainActivity.java" {4,9,16,19-32}
import android.os.Handler;
import android.os.Looper;

import com.lynx.devtoolwrapper.LynxBaseInspectorOwnerNG;

import java.lang.ref.WeakReference;

public class MainActivity extends Activity {
  private TestMessageHandler mTestMessageHandler = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...

    subscribeCDPMessage(lynxView);
  }

  private void subscribeCDPMessage(LynxView lynxView) {
    LynxBaseInspectorOwnerNG owner = (LynxBaseInspectorOwnerNG) lynxView.getBaseInspectorOwner();
    if (owner == null) {
      return;
    }
    mTestMessageHandler = new TestMessageHandler(owner);
    owner.subscribeMessage("CDP", mTestMessageHandler);
    Handler mainHandler = new Handler(Looper.getMainLooper());
    WeakReference<LynxBaseInspectorOwnerNG> weakOwner = new WeakReference<>(owner);
    mainHandler.postDelayed(() -> {
      LynxBaseInspectorOwnerNG strongOwner = weakOwner.get();
      strongOwner.unsubscribeMessage("CDP");
    }, 10000);
  }
}
```

#### Harmony

```ts title="TestMessageHandler.ets" {1,19,26-46}
import { LynxBaseInspectorOwner, MessageHandler } from '@lynx/lynx';

interface LogEntry {
  level: string;
  source: string;
  text: string;
  timestamp: number;
}

interface LogParams {
  entry: LogEntry;
}

interface LogMessage {
  method: string;
  params: LogParams;
}

export class TestMessageHandler implements MessageHandler {
  private owner: WeakRef<LynxBaseInspectorOwner>;

  constructor(owner: LynxBaseInspectorOwner) {
    this.owner = new WeakRef(owner);
  }

  public onMessage(msg: string): void {
    let json: object = JSON.parse(msg);
    if (json['method'] === 'Page.enable') {
      let owner = this.owner.deref();
      if (!owner) {
        return;
      }
      let log: LogMessage = {
        method: 'Log.entryAdded',
        params: {
          entry: {
            level: 'info',
            source: 'javascript',
            text: 'Hello, Lynx DevTool!',
            timestamp: Date.now(),
          },
        },
      };
      owner.sendMessage('CDP', JSON.stringify(log));
    }
  }
}
```

```ts title=Index.ets" {2,8,15-24}
import { LynxView, LynxContext } from '@lynx/lynx';
import { TestMessageHandler } from './TestMessageHandler'

@Entry
@Component
struct Index {
  // ...
  private handler?: TestMessageHandler;

  build() {
    Column() {
      LynxView({
        // ...
        onCreate: (context: LynxContext) => {
          let owner = context?.getBaseInspectorOwner();
          if (owner) {
            this.handler = new TestMessageHandler(owner);
            owner.subscribeMessage('CDP', this.handler);
            let weakOwner = new WeakRef(owner);
            setTimeout(() => {
              let owner = weakOwner.deref();
              owner?.unsubscribeMessage('CDP');
            }, 10000);
          }
        }
      }).width('100%').height('100%');
    }
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.subscribe-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.8 | - |

**Description:** subscribeMessage




---
url: /api/lynx-devtool-native-api/lynx-base-inspector-owner/unsubscribe-message.md
---

# unsubscribeMessage

APISummary
Unsubscribes from debugging messages of a specified type.

This method is the counterpart to [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md). You should call it to unsubscribe when you no longer need to receive a certain type of messages.

## Syntax

### iOS

```objective-c title="LynxBaseInspectorOwnerNG.h"
- (void)unsubscribeMessage:(nonnull NSString *)type;
```

### Android

```java title="LynxBaseInspectorOwnerNG.java"
void unsubscribeMessage(String type);
```

### Harmony

```ts title="LynxBaseInspectorOwner.ets"
unsubscribeMessage(type: string): void;
```

### Parameters

- `type`: The type of message to unsubscribe from.

## Usage Example

Please refer to [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md#usage-example).

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-base-inspector-owner.unsubscribe-message`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.8 | - |

**Description:** unsubscribeMessage




---
url: /api/lynx-devtool-native-api/lynx-devtool-utils.md
---

# Overview

## LynxDevToolUtils

### [setDevToolLibraryLoader](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md)

- [Syntax](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md#syntax)
- [Compatibility](/api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md#compatibility)



---
url: /api/lynx-devtool-native-api/lynx-devtool-utils/set-devtool-library-loader.md
---

# setDevToolLibraryLoader

APISummary
Sets a custom library loader for DevTool, used to load the dynamic libraries (e.g., `liblynxdevtool.so`) required by DevTool at runtime.

If this method is not called, DevTool will use the default library loader.

## Syntax

### Android

```java title="LynxDevToolUtils.java"
static public void setDevToolLibraryLoader(INativeLibraryLoader loader);
```

#### Parameters

- `loader`: An instance of a custom library loader that implements the `INativeLibraryLoader` interface.

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-devtool-utils.set-devtool-library-loader`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | ❌ No | - |
| HarmonyOS | ❌ No | - |

**Description:** setDevToolLibraryLoader




---
url: /api/lynx-devtool-native-api/lynx-inspector-console-delegate.md
---

# LynxInspectorConsoleDelegate

APISummary
A **protocol (or interface)** used to receive all console messages from a `LynxView` instance.

:::info
Currently, it only supports getting BTS console messages when using the PrimJS engine.
:::

## Syntax

Implement `LynxInspectorConsoleDelegate` protocol (or interface) and receive console messages through the `onConsoleMessage` method.

### iOS

```objective-c title="LynxInspectorConsoleDelegate.h"
@protocol LynxInspectorConsoleDelegate <NSObject>

- (void)onConsoleMessage:(NSString *)msg;

@end
```

### Android

```java title="LynxInspectorConsoleDelegate.java"
public interface LynxInspectorConsoleDelegate {
  void onConsoleMessage(String msg);
}
```

### Harmony

```ts title="LynxInspectorConsoleDelegate.ets"
export interface LynxInspectorConsoleDelegate {
  onConsoleMessage: (msg: string) => void;
}
```

## Data Format

All data is in the form of a JSON formatted string.

For Object type data, only the basic information of the Object is included. You can use [`getConsoleObject`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md) to get more detailed data.

### onConsoleMessage

| Field | Type                                                                                         | Description                                                            |
| :---- | :------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
| type  | string                                                                                       | The log type, such as `log`, `debug`, `info`, `error`, `warning`, etc. |
| args  | array\[[argument](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#argument)] | The log arguments, an array where each element is an argument object.  |

### argument

| Field       | Type   | Description                                                                                                                                |
| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| type        | string | The argument type, such as `string`, `number`, `boolean`, `object`, `function`, `undefined`, etc.                                          |
| subtype     | string | Optional field, the subtype of the argument, such as `array`, `null`, `error`, etc. This is specified only for arguments of type `object`. |
| objectId    | string | Optional field, the unique identifier when the argument is an Object type.                                                                 |
| description | string | Optional field, a preview or description of the argument.                                                                                  |
| value       | any    | Optional field, the value of the argument.                                                                                                 |

### Example

```ts
let testObj = { a: 1, b: 'test', c: true, d: undefined, e: null, f: { g: 2 } };
console.log('test object: ', testObj);
```

The code above will trigger the `onConsoleMessage` event, and the event data is as follows:

```json
"{\"type\":\"log\",\"args\":[{\"value\":\"test object: \",\"type\":\"string\"},{\"type\":\"object\",\"objectId\":\"546729222512\",\"className\":\"Object\",\"description\":\"Object\"}]}"
```

Take the `objectId` field from the second argument and call the [`getConsoleObject`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md) method.

When `needStringify` is `false`, the returned data is as follows:

```json
"[{\"name\":\"a\",\"value\":{\"description\":\"1\",\"value\":1,\"type\":\"number\"}},{\"name\":\"b\",\"value\":{\"value\":\"test\",\"type\":\"string\"}},{\"name\":\"c\",\"value\":{\"value\":true,\"type\":\"boolean\"}},{\"name\":\"d\",\"value\":{\"type\":\"undefined\"}},{\"name\":\"e\",\"value\":{\"subtype\":\"null\",\"value\":null,\"type\":\"object\"}},{\"name\":\"f\",\"value\":{\"type\":\"object\",\"objectId\":\"546729222592\",\"className\":\"Object\",\"description\":\"Object\"}},{\"name\":\"__proto__\",\"value\":{\"type\":\"object\",\"objectId\":\"546824040688\",\"className\":\"Object\",\"description\":\"Object\"}}]"
```

When `needStringify` is `true`, the returned data is as follows:

```json
"{\n\t\"a\": 1,\n\t\"b\": \"test\",\n\t\"c\": true,\n\t\"e\": null,\n\t\"f\": {\n\t\t\"g\": 2\n\t}\n}"
```

## Usage Example

### Implementation Steps

1. [Implement `LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-inspector-console-delegate.md#syntax).
2. [Get the `LynxBaseInspectorOwner` instance](/api/lynx-devtool-native-api/lynx-base-inspector-owner.md#get-the-lynxbaseinspectorowner-instance).
3. [Register `LynxInspectorConsoleDelegate`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/set-lynx-inspector-console-delegate.md).
4. [Get detailed Object information](/api/lynx-devtool-native-api/lynx-base-inspector-owner/get-console-object.md).

### Code Example

#### iOS

```objective-c title="TestConsoleDelegate.h" {2-5}
#import <Foundation/Foundation.h>
#import <Lynx/LynxBaseInspectorOwner.h>
#import <Lynx/LynxInspectorConsoleDelegate.h>

@interface TestConsoleDelegate : NSObject <LynxInspectorConsoleDelegate>

- (instancetype)initWithInspectorOwner:(id<LynxBaseInspectorOwner>)owner;

@end
```

```objective-c title="TestConsoleDelegate.m" {15-38}
#import "TestConsoleDelegate.h"

@implementation TestConsoleDelegate {
  __weak id<LynxBaseInspectorOwner> _owner;
}

- (instancetype)initWithInspectorOwner:(id<LynxBaseInspectorOwner>)owner {
  self = [super init];
  if (self) {
    _owner = owner;
  }
  return self;
}

- (void)onConsoleMessage:(NSString *)msg {
  NSLog(@"onConsoleMessage: %@", msg);
  NSData *data = [msg dataUsingEncoding:NSUTF8StringEncoding];
  NSDictionary *dic = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
  for (NSDictionary *item in [dic objectForKey:@"args"]) {
    if ([item objectForKey:@"type"] && [[item objectForKey:@"type"] isEqualToString:@"object"]) {
      NSString *objectId = [item objectForKey:@"objectId"];
      id<LynxBaseInspectorOwner> strongOwner = _owner;
      if (!strongOwner) {
        break;
      }
      [strongOwner getConsoleObject:objectId
                      needStringify:NO
                      resultHandler:^(NSString *detail) {
                        NSLog(@"getConsoleObject: %@", detail);
                      }];
      [strongOwner getConsoleObject:objectId
                      needStringify:YES
                      resultHandler:^(NSString *detail) {
                        NSLog(@"getConsoleObject: %@", detail);
                      }];
    }
  }
}

@end
```

```objective-c title="ViewController.m" {2-4,13-16}
#import <Lynx/LynxView.h>
#import <Lynx/LynxBaseInspectorOwner.h>

#import "TestConsoleDelegate.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  id<LynxBaseInspectorOwner> owner = lynxView.baseInspectorOwner;
  TestConsoleDelegate* delegate =
      [[TestConsoleDelegate alloc] initWithInspectorOwner:owner];
  [owner setLynxInspectorConsoleDelegate:delegate];
}

@end
```

#### Android

```java title="TestConsoleDelegate.java" {4-5,12,20-63}
import android.os.Handler;
import android.os.Looper;
import android.util.Log;
import com.lynx.devtool.LynxInspectorConsoleDelegate;
import com.lynx.devtoolwrapper.LynxBaseInspectorOwner;
import com.lynx.react.bridge.Callback;
import java.lang.ref.WeakReference;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class TestConsoleDelegate implements LynxInspectorConsoleDelegate {
  private final WeakReference<LynxBaseInspectorOwner> mOwner;

  public TestConsoleDelegate(LynxBaseInspectorOwner owner) {
    mOwner = new WeakReference<>(owner);
  }

  @Override
  public void onConsoleMessage(String msg) {
    LynxBaseInspectorOwner owner = mOwner.get();
    if (owner == null) {
      return;
    }
    try {
      Log.i("TestConsoleDelegate", "onConsoleMessage: " + msg);
      JSONObject jsonObject = new JSONObject(msg);
      JSONArray args = jsonObject.getJSONArray("args");
      for (int i = 0; i < args.length(); i++) {
        JSONObject obj = new JSONObject(args.get(i).toString());
        if (obj.get("type").toString().equals("object")) {
          String objectId = obj.get("objectId").toString();
          Handler mainHandler = new Handler(Looper.getMainLooper());
          // Post task instead of calling `getConsoleObject` directly to avoid deadlock.
          mainHandler.post(new Runnable() {
            @Override
            public void run() {
              LynxBaseInspectorOwner strongOwner = mOwner.get();
              if (strongOwner == null) {
                return;
              }
              strongOwner.getConsoleObject(
                  objectId, false, new Callback() {
                    @Override
                    public void invoke(Object... args) {
                      Log.i("TestConsoleDelegate", "getConsoleObject: " + args[0].toString());
                    }
                  });
              strongOwner.getConsoleObject(
                  objectId, true, new Callback() {
                    @Override
                    public void invoke(Object... args) {
                      Log.i("TestConsoleDelegate", "getConsoleObject: " + args[0].toString());
                    }
                  });
            }
          });
        }
      }
    } catch (JSONException e) {
      // ...
    }
  }
}
```

```java title="MainActivity.java" {1,10,13-20}
import com.lynx.devtoolwrapper.LynxBaseInspectorOwner;

public class MainActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...

    handleConsoleMessage(lynxView);
  }

  private void handleConsoleMessage(LynxView lynxView) {
    LynxBaseInspectorOwner owner = lynxView.getBaseInspectorOwner();
    if (owner == null) {
      return;
    }
    TestConsoleDelegate delegate = new TestConsoleDelegate(owner);
    owner.setLynxInspectorConsoleDelegate(delegate);
  }
}
```

#### Harmony

```ts title="TestConsoleDelegate.ets" {2-3,6,13-31}
import {
  LynxBaseInspectorOwner,
  LynxInspectorConsoleDelegate,
} from '@lynx/lynx';

export class TestConsoleDelegate implements LynxInspectorConsoleDelegate {
  private owner: WeakRef<LynxBaseInspectorOwner>;

  constructor(owner: LynxBaseInspectorOwner) {
    this.owner = new WeakRef(owner);
  }

  public onConsoleMessage(msg: string): void {
    console.log('onConsoleMessage:', msg);
    let json: object = JSON.parse(msg);
    let args: Array<object> = json['args'];
    args.forEach((value) => {
      if (value['type'] === 'object') {
        let objectId: string = value['objectId'];
        let owner = this.owner.deref();
        if (owner) {
          owner.getConsoleObject(objectId, true, (detail: string) => {
            console.log('getConsoleObject:', detail);
          });
          owner.getConsoleObject(objectId, false, (detail: string) => {
            console.log('getConsoleObject:', detail);
          });
        }
      }
    });
  }
}
```

```ts title=Index.ets" {2,14-18}
import { LynxView, LynxContext } from '@lynx/lynx';
import { TestConsoleDelegate } from './TestConsoleDelegate';

@Entry
@Component
struct Index {
  // ...

  build() {
    Column() {
      LynxView({
        // ...
        onCreate: (context: LynxContext) => {
          let owner = context?.getBaseInspectorOwner();
          if (owner) {
            let delegate = new TestConsoleDelegate(owner);
            owner.setLynxInspectorConsoleDelegate(delegate);
          }
        }
      }).width('100%').height('100%');
    }
  }
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.lynx-inspector-console-delegate`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.5 | - |

**Description:** LynxInspectorConsoleDelegate




---
url: /api/lynx-devtool-native-api/message-handler.md
---

# MessageHandler

APISummary
A **protocol (or interface)** that acts as a handler for debugging messages.

To learn how to subscribe to debugging messages, please refer to [`subscribeMessage`](/api/lynx-devtool-native-api/lynx-base-inspector-owner/subscribe-message.md).

## Syntax

Implement the `MessageHandler` protocol (or interface) and receive debugging messages through the `onMessage` method.

### iOS

```objective-c title="LynxBaseInspectorOwnerNG.h"
@protocol MessageHandler <NSObject>

@required
- (void)onMessage:(nonnull NSString *)message;

@end
```

### Android

```java title="MessageHandler.java"
public interface MessageHandler {
  void onMessage(String message);
}
```

### Harmony

```ts title="MessageHandler.ets"
export interface MessageHandler {
  onMessage: (msg: string) => void;
}
```

## Compatibility

**Compatibility Table**
**Query:** `lynx-devtool-native-api.message-handler`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.8 | - |

**Description:** MessageHandler




---
url: /api/lynx-testing-environment/index.md
---



# @lynx-js/testing-environment

`@lynx-js/testing-environment` is a pure-JavaScript implementation of the [Lynx Spec](/api/engine/element-api.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. In general, the goal of the project is to emulate enough of a subset of a Lynx environment to be useful for testing.

The Element PAPI implementation is based on jsdom, for example `__CreateElement` will return a `LynxElement`, which extends `HTMLElement` from jsdom. You can reuse the testing utilities that are commonly used for DOM testing, such as [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) (for DOM querying) and [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) (custom jest matchers for the DOM), etc.

## Usage

```js
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });
```

To use `@lynx-js/testing-environment`, you will primarily use the `LynxTestingEnv` constructor, which is a named export of the package. You will get back a `LynxTestingEnv` instance, which has a number of methods of useful properties, notably `switchToMainThread` and `switchToBackgroundThread`, which allow you to switch between the main thread and background thread.

Use the background thread API:

```js
lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
// or directly use `lynxCoreInject` since it's already injected to `globalThis`
// lynxCoreInject.tt.OnLifecycleEvent(...args);
```

Use the main thread API:

```js
lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);
```

Note that you can still access the other thread's globals without switching threads:

```js
lynxTestingEnv.switchToMainThread();
// use the `backgroundThread` global object even though we're on the main thread
lynxTestingEnv.backgroundThread.tt.OnLifecycleEvent(...args);
```

### Use in Vitest

It is recommended to configure as Vitest's [test environment](https://vitest.dev/guide/environment), for example:

```js
// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: require.resolve(
      '@lynx-js/testing-environment/env/vitest',
    ),
  },
});
```

After configuration, you can directly access the `lynxTestingEnv` object globally in the test.

If you want to use `@lynx-js/testing-environment` for unit testing in ReactLynx, you usually don't need to specify this configuration manually.

Please refer to [ReactLynx Testing Library](/react/reactlynx-testing-library.md) to inherit the configuration from `@lynx-js/react/testing-library`.

### Use in Rstest

If your runner already provides a `window` global via jsdom, you can load the shared Lynx test environment with:

```js
import '@lynx-js/testing-environment/env/rstest';
```

## Credits

Thanks to:

- [jsdom](https://github.com/jsdom/jsdom) for the pure-JavaScript implementation of DOM API.

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Classes

| Class                                                                           | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [GlobalEventEmitter](/api/lynx-testing-environment/Class.GlobalEventEmitter.md) | The Lynx `GlobalEventEmitter` module, accessible via `lynx.getJSModule('GlobalEventEmitter')`.                                                                                                                  |
| [LynxTestingEnv](/api/lynx-testing-environment/Class.LynxTestingEnv.md)         | A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. |

## Interfaces

| Interface                                                                   | Description                                               |
| --------------------------------------------------------------------------- | --------------------------------------------------------- |
| [LynxElement](/api/lynx-testing-environment/Interface.LynxElement.md)       | Any Lynx Element, such as `view`, `text`, `image`, etc.   |
| [LynxEnv](/api/lynx-testing-environment/Interface.LynxEnv.md)               | The host environment used to initialize `LynxTestingEnv`. |
| [LynxGlobalThis](/api/lynx-testing-environment/Interface.LynxGlobalThis.md) | The `globalThis` object of Lynx dual thread environment.  |

## Type Aliases

| Type alias                                                                              | Description            |
| --------------------------------------------------------------------------------------- | ---------------------- |
| [ElementTree](/api/lynx-testing-environment/TypeAlias.ElementTree.md)                   | The lynx element tree  |
| [ElementTreeGlobals](/api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md)     | The Element PAPI Types |
| [FilterUnderscoreKeys](/api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md) | -                      |
| [PickUnderscoreKeys](/api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md)     | -                      |

## Functions

| Function                                                                                     | Description                                                                  |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [initElementTree](/api/lynx-testing-environment/Function.initElementTree.md)                 | -                                                                            |
| [installLynxTestingEnv](/api/lynx-testing-environment/Function.installLynxTestingEnv.md)     | Installs a `LynxTestingEnv` instance and its required globals onto a target. |
| [uninstallLynxTestingEnv](/api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md) | Removes the globals installed by `installLynxTestingEnv`.                    |



---
url: /api/lynx-testing-environment/Class.GlobalEventEmitter.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / GlobalEventEmitter

# Class: GlobalEventEmitter

The Lynx `GlobalEventEmitter` module, accessible via `lynx.getJSModule('GlobalEventEmitter')`.

Framework testing libraries can use this to trigger and listen to cross-thread events.

## Constructors

### new GlobalEventEmitter()

```ts
new GlobalEventEmitter(): GlobalEventEmitter
```

#### Returns

[`GlobalEventEmitter`](/api/lynx-testing-environment/Class.GlobalEventEmitter.md)

## Properties

### listeners

```ts
listeners: Record<string, Function[]>;
```

#### Defined in

lynx/GlobalEventEmitter.d.ts:9

## Methods

### addListener()

```ts
addListener(eventName: string, listener: Function): void
```

#### Parameters

| Parameter   | Type       |
| ----------- | ---------- |
| `eventName` | `string`   |
| `listener`  | `Function` |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:10

***

### clear()

```ts
clear(): void
```

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:13

***

### emit()

```ts
emit(eventName: string, args: any[]): void
```

#### Parameters

| Parameter   | Type     |
| ----------- | -------- |
| `eventName` | `string` |
| `args`      | `any`\[] |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:12

***

### removeAllListeners()

```ts
removeAllListeners(eventName?: string): void
```

#### Parameters

| Parameter    | Type     |
| ------------ | -------- |
| `eventName`? | `string` |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:14

***

### removeListener()

```ts
removeListener(eventName: string, listener: Function): void
```

#### Parameters

| Parameter   | Type       |
| ----------- | ---------- |
| `eventName` | `string`   |
| `listener`  | `Function` |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:11

***

### toggle()

```ts
toggle(eventName: string, ...data: unknown[]): void
```

#### Parameters

| Parameter   | Type         |
| ----------- | ------------ |
| `eventName` | `string`     |
| ...`data`   | `unknown`\[] |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:16

***

### trigger()

```ts
trigger(eventName: string, params: string | Record<any, any>): void
```

#### Parameters

| Parameter   | Type                                |
| ----------- | ----------------------------------- |
| `eventName` | `string`                            |
| `params`    | `string` \| `Record`\<`any`, `any`> |

#### Returns

`void`

#### Defined in

lynx/GlobalEventEmitter.d.ts:15



---
url: /api/lynx-testing-environment/Class.LynxTestingEnv.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxTestingEnv

# Class: LynxTestingEnv

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);

```

## Constructors

### new LynxTestingEnv()

```ts
new LynxTestingEnv(env?: LynxEnv): LynxTestingEnv
```

#### Parameters

| Parameter | Type                                                            |
| --------- | --------------------------------------------------------------- |
| `env`?    | [`LynxEnv`](/api/lynx-testing-environment/Interface.LynxEnv.md) |

#### Returns

[`LynxTestingEnv`](/api/lynx-testing-environment/Class.LynxTestingEnv.md)

#### Defined in

index.d.ts:166

## Properties

### backgroundThread

```ts
backgroundThread: LynxGlobalThis;
```

The global object for the background thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
```

#### Defined in

index.d.ts:145

***

### env

```ts
env: LynxEnv;
```

#### Defined in

index.d.ts:165

***

### mainThread

```ts
mainThread: LynxGlobalThis & ElementTreeGlobals;
```

The global object for the main thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToMainThread();
// use the main thread global object
const page = globalThis.__CreatePage('0', 0);
const view = globalThis.__CreateView(0);
globalThis.__AppendElement(page, view);
```

#### Defined in

index.d.ts:164

## Methods

### clearGlobal()

```ts
clearGlobal(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:170

***

### injectGlobals()

```ts
injectGlobals(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:167

***

### reset()

```ts
reset(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:171

***

### switchToBackgroundThread()

```ts
switchToBackgroundThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:168

***

### switchToMainThread()

```ts
switchToMainThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:169



---
url: /api/lynx-testing-environment/Function.initElementTree.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / initElementTree

# Function: initElementTree()

```ts
function initElementTree(): object
```

## Returns

`object`

### animationMap

```ts
animationMap: Map<string, object>;
```

**`Internal`**

### root

```ts
root: undefined | LynxElement;
```

### uniqueId2Element

```ts
uniqueId2Element: Map<number, LynxElement>;
```

### \_\_AddDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `key`     | `string`                                                                |
| `value`   | `string`                                                                |

#### Returns

`void`

### \_\_AddEvent()

#### Parameters

| Parameter      | Type                                                                    |
| -------------- | ----------------------------------------------------------------------- |
| `e`            | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `eventType`    | `string`                                                                |
| `eventName`    | `string`                                                                |
| `eventHandler` | `string` \| `Record`\<`string`, `any`>                                  |

#### Returns

`void`

### \_\_AddInlineStyle()

#### Parameters

| Parameter | Type          |
| --------- | ------------- |
| `e`       | `HTMLElement` |
| `key`     | `number`      |
| `value`   | `string`      |

#### Returns

`void`

### \_\_AppendElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_CreateElement()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `tag`                     | `string` |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateImage()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateList()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |
| `componentAtIndex`        | `any`    |
| `enqueueComponent`        | `any`    |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreatePage()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `_tag`                    | `string` |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateRawText()

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `text`    | `string` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateScrollView()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateText()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateView()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_CreateWrapperElement()

#### Parameters

| Parameter                 | Type     |
| ------------------------- | -------- |
| `parentComponentUniqueId` | `number` |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_ElementAnimate()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `element` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `args`    | \[`number`, `string`, `...any[]`]                                       |

#### Returns

`void`

### \_\_FirstElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

[`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_FlushElementTree()

#### Returns

`void`

### \_\_GetAttributeByName()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `ele`     | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `name`    | `string`                                                                |

#### Returns

`null` | `string`

### \_\_GetDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`DOMStringMap`

### \_\_GetElementByUniqueId()

#### Parameters

| Parameter  | Type     |
| ---------- | -------- |
| `uniqueId` | `number` |

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_GetElementUniqueID()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`number`

### \_\_GetEvent()

#### Parameters

| Parameter   | Type                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| `e`         | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `eventType` | `string`                                                                |
| `eventName` | `string`                                                                |

#### Returns

`undefined` | `object`

### \_\_GetPageElement()

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_GetTag()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `ele`     | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`string`

### \_\_InsertElementBefore()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `ref`?    | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_QuerySelector()

#### Parameters

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `e`           | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `cssSelector` | `string`                                                                |
| `_params`     | `object`                                                                |

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### \_\_RemoveElement()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `parent`  | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `child`   | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_RemoveGestureDetector()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `id`      | `number`                                                                |

#### Returns

`void`

### \_\_ReplaceElement()

#### Parameters

| Parameter    | Type                                                                    |
| ------------ | ----------------------------------------------------------------------- |
| `newElement` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `oldElement` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |

#### Returns

`void`

### \_\_SetAttribute()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `key`     | `string`                                                                |
| `value`   | `any`                                                                   |

#### Returns

`void`

### \_\_SetClasses()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `cls`     | `string`                                                                |

#### Returns

`void`

### \_\_SetCSSId()

#### Parameters

| Parameter    | Type                                                                                                                                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `e`          | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) \| [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)\[] |
| `id`         | `string`                                                                                                                                              |
| `entryName`? | `string`                                                                                                                                              |

#### Returns

`void`

### \_\_SetDataset()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `dataset` | `any`                                                                   |

#### Returns

`void`

### \_\_SetGestureDetector()

#### Parameters

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `e`           | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `id`          | `number`                                                                |
| `type`        | `number`                                                                |
| `config`      | `any`                                                                   |
| `relationMap` | `Record`\<`string`, `number`\[]>                                        |

#### Returns

`void`

### \_\_SetID()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `id`      | `string`                                                                |

#### Returns

`void`

### \_\_SetInlineStyles()

#### Parameters

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `styles`  | `string` \| `Record`\<`string`, `string`>                               |

#### Returns

`void`

### \_\_UpdateListCallbacks()

#### Parameters

| Parameter          | Type                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`             | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)                                                                                                                                 |
| `componentAtIndex` | (`list`: [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md), `listID`: `number`, `cellIndex`: `number`, `operationID`: `number`, `enable_reuse_notification`: `boolean`) => `void` |
| `enqueueComponent` | (`list`: [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md), `listID`: `number`, `sign`: `number`) => `void`                                                                       |

#### Returns

`void`

### \_\_UpdateListComponents()

#### Parameters

| Parameter     | Type                                                                    |
| ------------- | ----------------------------------------------------------------------- |
| `_list`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `_components` | `string`\[]                                                             |

#### Returns

`void`

### clear()

#### Returns

`void`

### countElement()

#### Parameters

| Parameter                 | Type                                                                    |
| ------------------------- | ----------------------------------------------------------------------- |
| `element`                 | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) |
| `parentComponentUniqueId` | `number`                                                                |

#### Returns

`void`

### enterListItemAtIndex()

Enter a list-item element at the given index.
It will load the list-item element using the `componentAtIndex` callback.

#### Parameters

| Parameter | Type                                                                    | Description                                        |
| --------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) | The list element                                   |
| `index`   | `number`                                                                | The index of the list-item element                 |
| ...`args` | `any`\[]                                                                | The arguments used to create the list-item element |

#### Returns

`number`

The unique id of the list-item element

### leaveListItem()

Leave a list-item element.
It will mark the list-item element as unused using
the `enqueueComponent` callback, and the list-item element
will be reused in the future by other list-item elements.

#### Parameters

| Parameter | Type                                                                    | Description                            |
| --------- | ----------------------------------------------------------------------- | -------------------------------------- |
| `e`       | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) | The list element                       |
| `uiSign`  | `number`                                                                | The unique id of the list-item element |

#### Returns

`void`

### toJSON()

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

### toTree()

#### Returns

`undefined` | [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md)

## Defined in

lynx/ElementPAPI.d.ts:47



---
url: /api/lynx-testing-environment/Function.installLynxTestingEnv.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / installLynxTestingEnv

# Function: installLynxTestingEnv()

```ts
function installLynxTestingEnv(target: typeof globalThis & object, env: LynxEnv): void
```

Installs a `LynxTestingEnv` instance and its required globals onto a target.

## Parameters

| Parameter | Type                                                            |
| --------- | --------------------------------------------------------------- |
| `target`  | _typeof_ `globalThis` & `object`                                |
| `env`     | [`LynxEnv`](/api/lynx-testing-environment/Interface.LynxEnv.md) |

## Returns

`void`

## Defined in

index.d.ts:90



---
url: /api/lynx-testing-environment/Function.uninstallLynxTestingEnv.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / uninstallLynxTestingEnv

# Function: uninstallLynxTestingEnv()

```ts
function uninstallLynxTestingEnv(target: typeof globalThis & object): void
```

Removes the globals installed by `installLynxTestingEnv`.

## Parameters

| Parameter | Type                             |
| --------- | -------------------------------- |
| `target`  | _typeof_ `globalThis` & `object` |

## Returns

`void`

## Defined in

index.d.ts:100



---
url: /api/lynx-testing-environment/Interface.LynxElement.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxElement

# Interface: LynxElement

Any Lynx Element, such as `view`, `text`, `image`, etc.

[Lynx Spec Reference](https://lynxjs.org/living-spec/index.html?ts=1743416098203#element%E2%91%A0)

## Extends

- `HTMLElement`

## Properties

### cssId?

```ts
optional cssId: string;
```

The cssId of the element

#### Defined in

lynx/ElementPAPI.d.ts:24

***

### eventMap?

```ts
optional eventMap: object;
```

The map of events bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:12

***

### firstChild

```ts
firstChild: LynxElement;
```

Returns the first child.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/firstChild)

#### Defined in

lynx/ElementPAPI.d.ts:30

***

### gesture?

```ts
optional gesture: object;
```

The gestures bound to the element.

#### Index Signature

\[`key`: `string`]: `any`

#### Defined in

lynx/ElementPAPI.d.ts:18

***

### nextSibling

```ts
nextSibling: LynxElement;
```

Returns the next sibling.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/nextSibling)

#### Defined in

lynx/ElementPAPI.d.ts:36

***

### parentNode

```ts
parentNode: LynxElement;
```

Returns the parent.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Node/parentNode)

#### Defined in

lynx/ElementPAPI.d.ts:42



---
url: /api/lynx-testing-environment/Interface.LynxEnv.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxEnv

# Interface: LynxEnv

The host environment used to initialize `LynxTestingEnv`.

## Properties

### window

```ts
window: any;
```

#### Defined in

index.d.ts:19



---
url: /api/lynx-testing-environment/Interface.LynxGlobalThis.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / LynxGlobalThis

# Interface: LynxGlobalThis

The `globalThis` object of Lynx dual thread environment.

## Indexable

\[`key`: `string`]: `any`

## Properties

### globalThis

```ts
globalThis: LynxGlobalThis;
```

The globalThis object.

#### Defined in

lynx/GlobalThis.d.ts:11



---
url: /api/lynx-testing-environment/TypeAlias.ElementTree.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / ElementTree

# Type Alias: ElementTree

```ts
type ElementTree: ReturnType<typeof initElementTree>;
```

The lynx element tree

## Defined in

index.d.ts:25



---
url: /api/lynx-testing-environment/TypeAlias.ElementTreeGlobals.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / ElementTreeGlobals

# Type Alias: ElementTreeGlobals

```ts
type ElementTreeGlobals: PickUnderscoreKeys<ElementTree>;
```

The Element PAPI Types

## Defined in

index.d.ts:40



---
url: /api/lynx-testing-environment/TypeAlias.FilterUnderscoreKeys.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / FilterUnderscoreKeys

# Type Alias: FilterUnderscoreKeys\<T>

```ts
type FilterUnderscoreKeys<T>: { [K in keyof T]: K extends `__${string}` ? K : never }[keyof T];
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:29



---
url: /api/lynx-testing-environment/TypeAlias.PickUnderscoreKeys.md
---



[lynx-testing-environment](/api/lynx-testing-environment/index.md) / PickUnderscoreKeys

# Type Alias: PickUnderscoreKeys\<T>

```ts
type PickUnderscoreKeys<T>: Pick<T, FilterUnderscoreKeys<T>>;
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:35



---
url: /api/reactlynx-testing-library/index.md
---



# @lynx-js/react/testing-library

ReactLynx Testing Library is a simple and complete ReactLynx unit testing library that encourages good testing practices.

> Inspired completely by [react-testing-library](https://github.com/testing-library/react-testing-library)

Similar to [react-testing-library](https://github.com/testing-library/react-testing-library), this library is designed to test your ReactLynx components in the same way you would test React components using react-testing-library.

## Setup

### Rstest

Setup rstest with `@lynx-js/react/testing-library/rstest-config`.

Recommended for library projects:

```ts
import { defineConfig } from '@rstest/core';
import { withDefaultConfig } from '@lynx-js/react/testing-library/rstest-config';

export default defineConfig({
  extends: withDefaultConfig(),
});
```

Use `withLynxConfig` when you want to reuse your app's `lynx.config.ts`:

```ts
// rstest.config.ts
import { defineConfig } from '@rstest/core';
import { withLynxConfig } from '@lynx-js/react/testing-library/rstest-config';

export default defineConfig({
  extends: withLynxConfig(),
});
```

Difference between `withLynxConfig` and `withDefaultConfig`:

- `withLynxConfig`: app-oriented. Loads your `lynx.config.ts` and converts it to rstest config, so rspeedy/lynx settings are reused in tests.
- `withDefaultConfig`: library-oriented. Only applies testing-library defaults (`jsdom`, setup files, globals) and lets you provide the rest via `modifyRstestConfig`.

Then you can start writing tests and run them with rstest!

For more usage detail, see [https://rstest.rs/](https://rstest.rs/)

### Vitest

Setup vitest:

```js
import { defineConfig } from 'vitest/config';
import { vitestTestingLibraryPlugin } from '@lynx-js/react/testing-library/plugins';

export default defineConfig({
  plugins: [
    vitestTestingLibraryPlugin(),
  ],
  test: {
    // ...
  },
});
```

Then you can start writing tests and run them with vitest!

`createVitestConfig` is still supported for backward compatibility, but is deprecated.

## Usage

```jsx
import '@testing-library/jest-dom';
import { test, expect } from 'vitest'; // or '@rstest/core'
import { render } from '@lynx-js/react/testing-library';

test('renders options.wrapper around node', async () => {
  const WrapperComponent = ({ children }) => (
    <view data-testid='wrapper'>{children}</view>
  );
  const Comp = () => {
    return <view data-testid='inner' style='background-color: yellow;' />;
  };
  const { container, getByTestId } = render(<Comp />, {
    wrapper: WrapperComponent,
  });
  expect(getByTestId('wrapper')).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <view
      data-testid="wrapper"
    >
      <view
        data-testid="inner"
        style="background-color: yellow;"
      />
    </view>
  `);
});
```

💡 Since our testing environment (`@lynx-js/testing-environment`) is based on jsdom, You may also be interested in installing `@testing-library/jest-dom` so you can use
[the custom jest matchers](https://github.com/testing-library/jest-dom).

## Examples

See our [examples](https://github.com/lynx-family/lynx-stack/tree/main/packages/react/testing-library/src/__tests__) for more usage.

## Credits

- [Testing Library](https://testing-library.com/) for the testing utilities and good practices for React testing.

## References

### prettyFormat

Renames and re-exports [act](/api/reactlynx-testing-library/Variable.act.md)

***

### QueryByBoundAttribute

Re-exports [QueryByBoundAttribute](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)

***

### QueryByRole

Re-exports [QueryByRole](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)

***

### QueryByText

Re-exports [QueryByText](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)

***

### QueryMethod

Re-exports [QueryMethod](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md)

***

### SelectorMatcherOptions

Re-exports [SelectorMatcherOptions](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)

***

### WithSuggest

Re-exports [WithSuggest](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md)

## Namespaces

| Namespace                                                                | Description |
| ------------------------------------------------------------------------ | ----------- |
| [queries](/api/reactlynx-testing-library/Namespace.queries.md)           | -           |
| [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) | -           |

## Classes

| Class                                                                    | Description                                                                                                                                                                                                     |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [LynxTestingEnv](/api/reactlynx-testing-library/Class.LynxTestingEnv.md) | A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md), notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js. |

## Interfaces

| Interface                                                                                        | Description                                                                         |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [ByRoleOptions](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)                       | -                                                                                   |
| [Config](/api/reactlynx-testing-library/Interface.Config.md)                                     | -                                                                                   |
| [ConfigFn](/api/reactlynx-testing-library/Interface.ConfigFn.md)                                 | -                                                                                   |
| [DefaultNormalizerOptions](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md) | -                                                                                   |
| [LogRolesOptions](/api/reactlynx-testing-library/Interface.LogRolesOptions.md)                   | -                                                                                   |
| [MatcherOptions](/api/reactlynx-testing-library/Interface.MatcherOptions.md)                     | -                                                                                   |
| [NormalizerOptions](/api/reactlynx-testing-library/Interface.NormalizerOptions.md)               | -                                                                                   |
| [PrettyDOMOptions](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md)                 | -                                                                                   |
| [Queries](/api/reactlynx-testing-library/Interface.Queries.md)                                   | -                                                                                   |
| [QueryOptions](/api/reactlynx-testing-library/Interface.QueryOptions.md)                         | -                                                                                   |
| [RenderHookOptions](/api/reactlynx-testing-library/Interface.RenderHookOptions.md)               | The options for [renderHook](/api/reactlynx-testing-library/Function.renderHook.md) |
| [RenderHookResult](/api/reactlynx-testing-library/Interface.RenderHookResult.md)                 | The result of [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)   |
| [RenderOptions](/api/reactlynx-testing-library/Interface.RenderOptions.md)                       | The options for [render](/api/reactlynx-testing-library/Function.render.md).        |
| [Suggestion](/api/reactlynx-testing-library/Interface.Suggestion.md)                             | -                                                                                   |
| [waitForOptions](/api/reactlynx-testing-library/Interface.waitForOptions.md)                     | -                                                                                   |

## Type Aliases

| Type alias                                                                                     | Description                                                               |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [AllByAttribute](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md)                   | -                                                                         |
| [AllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)         | -                                                                         |
| [AllByRole](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)                             | -                                                                         |
| [AllByText](/api/reactlynx-testing-library/TypeAlias.AllByText.md)                             | -                                                                         |
| [BoundFunction](/api/reactlynx-testing-library/TypeAlias.BoundFunction.md)                     | -                                                                         |
| [BoundFunctions](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)                   | -                                                                         |
| [BuiltQueryMethods](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)             | -                                                                         |
| [ByRoleMatcher](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)                     | -                                                                         |
| [CreateFunction](/api/reactlynx-testing-library/TypeAlias.CreateFunction.md)                   | -                                                                         |
| [CreateObject](/api/reactlynx-testing-library/TypeAlias.CreateObject.md)                       | -                                                                         |
| [ElementTree](/api/reactlynx-testing-library/TypeAlias.ElementTree.md)                         | The lynx element tree                                                     |
| [EventType](/api/reactlynx-testing-library/TypeAlias.EventType.md)                             | -                                                                         |
| [FindAllBy](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md)                             | -                                                                         |
| [FindAllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md) | -                                                                         |
| [FindAllByRole](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)                     | -                                                                         |
| [FindAllByText](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)                     | -                                                                         |
| [FindBy](/api/reactlynx-testing-library/TypeAlias.FindBy.md)                                   | -                                                                         |
| [FindByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)       | -                                                                         |
| [FindByRole](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)                           | -                                                                         |
| [FindByText](/api/reactlynx-testing-library/TypeAlias.FindByText.md)                           | -                                                                         |
| [FireFunction](/api/reactlynx-testing-library/TypeAlias.FireFunction.md)                       | -                                                                         |
| [FireObject](/api/reactlynx-testing-library/TypeAlias.FireObject.md)                           | -                                                                         |
| [GetAllBy](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)                               | -                                                                         |
| [GetBy](/api/reactlynx-testing-library/TypeAlias.GetBy.md)                                     | -                                                                         |
| [GetByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)         | -                                                                         |
| [GetByRole](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)                             | -                                                                         |
| [GetByText](/api/reactlynx-testing-library/TypeAlias.GetByText.md)                             | -                                                                         |
| [GetErrorFunction](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)               | -                                                                         |
| [Match](/api/reactlynx-testing-library/TypeAlias.Match.md)                                     | -                                                                         |
| [Matcher](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                 | -                                                                         |
| [MatcherFunction](/api/reactlynx-testing-library/TypeAlias.MatcherFunction.md)                 | -                                                                         |
| [Method](/api/reactlynx-testing-library/TypeAlias.Method.md)                                   | -                                                                         |
| [NormalizerFn](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md)                       | -                                                                         |
| [Query](/api/reactlynx-testing-library/TypeAlias.Query.md)                                     | -                                                                         |
| [QueryArgs](/api/reactlynx-testing-library/TypeAlias.QueryArgs.md)                             | -                                                                         |
| [QueryBy](/api/reactlynx-testing-library/TypeAlias.QueryBy.md)                                 | -                                                                         |
| [QueryByAttribute](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md)               | -                                                                         |
| [RenderResult](/api/reactlynx-testing-library/TypeAlias.RenderResult.md)                       | The result of [render](/api/reactlynx-testing-library/Function.render.md) |
| [Screen](/api/reactlynx-testing-library/TypeAlias.Screen.md)                                   | -                                                                         |
| [Variant](/api/reactlynx-testing-library/TypeAlias.Variant.md)                                 | -                                                                         |

## Variables

| Variable                                                    | Description |
| ----------------------------------------------------------- | ----------- |
| [act](/api/reactlynx-testing-library/Variable.act.md)       | -           |
| [screen](/api/reactlynx-testing-library/Variable.screen.md) | -           |

## Functions

| Function                                                                                          | Description                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [buildQueries](/api/reactlynx-testing-library/Function.buildQueries.md)                           | -                                                                                                                                                                  |
| [cleanup](/api/reactlynx-testing-library/Function.cleanup.md)                                     | Cleanup elements rendered to the page and Preact trees that were mounted with render.                                                                              |
| [computeHeadingLevel](/api/reactlynx-testing-library/Function.computeHeadingLevel.md)             | -                                                                                                                                                                  |
| [configure](/api/reactlynx-testing-library/Function.configure.md)                                 | -                                                                                                                                                                  |
| [createEvent](/api/reactlynx-testing-library/Function.createEvent.md)                             | -                                                                                                                                                                  |
| [findAllByAltText](/api/reactlynx-testing-library/Function.findAllByAltText.md)                   | -                                                                                                                                                                  |
| [findAllByDisplayValue](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md)         | -                                                                                                                                                                  |
| [findAllByLabelText](/api/reactlynx-testing-library/Function.findAllByLabelText.md)               | -                                                                                                                                                                  |
| [findAllByPlaceholderText](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md)   | -                                                                                                                                                                  |
| [findAllByRole](/api/reactlynx-testing-library/Function.findAllByRole.md)                         | -                                                                                                                                                                  |
| [findAllByTestId](/api/reactlynx-testing-library/Function.findAllByTestId.md)                     | -                                                                                                                                                                  |
| [findAllByText](/api/reactlynx-testing-library/Function.findAllByText.md)                         | -                                                                                                                                                                  |
| [findAllByTitle](/api/reactlynx-testing-library/Function.findAllByTitle.md)                       | -                                                                                                                                                                  |
| [findByAltText](/api/reactlynx-testing-library/Function.findByAltText.md)                         | -                                                                                                                                                                  |
| [findByDisplayValue](/api/reactlynx-testing-library/Function.findByDisplayValue.md)               | -                                                                                                                                                                  |
| [findByLabelText](/api/reactlynx-testing-library/Function.findByLabelText.md)                     | -                                                                                                                                                                  |
| [findByPlaceholderText](/api/reactlynx-testing-library/Function.findByPlaceholderText.md)         | -                                                                                                                                                                  |
| [findByRole](/api/reactlynx-testing-library/Function.findByRole.md)                               | -                                                                                                                                                                  |
| [findByTestId](/api/reactlynx-testing-library/Function.findByTestId.md)                           | -                                                                                                                                                                  |
| [findByText](/api/reactlynx-testing-library/Function.findByText.md)                               | -                                                                                                                                                                  |
| [findByTitle](/api/reactlynx-testing-library/Function.findByTitle.md)                             | -                                                                                                                                                                  |
| [fireEvent](/api/reactlynx-testing-library/Function.fireEvent.md)                                 | -                                                                                                                                                                  |
| [getAllByAltText](/api/reactlynx-testing-library/Function.getAllByAltText.md)                     | -                                                                                                                                                                  |
| [getAllByDisplayValue](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md)           | -                                                                                                                                                                  |
| [getAllByLabelText](/api/reactlynx-testing-library/Function.getAllByLabelText.md)                 | -                                                                                                                                                                  |
| [getAllByPlaceholderText](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md)     | -                                                                                                                                                                  |
| [getAllByRole](/api/reactlynx-testing-library/Function.getAllByRole.md)                           | -                                                                                                                                                                  |
| [getAllByTestId](/api/reactlynx-testing-library/Function.getAllByTestId.md)                       | -                                                                                                                                                                  |
| [getAllByText](/api/reactlynx-testing-library/Function.getAllByText.md)                           | -                                                                                                                                                                  |
| [getAllByTitle](/api/reactlynx-testing-library/Function.getAllByTitle.md)                         | -                                                                                                                                                                  |
| [getByAltText](/api/reactlynx-testing-library/Function.getByAltText.md)                           | -                                                                                                                                                                  |
| [getByDisplayValue](/api/reactlynx-testing-library/Function.getByDisplayValue.md)                 | -                                                                                                                                                                  |
| [getByLabelText](/api/reactlynx-testing-library/Function.getByLabelText.md)                       | -                                                                                                                                                                  |
| [getByPlaceholderText](/api/reactlynx-testing-library/Function.getByPlaceholderText.md)           | -                                                                                                                                                                  |
| [getByRole](/api/reactlynx-testing-library/Function.getByRole.md)                                 | -                                                                                                                                                                  |
| [getByTestId](/api/reactlynx-testing-library/Function.getByTestId.md)                             | -                                                                                                                                                                  |
| [getByText](/api/reactlynx-testing-library/Function.getByText.md)                                 | -                                                                                                                                                                  |
| [getByTitle](/api/reactlynx-testing-library/Function.getByTitle.md)                               | -                                                                                                                                                                  |
| [getConfig](/api/reactlynx-testing-library/Function.getConfig.md)                                 | -                                                                                                                                                                  |
| [getDefaultNormalizer](/api/reactlynx-testing-library/Function.getDefaultNormalizer.md)           | -                                                                                                                                                                  |
| [getElementError](/api/reactlynx-testing-library/Function.getElementError.md)                     | -                                                                                                                                                                  |
| [getNodeText](/api/reactlynx-testing-library/Function.getNodeText.md)                             | -                                                                                                                                                                  |
| [getQueriesForElement](/api/reactlynx-testing-library/Function.getQueriesForElement.md)           | -                                                                                                                                                                  |
| [getRoles](/api/reactlynx-testing-library/Function.getRoles.md)                                   | -                                                                                                                                                                  |
| [getSuggestedQuery](/api/reactlynx-testing-library/Function.getSuggestedQuery.md)                 | -                                                                                                                                                                  |
| [isInaccessible](/api/reactlynx-testing-library/Function.isInaccessible.md)                       | [https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible](https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible) |
| [logDOM](/api/reactlynx-testing-library/Function.logDOM.md)                                       | -                                                                                                                                                                  |
| [logRoles](/api/reactlynx-testing-library/Function.logRoles.md)                                   | -                                                                                                                                                                  |
| [prettyDOM](/api/reactlynx-testing-library/Function.prettyDOM.md)                                 | -                                                                                                                                                                  |
| [queryAllByAltText](/api/reactlynx-testing-library/Function.queryAllByAltText.md)                 | -                                                                                                                                                                  |
| [queryAllByAttribute](/api/reactlynx-testing-library/Function.queryAllByAttribute.md)             | -                                                                                                                                                                  |
| [queryAllByDisplayValue](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md)       | -                                                                                                                                                                  |
| [queryAllByLabelText](/api/reactlynx-testing-library/Function.queryAllByLabelText.md)             | -                                                                                                                                                                  |
| [queryAllByPlaceholderText](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md) | -                                                                                                                                                                  |
| [queryAllByRole](/api/reactlynx-testing-library/Function.queryAllByRole.md)                       | -                                                                                                                                                                  |
| [queryAllByTestId](/api/reactlynx-testing-library/Function.queryAllByTestId.md)                   | -                                                                                                                                                                  |
| [queryAllByText](/api/reactlynx-testing-library/Function.queryAllByText.md)                       | -                                                                                                                                                                  |
| [queryAllByTitle](/api/reactlynx-testing-library/Function.queryAllByTitle.md)                     | -                                                                                                                                                                  |
| [queryByAltText](/api/reactlynx-testing-library/Function.queryByAltText.md)                       | -                                                                                                                                                                  |
| [queryByAttribute](/api/reactlynx-testing-library/Function.queryByAttribute.md)                   | -                                                                                                                                                                  |
| [queryByDisplayValue](/api/reactlynx-testing-library/Function.queryByDisplayValue.md)             | -                                                                                                                                                                  |
| [queryByLabelText](/api/reactlynx-testing-library/Function.queryByLabelText.md)                   | -                                                                                                                                                                  |
| [queryByPlaceholderText](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md)       | -                                                                                                                                                                  |
| [queryByRole](/api/reactlynx-testing-library/Function.queryByRole.md)                             | -                                                                                                                                                                  |
| [queryByTestId](/api/reactlynx-testing-library/Function.queryByTestId.md)                         | -                                                                                                                                                                  |
| [queryByText](/api/reactlynx-testing-library/Function.queryByText.md)                             | -                                                                                                                                                                  |
| [queryByTitle](/api/reactlynx-testing-library/Function.queryByTitle.md)                           | -                                                                                                                                                                  |
| [render](/api/reactlynx-testing-library/Function.render.md)                                       | Render into the page. It should be used with cleanup.                                                                                                              |
| [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)                               | Allows you to render a hook within a test React component without having to create that component yourself.                                                        |
| [waitFor](/api/reactlynx-testing-library/Function.waitFor.md)                                     | -                                                                                                                                                                  |
| [waitForElementToBeRemoved](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md) | -                                                                                                                                                                  |
| [waitSchedule](/api/reactlynx-testing-library/Function.waitSchedule.md)                           | Wait for the next event loop.                                                                                                                                      |
| [within](/api/reactlynx-testing-library/Function.within.md)                                       | -                                                                                                                                                                  |



---
url: /api/reactlynx-testing-library/Class.LynxTestingEnv.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / LynxTestingEnv

# Class: LynxTestingEnv

A pure-JavaScript implementation of the [Lynx Spec](/guide/spec.md),
notably the [Element PAPI](/api/engine/element-api.md) and [Dual-threaded Model](/guide/spec.md#dual-threaded-model) for use with Node.js.

## Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToMainThread();
// use the main thread Element PAPI
const page = __CreatePage('0', 0);
const view = __CreateView(0);
__AppendElement(page, view);

```

## Constructors

### new LynxTestingEnv()

```ts
new LynxTestingEnv(env?: LynxEnv): LynxTestingEnv
```

#### Parameters

| Parameter | Type      |
| --------- | --------- |
| `env`?    | `LynxEnv` |

#### Returns

[`LynxTestingEnv`](/api/reactlynx-testing-library/Class.LynxTestingEnv.md)

#### Defined in

index.d.ts:971

## Properties

### backgroundThread

```ts
backgroundThread: LynxGlobalThis;
```

The global object for the background thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToBackgroundThread();
// use the background thread global object
globalThis.lynxCoreInject.tt.OnLifecycleEvent(...args);
```

#### Defined in

index.d.ts:950

***

### env

```ts
env: LynxEnv;
```

#### Defined in

index.d.ts:970

***

### mainThread

```ts
mainThread: LynxGlobalThis & ElementTreeGlobals;
```

The global object for the main thread.

#### Example

```ts
import { LynxTestingEnv } from '@lynx-js/testing-environment';
import { JSDOM } from 'jsdom';

const lynxTestingEnv = new LynxTestingEnv({ window: new JSDOM().window });

lynxTestingEnv.switchToMainThread();
// use the main thread global object
const page = globalThis.__CreatePage('0', 0);
const view = globalThis.__CreateView(0);
globalThis.__AppendElement(page, view);
```

#### Defined in

index.d.ts:969

## Methods

### clearGlobal()

```ts
clearGlobal(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:975

***

### injectGlobals()

```ts
injectGlobals(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:972

***

### reset()

```ts
reset(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:976

***

### switchToBackgroundThread()

```ts
switchToBackgroundThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:973

***

### switchToMainThread()

```ts
switchToMainThread(): void
```

#### Returns

`void`

#### Defined in

index.d.ts:974



---
url: /api/reactlynx-testing-library/Function.buildQueries.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / buildQueries

# Function: buildQueries()

```ts
function buildQueries<Arguments>(
   queryAllBy: GetAllBy<Arguments>, 
   getMultipleError: GetErrorFunction<Arguments>, 
getMissingError: GetErrorFunction<Arguments>): BuiltQueryMethods<Arguments>
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Parameters

| Parameter          | Type                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `queryAllBy`       | [`GetAllBy`](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)\<`Arguments`>                 |
| `getMultipleError` | [`GetErrorFunction`](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)\<`Arguments`> |
| `getMissingError`  | [`GetErrorFunction`](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)\<`Arguments`> |

## Returns

[`BuiltQueryMethods`](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)\<`Arguments`>

## Defined in

index.d.ts:193



---
url: /api/reactlynx-testing-library/Function.cleanup.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / cleanup

# Function: cleanup()

```ts
function cleanup(): void
```

Cleanup elements rendered to the page and Preact trees that were mounted with render.

## Returns

`void`

## Defined in

index.d.ts:285



---
url: /api/reactlynx-testing-library/Function.computeHeadingLevel.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / computeHeadingLevel

# Function: computeHeadingLevel()

```ts
function computeHeadingLevel(element: Element): number | undefined
```

## Parameters

| Parameter | Type      |
| --------- | --------- |
| `element` | `Element` |

## Returns

`number` | `undefined`

## Defined in

index.d.ts:287



---
url: /api/reactlynx-testing-library/Function.configure.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / configure

# Function: configure()

```ts
function configure(configDelta: ConfigFn | Partial<Config>): void
```

## Parameters

| Parameter     | Type                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configDelta` | [`ConfigFn`](/api/reactlynx-testing-library/Interface.ConfigFn.md) \| `Partial`\<[`Config`](/api/reactlynx-testing-library/Interface.Config.md)> |

## Returns

`void`

## Defined in

index.d.ts:314



---
url: /api/reactlynx-testing-library/Function.createEvent.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / createEvent

# Function: createEvent()

```ts
function createEvent(
   eventName: string, 
   node: any, 
   init?: object, 
   options?: object): Event
```

## Parameters

| Parameter              | Type     |
| ---------------------- | -------- |
| `eventName`            | `string` |
| `node`                 | `any`    |
| `init`?                | `object` |
| `options`?             | `object` |
| `options.defaultInit`? | `object` |
| `options.EventType`?   | `string` |

## Returns

`Event`

## Defined in

index.d.ts:316



---
url: /api/reactlynx-testing-library/Function.findAllByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByAltText

# Function: findAllByAltText()

```ts
function findAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:492



---
url: /api/reactlynx-testing-library/Function.findAllByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByDisplayValue

# Function: findAllByDisplayValue()

```ts
function findAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:503



---
url: /api/reactlynx-testing-library/Function.findAllByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByLabelText

# Function: findAllByLabelText()

```ts
function findAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindAllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByText`](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)\<`T`>>

## Defined in

index.d.ts:507



---
url: /api/reactlynx-testing-library/Function.findAllByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByPlaceholderText

# Function: findAllByPlaceholderText()

```ts
function findAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:511



---
url: /api/reactlynx-testing-library/Function.findAllByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByRole

# Function: findAllByRole()

```ts
function findAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions, waitForOptions]): ReturnType<FindAllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByRole`](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)\<`T`>>

## Defined in

index.d.ts:522



---
url: /api/reactlynx-testing-library/Function.findAllByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByTestId

# Function: findAllByTestId()

```ts
function findAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:526



---
url: /api/reactlynx-testing-library/Function.findAllByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByText

# Function: findAllByText()

```ts
function findAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindAllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByText`](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)\<`T`>>

## Defined in

index.d.ts:537



---
url: /api/reactlynx-testing-library/Function.findAllByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findAllByTitle

# Function: findAllByTitle()

```ts
function findAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindAllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindAllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:541



---
url: /api/reactlynx-testing-library/Function.findByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByAltText

# Function: findByAltText()

```ts
function findByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:550



---
url: /api/reactlynx-testing-library/Function.findByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByDisplayValue

# Function: findByDisplayValue()

```ts
function findByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:561



---
url: /api/reactlynx-testing-library/Function.findByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByLabelText

# Function: findByLabelText()

```ts
function findByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByText`](/api/reactlynx-testing-library/TypeAlias.FindByText.md)\<`T`>>

## Defined in

index.d.ts:565



---
url: /api/reactlynx-testing-library/Function.findByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByPlaceholderText

# Function: findByPlaceholderText()

```ts
function findByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:569



---
url: /api/reactlynx-testing-library/Function.findByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByRole

# Function: findByRole()

```ts
function findByRole<T>(...args: [HTMLElement, any, ByRoleOptions, waitForOptions]): ReturnType<FindByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByRole`](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)\<`T`>>

## Defined in

index.d.ts:580



---
url: /api/reactlynx-testing-library/Function.findByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByTestId

# Function: findByTestId()

```ts
function findByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:584



---
url: /api/reactlynx-testing-library/Function.findByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByText

# Function: findByText()

```ts
function findByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions, waitForOptions]): ReturnType<FindByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByText`](/api/reactlynx-testing-library/TypeAlias.FindByText.md)\<`T`>>

## Defined in

index.d.ts:595



---
url: /api/reactlynx-testing-library/Function.findByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / findByTitle

# Function: findByTitle()

```ts
function findByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions, waitForOptions]): ReturnType<FindByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                                                                               |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md), [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)] |

## Returns

`ReturnType`\<[`FindByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:599



---
url: /api/reactlynx-testing-library/Function.fireEvent.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / fireEvent

# Function: fireEvent()

```ts
function fireEvent(element: any, event: Event): boolean
```

## Parameters

| Parameter | Type    |
| --------- | ------- |
| `element` | `any`   |
| `event`   | `Event` |

## Returns

`boolean`

## Defined in

index.d.ts:603



---
url: /api/reactlynx-testing-library/Function.getAllByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByAltText

# Function: getAllByAltText()

```ts
function getAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:626



---
url: /api/reactlynx-testing-library/Function.getAllByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByDisplayValue

# Function: getAllByDisplayValue()

```ts
function getAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:630



---
url: /api/reactlynx-testing-library/Function.getAllByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByLabelText

# Function: getAllByLabelText()

```ts
function getAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:634



---
url: /api/reactlynx-testing-library/Function.getAllByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByPlaceholderText

# Function: getAllByPlaceholderText()

```ts
function getAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:638



---
url: /api/reactlynx-testing-library/Function.getAllByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByRole

# Function: getAllByRole()

```ts
function getAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<AllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`AllByRole`](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)\<`T`>>

## Defined in

index.d.ts:642



---
url: /api/reactlynx-testing-library/Function.getAllByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByTestId

# Function: getAllByTestId()

```ts
function getAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:646



---
url: /api/reactlynx-testing-library/Function.getAllByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByText

# Function: getAllByText()

```ts
function getAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:650



---
url: /api/reactlynx-testing-library/Function.getAllByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getAllByTitle

# Function: getAllByTitle()

```ts
function getAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:654



---
url: /api/reactlynx-testing-library/Function.getByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByAltText

# Function: getByAltText()

```ts
function getByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:660



---
url: /api/reactlynx-testing-library/Function.getByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByDisplayValue

# Function: getByDisplayValue()

```ts
function getByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:670



---
url: /api/reactlynx-testing-library/Function.getByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByLabelText

# Function: getByLabelText()

```ts
function getByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<GetByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByText`](/api/reactlynx-testing-library/TypeAlias.GetByText.md)\<`T`>>

## Defined in

index.d.ts:674



---
url: /api/reactlynx-testing-library/Function.getByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByPlaceholderText

# Function: getByPlaceholderText()

```ts
function getByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:678



---
url: /api/reactlynx-testing-library/Function.getByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByRole

# Function: getByRole()

```ts
function getByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<GetByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`GetByRole`](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)\<`T`>>

## Defined in

index.d.ts:688



---
url: /api/reactlynx-testing-library/Function.getByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByTestId

# Function: getByTestId()

```ts
function getByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:692



---
url: /api/reactlynx-testing-library/Function.getByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByText

# Function: getByText()

```ts
function getByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<GetByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByText`](/api/reactlynx-testing-library/TypeAlias.GetByText.md)\<`T`>>

## Defined in

index.d.ts:702



---
url: /api/reactlynx-testing-library/Function.getByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getByTitle

# Function: getByTitle()

```ts
function getByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<GetByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`GetByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:706



---
url: /api/reactlynx-testing-library/Function.getConfig.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getConfig

# Function: getConfig()

```ts
function getConfig(): Config
```

## Returns

[`Config`](/api/reactlynx-testing-library/Interface.Config.md)

## Defined in

index.d.ts:710



---
url: /api/reactlynx-testing-library/Function.getDefaultNormalizer.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getDefaultNormalizer

# Function: getDefaultNormalizer()

```ts
function getDefaultNormalizer(options?: DefaultNormalizerOptions): NormalizerFn
```

## Parameters

| Parameter  | Type                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `options`? | [`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md) |

## Returns

[`NormalizerFn`](/api/reactlynx-testing-library/TypeAlias.NormalizerFn.md)

## Defined in

index.d.ts:712



---
url: /api/reactlynx-testing-library/Function.getElementError.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getElementError

# Function: getElementError()

```ts
function getElementError(message: null | string, container: HTMLElement): Error
```

## Parameters

| Parameter   | Type               |
| ----------- | ------------------ |
| `message`   | `null` \| `string` |
| `container` | `HTMLElement`      |

## Returns

`Error`

## Defined in

index.d.ts:716



---
url: /api/reactlynx-testing-library/Function.getNodeText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getNodeText

# Function: getNodeText()

```ts
function getNodeText(node: HTMLElement): string
```

## Parameters

| Parameter | Type          |
| --------- | ------------- |
| `node`    | `HTMLElement` |

## Returns

`string`

## Defined in

index.d.ts:726



---
url: /api/reactlynx-testing-library/Function.getQueriesForElement.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getQueriesForElement

# Function: getQueriesForElement()

```ts
function getQueriesForElement<QueriesToBind, T>(element: HTMLElement, queriesToBind?: T): BoundFunctions<T>
```

## Type Parameters

| Type Parameter                                                                             | Default type                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `QueriesToBind` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |
| `T` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md)             | `QueriesToBind`                                                           |

## Parameters

| Parameter        | Type          |
| ---------------- | ------------- |
| `element`        | `HTMLElement` |
| `queriesToBind`? | `T`           |

## Returns

[`BoundFunctions`](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)\<`T`>

## Defined in

index.d.ts:728



---
url: /api/reactlynx-testing-library/Function.getRoles.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getRoles

# Function: getRoles()

```ts
function getRoles(container: HTMLElement): object
```

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |

## Returns

`object`

## Defined in

index.d.ts:734



---
url: /api/reactlynx-testing-library/Function.getSuggestedQuery.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / getSuggestedQuery

# Function: getSuggestedQuery()

```ts
function getSuggestedQuery(
   element: HTMLElement, 
   variant?: Variant, 
   method?: Method): Suggestion | undefined
```

## Parameters

| Parameter  | Type                                                             |
| ---------- | ---------------------------------------------------------------- |
| `element`  | `HTMLElement`                                                    |
| `variant`? | [`Variant`](/api/reactlynx-testing-library/TypeAlias.Variant.md) |
| `method`?  | [`Method`](/api/reactlynx-testing-library/TypeAlias.Method.md)   |

## Returns

[`Suggestion`](/api/reactlynx-testing-library/Interface.Suggestion.md) | `undefined`

## Defined in

index.d.ts:738



---
url: /api/reactlynx-testing-library/Function.isInaccessible.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / isInaccessible

# Function: isInaccessible()

```ts
function isInaccessible(element: Element): boolean
```

[https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible](https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible)

## Parameters

| Parameter | Type      |
| --------- | --------- |
| `element` | `Element` |

## Returns

`boolean`

## Defined in

index.d.ts:827



---
url: /api/reactlynx-testing-library/Function.logDOM.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / logDOM

# Function: logDOM()

```ts
function logDOM(
   dom?: any, 
   maxLength?: number, 
   options?: PrettyDOMOptions): void
```

## Parameters

| Parameter    | Type                                                                               |
| ------------ | ---------------------------------------------------------------------------------- |
| `dom`?       | `any`                                                                              |
| `maxLength`? | `number`                                                                           |
| `options`?   | [`PrettyDOMOptions`](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md) |

## Returns

`void`

## Defined in

index.d.ts:829



---
url: /api/reactlynx-testing-library/Function.logRoles.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / logRoles

# Function: logRoles()

```ts
function logRoles(container: HTMLElement, options?: LogRolesOptions): string
```

## Parameters

| Parameter   | Type                                                                             |
| ----------- | -------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                    |
| `options`?  | [`LogRolesOptions`](/api/reactlynx-testing-library/Interface.LogRolesOptions.md) |

## Returns

`string`

## Defined in

index.d.ts:835



---
url: /api/reactlynx-testing-library/Function.prettyDOM.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / prettyDOM

# Function: prettyDOM()

```ts
function prettyDOM(
   dom?: any, 
   maxLength?: number, 
   options?: PrettyDOMOptions): string | false
```

## Parameters

| Parameter    | Type                                                                               |
| ------------ | ---------------------------------------------------------------------------------- |
| `dom`?       | `any`                                                                              |
| `maxLength`? | `number`                                                                           |
| `options`?   | [`PrettyDOMOptions`](/api/reactlynx-testing-library/Interface.PrettyDOMOptions.md) |

## Returns

`string` | `false`

## Defined in

index.d.ts:1033



---
url: /api/reactlynx-testing-library/Function.queryAllByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByAltText

# Function: queryAllByAltText()

```ts
function queryAllByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1134



---
url: /api/reactlynx-testing-library/Function.queryAllByAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByAttribute

# Function: queryAllByAttribute()

```ts
function queryAllByAttribute(
   attribute: string, 
   container: HTMLElement, 
   id: Matcher, 
   options?: MatcherOptions): HTMLElement[]
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement`\[]

## Defined in

index.d.ts:1138



---
url: /api/reactlynx-testing-library/Function.queryAllByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByDisplayValue

# Function: queryAllByDisplayValue()

```ts
function queryAllByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1140



---
url: /api/reactlynx-testing-library/Function.queryAllByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByLabelText

# Function: queryAllByLabelText()

```ts
function queryAllByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:1144



---
url: /api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByPlaceholderText

# Function: queryAllByPlaceholderText()

```ts
function queryAllByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1148



---
url: /api/reactlynx-testing-library/Function.queryAllByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByRole

# Function: queryAllByRole()

```ts
function queryAllByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<AllByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`AllByRole`](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)\<`T`>>

## Defined in

index.d.ts:1152



---
url: /api/reactlynx-testing-library/Function.queryAllByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByTestId

# Function: queryAllByTestId()

```ts
function queryAllByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1156



---
url: /api/reactlynx-testing-library/Function.queryAllByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByText

# Function: queryAllByText()

```ts
function queryAllByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<AllByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByText`](/api/reactlynx-testing-library/TypeAlias.AllByText.md)\<`T`>>

## Defined in

index.d.ts:1160



---
url: /api/reactlynx-testing-library/Function.queryAllByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryAllByTitle

# Function: queryAllByTitle()

```ts
function queryAllByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<AllByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`AllByBoundAttribute`](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1164



---
url: /api/reactlynx-testing-library/Function.queryByAltText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByAltText

# Function: queryByAltText()

```ts
function queryByAltText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1175



---
url: /api/reactlynx-testing-library/Function.queryByAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByAttribute

# Function: queryByAttribute()

```ts
function queryByAttribute(
   attribute: string, 
   container: HTMLElement, 
   id: Matcher, 
   options?: MatcherOptions): null | HTMLElement
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`null` | `HTMLElement`

## Defined in

index.d.ts:1186



---
url: /api/reactlynx-testing-library/Function.queryByDisplayValue.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByDisplayValue

# Function: queryByDisplayValue()

```ts
function queryByDisplayValue<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1194



---
url: /api/reactlynx-testing-library/Function.queryByLabelText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByLabelText

# Function: queryByLabelText()

```ts
function queryByLabelText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<QueryByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByText`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)\<`T`>>

## Defined in

index.d.ts:1198



---
url: /api/reactlynx-testing-library/Function.queryByPlaceholderText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByPlaceholderText

# Function: queryByPlaceholderText()

```ts
function queryByPlaceholderText<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1202



---
url: /api/reactlynx-testing-library/Function.queryByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByRole

# Function: queryByRole()

```ts
function queryByRole<T>(...args: [HTMLElement, any, ByRoleOptions]): ReturnType<QueryByRole<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                  |
| --------- | ----------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, `any`, [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)] |

## Returns

`ReturnType`\<[`QueryByRole`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)\<`T`>>

## Defined in

index.d.ts:1212



---
url: /api/reactlynx-testing-library/Function.queryByTestId.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByTestId

# Function: queryByTestId()

```ts
function queryByTestId<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1216



---
url: /api/reactlynx-testing-library/Function.queryByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByText

# Function: queryByText()

```ts
function queryByText<T>(...args: [HTMLElement, Matcher, SelectorMatcherOptions]): ReturnType<QueryByText<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                                                            |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByText`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)\<`T`>>

## Defined in

index.d.ts:1226



---
url: /api/reactlynx-testing-library/Function.queryByTitle.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryByTitle

# Function: queryByTitle()

```ts
function queryByTitle<T>(...args: [HTMLElement, Matcher, MatcherOptions]): ReturnType<QueryByBoundAttribute<T>>
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter | Type                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...`args` | \[`HTMLElement`, [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md), [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)] |

## Returns

`ReturnType`\<[`QueryByBoundAttribute`](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md)\<`T`>>

## Defined in

index.d.ts:1230



---
url: /api/reactlynx-testing-library/Function.render.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / render

# Function: render()

```ts
function render<Q>(ui: ReactNode, options?: RenderOptions<Q>): RenderResult<Q>
```

Render into the page. It should be used with cleanup.

## Type Parameters

| Type Parameter                                                                 |
| ------------------------------------------------------------------------------ |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) |

## Parameters

| Parameter  | Type                                                                               |
| ---------- | ---------------------------------------------------------------------------------- |
| `ui`       | `ReactNode`                                                                        |
| `options`? | [`RenderOptions`](/api/reactlynx-testing-library/Interface.RenderOptions.md)\<`Q`> |

## Returns

[`RenderResult`](/api/reactlynx-testing-library/TypeAlias.RenderResult.md)\<`Q`>

## Example

```ts
import { render} from '@lynx-js/react/testing-library'

const WrapperComponent = ({ children }) => (
    <view data-testid='wrapper'>{children}</view>
);
const Comp = () => {
  return <view data-testid='inner' style="background-color: yellow;" />;
};
const { container, getByTestId } = render(<Comp />, {
  wrapper: WrapperComponent,
});
expect(getByTestId('wrapper')).toBeInTheDocument();
expect(container.firstChild).toMatchInlineSnapshot(`
  <view
    data-testid="wrapper"
  >
    <view
      data-testid="inner"
      style="background-color: yellow;"
    />
  </view>
`);
```

## Defined in

index.d.ts:1300



---
url: /api/reactlynx-testing-library/Function.renderHook.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / renderHook

# Function: renderHook()

```ts
function renderHook<Result, Props>(render: (initialProps: Props) => Result, options?: RenderHookOptions<Props>): RenderHookResult<Result, Props>
```

Allows you to render a hook within a test React component without having to
create that component yourself.

## Type Parameters

| Type Parameter |
| -------------- |
| `Result`       |
| `Props`        |

## Parameters

| Parameter  | Type                                                                                           |
| ---------- | ---------------------------------------------------------------------------------------------- |
| `render`   | (`initialProps`: `Props`) => `Result`                                                          |
| `options`? | [`RenderHookOptions`](/api/reactlynx-testing-library/Interface.RenderHookOptions.md)\<`Props`> |

## Returns

[`RenderHookResult`](/api/reactlynx-testing-library/Interface.RenderHookResult.md)\<`Result`, `Props`>

## Example

```ts
import { renderHook } from '@lynx-js/react/testing-library'

const Context = createContext('default');
function Wrapper({ children }) {
  return <Context.Provider value='provided'>{children}</Context.Provider>;
}
const { result } = renderHook(
  () => {
    return useContext(Context);
  },
  {
    wrapper: Wrapper,
  },
);

expect(result.current).toEqual('provided');
```

## Defined in

index.d.ts:1332



---
url: /api/reactlynx-testing-library/Function.waitFor.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitFor

# Function: waitFor()

```ts
function waitFor<T>(callback: () => T | Promise<T>, options?: waitForOptions): Promise<T>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter  | Type                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| `callback` | () => `T` \| `Promise`\<`T`>                                                   |
| `options`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:1540



---
url: /api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitForElementToBeRemoved

# Function: waitForElementToBeRemoved()

```ts
function waitForElementToBeRemoved<T>(callback: T | () => T, options?: waitForOptions): Promise<void>
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Parameters

| Parameter  | Type                                                                           |
| ---------- | ------------------------------------------------------------------------------ |
| `callback` | `T` \| () => `T`                                                               |
| `options`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`void`>

## Defined in

index.d.ts:1545



---
url: /api/reactlynx-testing-library/Function.waitSchedule.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitSchedule

# Function: ~~waitSchedule()~~

```ts
function waitSchedule(): Promise<void>
```

Wait for the next event loop.

It will be useful when you want to wait for the next event loop to finish.

## Returns

`Promise`\<`void`>

## Deprecated

Please use `act` instead

## Defined in

index.d.ts:1565



---
url: /api/reactlynx-testing-library/Function.within.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / within

# Function: within()

```ts
function within<QueriesToBind, T>(element: HTMLElement, queriesToBind?: T): BoundFunctions<T>
```

## Type Parameters

| Type Parameter                                                                             | Default type                                                              |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `QueriesToBind` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |
| `T` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md)             | `QueriesToBind`                                                           |

## Parameters

| Parameter        | Type          |
| ---------------- | ------------- |
| `element`        | `HTMLElement` |
| `queriesToBind`? | `T`           |

## Returns

[`BoundFunctions`](/api/reactlynx-testing-library/TypeAlias.BoundFunctions.md)\<`T`>

## Defined in

index.d.ts:1567



---
url: /api/reactlynx-testing-library/Interface.ByRoleOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ByRoleOptions

# Interface: ByRoleOptions

## Properties

### busy?

```ts
optional busy: boolean;
```

If true only includes elements in the query set that are marked as
busy in the accessibility tree, i.e., `aria-busy="true"`

#### Defined in

index.d.ts:227

***

### checked?

```ts
optional checked: boolean;
```

If true only includes elements in the query set that are marked as
checked in the accessibility tree, i.e., `aria-checked="true"`

#### Defined in

index.d.ts:232

***

### current?

```ts
optional current: string | boolean;
```

Filters elements by their `aria-current` state. `true` and `false` match `aria-current="true"` and `aria-current="false"` (as well as a missing `aria-current` attribute) respectively.

#### Defined in

index.d.ts:241

***

### description?

```ts
optional description: string | RegExp | (accessibleDescription: string, element: Element) => boolean;
```

Only considers elements with the specified accessible description.

#### Defined in

index.d.ts:274

***

### expanded?

```ts
optional expanded: boolean;
```

If true only includes elements in the query set that are marked as
expanded in the accessibility tree, i.e., `aria-expanded="true"`

#### Defined in

index.d.ts:246

***

### hidden?

```ts
optional hidden: boolean;
```

If true includes elements in the query set that are usually excluded from
the accessibility tree. `role="none"` or `role="presentation"` are included
in either case.

#### Defined in

index.d.ts:217

***

### level?

```ts
optional level: number;
```

Includes elements with the `"heading"` role matching the indicated level,
either by the semantic HTML heading elements `<h1>-<h6>` or matching
the `aria-level` attribute.

#### Defined in

index.d.ts:252

***

### name?

```ts
optional name: string | RegExp | (accessibleName: string, element: Element) => boolean;
```

Only considers elements with the specified accessible name.

#### Defined in

index.d.ts:267

***

### pressed?

```ts
optional pressed: boolean;
```

If true only includes elements in the query set that are marked as
pressed in the accessibility tree, i.e., `aria-pressed="true"`

#### Defined in

index.d.ts:237

***

### queryFallbacks?

```ts
optional queryFallbacks: boolean;
```

Includes every role used in the `role` attribute
For example \*ByRole('progressbar', \{queryFallbacks: true})` will find <div role="meter progressbar">`.

#### Defined in

index.d.ts:263

***

### selected?

```ts
optional selected: boolean;
```

If true only includes elements in the query set that are marked as
selected in the accessibility tree, i.e., `aria-selected="true"`

#### Defined in

index.d.ts:222

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Defined in

index.d.ts:211

***

### value?

```ts
optional value: object;
```

#### max?

```ts
optional max: number;
```

#### min?

```ts
optional min: number;
```

#### now?

```ts
optional now: number;
```

#### text?

```ts
optional text: Matcher;
```

#### Defined in

index.d.ts:253



---
url: /api/reactlynx-testing-library/Interface.Config.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Config

# Interface: Config

## Properties

### asyncUtilTimeout

```ts
asyncUtilTimeout: number;
```

#### Defined in

index.d.ts:300

***

### computedStyleSupportsPseudoElements

```ts
computedStyleSupportsPseudoElements: boolean;
```

#### Defined in

index.d.ts:301

***

### defaultHidden

```ts
defaultHidden: boolean;
```

#### Defined in

index.d.ts:302

***

### defaultIgnore

```ts
defaultIgnore: string;
```

default value for the `ignore` option in `ByText` queries

#### Defined in

index.d.ts:304

***

### getElementError()

```ts
getElementError: (message: null | string, container: Element) => Error;
```

#### Parameters

| Parameter   | Type               |
| ----------- | ------------------ |
| `message`   | `null` \| `string` |
| `container` | `Element`          |

#### Returns

`Error`

#### Defined in

index.d.ts:307

***

### showOriginalStackTrace

```ts
showOriginalStackTrace: boolean;
```

#### Defined in

index.d.ts:305

***

### testIdAttribute

```ts
testIdAttribute: string;
```

#### Defined in

index.d.ts:290

***

### throwSuggestions

```ts
throwSuggestions: boolean;
```

#### Defined in

index.d.ts:306

## Methods

### asyncWrapper()

```ts
asyncWrapper(cb: (...args: any[]) => any): Promise<any>
```

#### Parameters

| Parameter | Type                           |
| --------- | ------------------------------ |
| `cb`      | (...`args`: `any`\[]) => `any` |

#### Returns

`Promise`\<`any`>

#### Defined in

index.d.ts:297

***

### eventWrapper()

```ts
eventWrapper(cb: (...args: any[]) => any): void
```

#### Parameters

| Parameter | Type                           |
| --------- | ------------------------------ |
| `cb`      | (...`args`: `any`\[]) => `any` |

#### Returns

`void`

#### Defined in

index.d.ts:299

***

### unstable\_advanceTimersWrapper()

```ts
unstable_advanceTimersWrapper(cb: (...args: unknown[]) => unknown): unknown
```

WARNING: `unstable` prefix means this API may change in patch and minor releases.

#### Parameters

| Parameter | Type                                   | Description |
| --------- | -------------------------------------- | ----------- |
| `cb`      | (...`args`: `unknown`\[]) => `unknown` |             |

#### Returns

`unknown`

#### Defined in

index.d.ts:295



---
url: /api/reactlynx-testing-library/Interface.ConfigFn.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ConfigFn

# Interface: ConfigFn()

```ts
interface ConfigFn(existingConfig: Config): Partial<Config>
```

## Parameters

| Parameter        | Type                                                           |
| ---------------- | -------------------------------------------------------------- |
| `existingConfig` | [`Config`](/api/reactlynx-testing-library/Interface.Config.md) |

## Returns

`Partial`\<[`Config`](/api/reactlynx-testing-library/Interface.Config.md)>

## Defined in

index.d.ts:311



---
url: /api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / DefaultNormalizerOptions

# Interface: DefaultNormalizerOptions

## Extended by

- [`NormalizerOptions`](/api/reactlynx-testing-library/Interface.NormalizerOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

#### Defined in

index.d.ts:334

***

### trim?

```ts
optional trim: boolean;
```

#### Defined in

index.d.ts:333



---
url: /api/reactlynx-testing-library/Interface.LogRolesOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / LogRolesOptions

# Interface: LogRolesOptions

## Properties

### hidden?

```ts
optional hidden: boolean;
```

#### Defined in

index.d.ts:841



---
url: /api/reactlynx-testing-library/Interface.MatcherOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / MatcherOptions

# Interface: MatcherOptions

## Extended by

- [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Defined in

index.d.ts:998

***

### exact?

```ts
optional exact: boolean;
```

#### Defined in

index.d.ts:994

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Defined in

index.d.ts:999

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Defined in

index.d.ts:1001

***

### trim?

```ts
optional trim: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Defined in

index.d.ts:996



---
url: /api/reactlynx-testing-library/Interface.NormalizerOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / NormalizerOptions

# Interface: NormalizerOptions

## Extends

- [`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

#### Inherited from

[`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md).[`collapseWhitespace`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#collapsewhitespace)

#### Defined in

index.d.ts:334

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Defined in

index.d.ts:1025

***

### trim?

```ts
optional trim: boolean;
```

#### Inherited from

[`DefaultNormalizerOptions`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md).[`trim`](/api/reactlynx-testing-library/Interface.DefaultNormalizerOptions.md#trim)

#### Defined in

index.d.ts:333



---
url: /api/reactlynx-testing-library/Interface.PrettyDOMOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / PrettyDOMOptions

# Interface: PrettyDOMOptions

## Extends

- [`act`](/api/reactlynx-testing-library/Variable.act.md)

## Properties

### filterNode()?

```ts
optional filterNode: (node: Node) => boolean;
```

Given a `Node` return `false` if you wish to ignore that node in the output.
By default, ignores `<style />`, `<script />` and comment nodes.

#### Parameters

| Parameter | Type   |
| --------- | ------ |
| `node`    | `Node` |

#### Returns

`boolean`

#### Defined in

index.d.ts:1044



---
url: /api/reactlynx-testing-library/Interface.Queries.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Queries

# Interface: Queries

## Indexable

\[`T`: `string`]: [`Query`](/api/reactlynx-testing-library/TypeAlias.Query.md)



---
url: /api/reactlynx-testing-library/Interface.QueryOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryOptions

# Interface: QueryOptions

## Indexable

\[`key`: `string`]: `RegExp` | `boolean`



---
url: /api/reactlynx-testing-library/Interface.RenderHookOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderHookOptions

# Interface: RenderHookOptions\<Props>

The options for [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)

## Type Parameters

| Type Parameter |
| -------------- |
| `Props`        |

## Properties

### initialProps?

```ts
optional initialProps: Props;
```

The argument passed to the renderHook callback. Can be useful if you plan
to use the rerender utility to change the values passed to your hook.

#### Defined in

index.d.ts:1347

***

### wrapper?

```ts
optional wrapper: JSXElementConstructor<object>;
```

Pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating
reusable custom render functions for common data providers. See setup for examples.

#### Type declaration

##### children

```ts
children: ReactNode;
```

#### Example

```ts
import { renderHook } from '@lynx-js/react/testing-library'
import { ThemeProvider } from 'my-ui-lib'
import { TranslationProvider } from 'my-i18n-lib'
import defaultStrings from 'i18n/en-x-default'

const AllTheProviders = ({children}) => {
  return (
    <ThemeProvider theme="light">
      <TranslationProvider messages={defaultStrings}>
        {children}
      </TranslationProvider>
    </ThemeProvider>
  )
}

const customRenderHook = (ui, options) =>
  renderHook(ui, { wrapper: AllTheProviders, ...options })

// re-export everything
export * from '@lynx-js/react/testing-library'

// override renderHook method
export { customRender as renderHook }
```

#### Defined in

index.d.ts:1380



---
url: /api/reactlynx-testing-library/Interface.RenderHookResult.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderHookResult

# Interface: RenderHookResult\<Result, Props>

The result of [renderHook](/api/reactlynx-testing-library/Function.renderHook.md)

## Type Parameters

| Type Parameter |
| -------------- |
| `Result`       |
| `Props`        |

## Properties

### rerender()

```ts
rerender: (props?: Props) => void;
```

Triggers a re-render. The props will be passed to your renderHook callback.

#### Parameters

| Parameter | Type    |
| --------- | ------- |
| `props`?  | `Props` |

#### Returns

`void`

#### Defined in

index.d.ts:1393

***

### result

```ts
result: object;
```

This is a stable reference to the latest value returned by your renderHook
callback

#### current

```ts
current: Result;
```

The value returned by your renderHook callback

#### Defined in

index.d.ts:1398

***

### unmount()

```ts
unmount: () => void;
```

Unmounts the test component. This is useful for when you need to test
any cleanup your useEffects have.

#### Returns

`void`

#### Defined in

index.d.ts:1408



---
url: /api/reactlynx-testing-library/Interface.RenderOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderOptions

# Interface: RenderOptions\<Q>

The options for [render](/api/reactlynx-testing-library/Function.render.md).

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Properties

### enableBackgroundThread?

```ts
optional enableBackgroundThread: boolean;
```

Render your component in the background thread or not.

Note that all user code in the top level will be executed in the background thread by default. (eg. `__BACKGROUND__` is `true` in the top level)

#### Default Value

```ts
true
```

#### Defined in

index.d.ts:1482

***

### enableMainThread?

```ts
optional enableMainThread: boolean;
```

Render your component in the main thread or not.

It is recommended to use this option only when you need to test the [IFR](/guide/interaction/ifr.md) behavior.

#### Default Value

```ts
false
```

#### Defined in

index.d.ts:1474

***

### queries?

```ts
optional queries: Q;
```

Queries to bind. Overrides the default set from DOM Testing Library unless merged.

#### Example

```ts
// Example, a function to traverse table contents
import * as tableQueries from 'my-table-query-library'
import { queries } from '@lynx-js/react/testing-library'

const { getByRowColumn, getByText } = render(<MyTable />, {
  queries: {...queries, ...tableQueries},
})

```

#### Defined in

index.d.ts:1433

***

### wrapper?

```ts
optional wrapper: JSXElementConstructor<object>;
```

Pass a React Component as the wrapper option to have it rendered around the inner element. This is most useful for creating
reusable custom render functions for common data providers. See setup for examples.

#### Type declaration

##### children

```ts
children: ReactNode;
```

#### Example

```ts
import { render } from '@lynx-js/react/testing-library'
import { ThemeProvider } from 'my-ui-lib'
import { TranslationProvider } from 'my-i18n-lib'
import defaultStrings from 'i18n/en-x-default'

const AllTheProviders = ({children}) => {
  return (
    <ThemeProvider theme="light">
      <TranslationProvider messages={defaultStrings}>
        {children}
      </TranslationProvider>
    </ThemeProvider>
  )
}

const customRender = (ui, options) =>
  render(ui, { wrapper: AllTheProviders, ...options })

// re-export everything
export * from '@lynx-js/react/testing-library'

// override render method
export { customRender as render }
```

#### Defined in

index.d.ts:1466



---
url: /api/reactlynx-testing-library/Interface.Suggestion.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Suggestion

# Interface: Suggestion

## Properties

### queryArgs

```ts
queryArgs: QueryArgs;
```

#### Defined in

index.d.ts:1526

***

### queryMethod

```ts
queryMethod: string;
```

#### Defined in

index.d.ts:1525

***

### queryName

```ts
queryName: string;
```

#### Defined in

index.d.ts:1524

***

### variant

```ts
variant: string;
```

#### Defined in

index.d.ts:1527

***

### warning?

```ts
optional warning: string;
```

#### Defined in

index.d.ts:1528

## Methods

### toString()

```ts
toString(): string
```

#### Returns

`string`

#### Defined in

index.d.ts:1529



---
url: /api/reactlynx-testing-library/Interface.waitForOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / waitForOptions

# Interface: waitForOptions

## Properties

### container?

```ts
optional container: HTMLElement;
```

#### Defined in

index.d.ts:1551

***

### interval?

```ts
optional interval: number;
```

#### Defined in

index.d.ts:1553

***

### mutationObserverOptions?

```ts
optional mutationObserverOptions: any;
```

#### Defined in

index.d.ts:1555

***

### onTimeout()?

```ts
optional onTimeout: (error: Error) => Error;
```

#### Parameters

| Parameter | Type    |
| --------- | ------- |
| `error`   | `Error` |

#### Returns

`Error`

#### Defined in

index.d.ts:1554

***

### timeout?

```ts
optional timeout: number;
```

#### Defined in

index.d.ts:1552



---
url: /api/reactlynx-testing-library/Namespace.queries.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queries

# queries

## Index

### Type Aliases

| Type alias                                                                                         | Description |
| -------------------------------------------------------------------------------------------------- | ----------- |
| [QueryByBoundAttribute](/api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md) | -           |
| [QueryByRole](/api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md)                     | -           |
| [QueryByText](/api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md)                     | -           |

## References

### AllByBoundAttribute

Re-exports [AllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md)

***

### AllByRole

Re-exports [AllByRole](/api/reactlynx-testing-library/TypeAlias.AllByRole.md)

***

### AllByText

Re-exports [AllByText](/api/reactlynx-testing-library/TypeAlias.AllByText.md)

***

### ByRoleOptions

Re-exports [ByRoleOptions](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)

***

### findAllByAltText

Re-exports [findAllByAltText](/api/reactlynx-testing-library/Function.findAllByAltText.md)

***

### FindAllByBoundAttribute

Re-exports [FindAllByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md)

***

### findAllByDisplayValue

Re-exports [findAllByDisplayValue](/api/reactlynx-testing-library/Function.findAllByDisplayValue.md)

***

### findAllByLabelText

Re-exports [findAllByLabelText](/api/reactlynx-testing-library/Function.findAllByLabelText.md)

***

### findAllByPlaceholderText

Re-exports [findAllByPlaceholderText](/api/reactlynx-testing-library/Function.findAllByPlaceholderText.md)

***

### findAllByRole

Re-exports [findAllByRole](/api/reactlynx-testing-library/Function.findAllByRole.md)

***

### FindAllByRole

Re-exports [FindAllByRole](/api/reactlynx-testing-library/TypeAlias.FindAllByRole.md)

***

### findAllByTestId

Re-exports [findAllByTestId](/api/reactlynx-testing-library/Function.findAllByTestId.md)

***

### findAllByText

Re-exports [findAllByText](/api/reactlynx-testing-library/Function.findAllByText.md)

***

### FindAllByText

Re-exports [FindAllByText](/api/reactlynx-testing-library/TypeAlias.FindAllByText.md)

***

### findAllByTitle

Re-exports [findAllByTitle](/api/reactlynx-testing-library/Function.findAllByTitle.md)

***

### findByAltText

Re-exports [findByAltText](/api/reactlynx-testing-library/Function.findByAltText.md)

***

### FindByBoundAttribute

Re-exports [FindByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md)

***

### findByDisplayValue

Re-exports [findByDisplayValue](/api/reactlynx-testing-library/Function.findByDisplayValue.md)

***

### findByLabelText

Re-exports [findByLabelText](/api/reactlynx-testing-library/Function.findByLabelText.md)

***

### findByPlaceholderText

Re-exports [findByPlaceholderText](/api/reactlynx-testing-library/Function.findByPlaceholderText.md)

***

### findByRole

Re-exports [findByRole](/api/reactlynx-testing-library/Function.findByRole.md)

***

### FindByRole

Re-exports [FindByRole](/api/reactlynx-testing-library/TypeAlias.FindByRole.md)

***

### findByTestId

Re-exports [findByTestId](/api/reactlynx-testing-library/Function.findByTestId.md)

***

### findByText

Re-exports [findByText](/api/reactlynx-testing-library/Function.findByText.md)

***

### FindByText

Re-exports [FindByText](/api/reactlynx-testing-library/TypeAlias.FindByText.md)

***

### findByTitle

Re-exports [findByTitle](/api/reactlynx-testing-library/Function.findByTitle.md)

***

### getAllByAltText

Re-exports [getAllByAltText](/api/reactlynx-testing-library/Function.getAllByAltText.md)

***

### getAllByDisplayValue

Re-exports [getAllByDisplayValue](/api/reactlynx-testing-library/Function.getAllByDisplayValue.md)

***

### getAllByLabelText

Re-exports [getAllByLabelText](/api/reactlynx-testing-library/Function.getAllByLabelText.md)

***

### getAllByPlaceholderText

Re-exports [getAllByPlaceholderText](/api/reactlynx-testing-library/Function.getAllByPlaceholderText.md)

***

### getAllByRole

Re-exports [getAllByRole](/api/reactlynx-testing-library/Function.getAllByRole.md)

***

### getAllByTestId

Re-exports [getAllByTestId](/api/reactlynx-testing-library/Function.getAllByTestId.md)

***

### getAllByText

Re-exports [getAllByText](/api/reactlynx-testing-library/Function.getAllByText.md)

***

### getAllByTitle

Re-exports [getAllByTitle](/api/reactlynx-testing-library/Function.getAllByTitle.md)

***

### getByAltText

Re-exports [getByAltText](/api/reactlynx-testing-library/Function.getByAltText.md)

***

### GetByBoundAttribute

Re-exports [GetByBoundAttribute](/api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md)

***

### getByDisplayValue

Re-exports [getByDisplayValue](/api/reactlynx-testing-library/Function.getByDisplayValue.md)

***

### getByLabelText

Re-exports [getByLabelText](/api/reactlynx-testing-library/Function.getByLabelText.md)

***

### getByPlaceholderText

Re-exports [getByPlaceholderText](/api/reactlynx-testing-library/Function.getByPlaceholderText.md)

***

### getByRole

Re-exports [getByRole](/api/reactlynx-testing-library/Function.getByRole.md)

***

### GetByRole

Re-exports [GetByRole](/api/reactlynx-testing-library/TypeAlias.GetByRole.md)

***

### getByTestId

Re-exports [getByTestId](/api/reactlynx-testing-library/Function.getByTestId.md)

***

### getByText

Re-exports [getByText](/api/reactlynx-testing-library/Function.getByText.md)

***

### GetByText

Re-exports [GetByText](/api/reactlynx-testing-library/TypeAlias.GetByText.md)

***

### getByTitle

Re-exports [getByTitle](/api/reactlynx-testing-library/Function.getByTitle.md)

***

### queryAllByAltText

Re-exports [queryAllByAltText](/api/reactlynx-testing-library/Function.queryAllByAltText.md)

***

### queryAllByDisplayValue

Re-exports [queryAllByDisplayValue](/api/reactlynx-testing-library/Function.queryAllByDisplayValue.md)

***

### queryAllByLabelText

Re-exports [queryAllByLabelText](/api/reactlynx-testing-library/Function.queryAllByLabelText.md)

***

### queryAllByPlaceholderText

Re-exports [queryAllByPlaceholderText](/api/reactlynx-testing-library/Function.queryAllByPlaceholderText.md)

***

### queryAllByRole

Re-exports [queryAllByRole](/api/reactlynx-testing-library/Function.queryAllByRole.md)

***

### queryAllByTestId

Re-exports [queryAllByTestId](/api/reactlynx-testing-library/Function.queryAllByTestId.md)

***

### queryAllByText

Re-exports [queryAllByText](/api/reactlynx-testing-library/Function.queryAllByText.md)

***

### queryAllByTitle

Re-exports [queryAllByTitle](/api/reactlynx-testing-library/Function.queryAllByTitle.md)

***

### queryByAltText

Re-exports [queryByAltText](/api/reactlynx-testing-library/Function.queryByAltText.md)

***

### queryByDisplayValue

Re-exports [queryByDisplayValue](/api/reactlynx-testing-library/Function.queryByDisplayValue.md)

***

### queryByLabelText

Re-exports [queryByLabelText](/api/reactlynx-testing-library/Function.queryByLabelText.md)

***

### queryByPlaceholderText

Re-exports [queryByPlaceholderText](/api/reactlynx-testing-library/Function.queryByPlaceholderText.md)

***

### queryByRole

Re-exports [queryByRole](/api/reactlynx-testing-library/Function.queryByRole.md)

***

### queryByTestId

Re-exports [queryByTestId](/api/reactlynx-testing-library/Function.queryByTestId.md)

***

### queryByText

Re-exports [queryByText](/api/reactlynx-testing-library/Function.queryByText.md)

***

### queryByTitle

Re-exports [queryByTitle](/api/reactlynx-testing-library/Function.queryByTitle.md)



---
url: /api/reactlynx-testing-library/Namespace.queryHelpers.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / queryHelpers

# queryHelpers

## Index

### Interfaces

| Interface                                                                                                 | Description |
| --------------------------------------------------------------------------------------------------------- | ----------- |
| [SelectorMatcherOptions](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) | -           |

### Type Aliases

| Type alias                                                                          | Description                                                               |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [QueryMethod](/api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md) | query methods have a common call signature. Only the return type differs. |
| [WithSuggest](/api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md) | -                                                                         |

## References

### AllByAttribute

Re-exports [AllByAttribute](/api/reactlynx-testing-library/TypeAlias.AllByAttribute.md)

***

### buildQueries

Re-exports [buildQueries](/api/reactlynx-testing-library/Function.buildQueries.md)

***

### BuiltQueryMethods

Re-exports [BuiltQueryMethods](/api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md)

***

### FindAllBy

Re-exports [FindAllBy](/api/reactlynx-testing-library/TypeAlias.FindAllBy.md)

***

### FindBy

Re-exports [FindBy](/api/reactlynx-testing-library/TypeAlias.FindBy.md)

***

### GetAllBy

Re-exports [GetAllBy](/api/reactlynx-testing-library/TypeAlias.GetAllBy.md)

***

### GetBy

Re-exports [GetBy](/api/reactlynx-testing-library/TypeAlias.GetBy.md)

***

### getElementError

Re-exports [getElementError](/api/reactlynx-testing-library/Function.getElementError.md)

***

### GetErrorFunction

Re-exports [GetErrorFunction](/api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md)

***

### queryAllByAttribute

Re-exports [queryAllByAttribute](/api/reactlynx-testing-library/Function.queryAllByAttribute.md)

***

### QueryBy

Re-exports [QueryBy](/api/reactlynx-testing-library/TypeAlias.QueryBy.md)

***

### queryByAttribute

Re-exports [queryByAttribute](/api/reactlynx-testing-library/Function.queryByAttribute.md)

***

### QueryByAttribute

Re-exports [QueryByAttribute](/api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md)



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByBoundAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByBoundAttribute

# Type Alias: QueryByBoundAttribute()\<T>

```ts
type QueryByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1188



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByRole

# Type Alias: QueryByRole()\<T>

```ts
type QueryByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1206



---
url: /api/reactlynx-testing-library/queries.TypeAlias.QueryByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queries](/api/reactlynx-testing-library/Namespace.queries.md) / QueryByText

# Type Alias: QueryByText()\<T>

```ts
type QueryByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T | null;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T` | `null`

## Defined in

index.d.ts:1220



---
url: /api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / SelectorMatcherOptions

# Interface: SelectorMatcherOptions

## Extends

- [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md)

## Properties

### collapseWhitespace?

```ts
optional collapseWhitespace: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`collapseWhitespace`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#collapsewhitespace)

#### Defined in

index.d.ts:998

***

### exact?

```ts
optional exact: boolean;
```

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`exact`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#exact)

#### Defined in

index.d.ts:994

***

### ignore?

```ts
optional ignore: string | boolean;
```

#### Defined in

index.d.ts:1520

***

### normalizer?

```ts
optional normalizer: NormalizerFn;
```

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`normalizer`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#normalizer)

#### Defined in

index.d.ts:999

***

### selector?

```ts
optional selector: string;
```

#### Defined in

index.d.ts:1519

***

### suggest?

```ts
optional suggest: boolean;
```

suppress suggestions for a specific query

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`suggest`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#suggest)

#### Defined in

index.d.ts:1001

***

### trim?

```ts
optional trim: boolean;
```

Use normalizer with getDefaultNormalizer instead

#### Inherited from

[`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md).[`trim`](/api/reactlynx-testing-library/Interface.MatcherOptions.md#trim)

#### Defined in

index.d.ts:996



---
url: /api/reactlynx-testing-library/queryHelpers.TypeAlias.QueryMethod.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / QueryMethod

# Type Alias: QueryMethod()\<Arguments, Return>

```ts
type QueryMethod<Arguments, Return>: (container: HTMLElement, ...args: Arguments) => Return;
```

query methods have a common call signature. Only the return type differs.

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |
| `Return`                       |

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |
| ...`args`   | `Arguments`   |

## Returns

`Return`

## Defined in

index.d.ts:1259



---
url: /api/reactlynx-testing-library/queryHelpers.TypeAlias.WithSuggest.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / [queryHelpers](/api/reactlynx-testing-library/Namespace.queryHelpers.md) / WithSuggest

# Type Alias: WithSuggest

```ts
type WithSuggest: object;
```

## Type declaration

### suggest?

```ts
optional suggest: boolean;
```

## Defined in

index.d.ts:1569



---
url: /api/reactlynx-testing-library/TypeAlias.AllByAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByAttribute

# Type Alias: AllByAttribute()

```ts
type AllByAttribute: (attribute: string, container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement[];
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement`\[]

## Defined in

index.d.ts:8



---
url: /api/reactlynx-testing-library/TypeAlias.AllByBoundAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByBoundAttribute

# Type Alias: AllByBoundAttribute()\<T>

```ts
type AllByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:15



---
url: /api/reactlynx-testing-library/TypeAlias.AllByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByRole

# Type Alias: AllByRole()\<T>

```ts
type AllByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:21



---
url: /api/reactlynx-testing-library/TypeAlias.AllByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / AllByText

# Type Alias: AllByText()\<T>

```ts
type AllByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T[];
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T`\[]

## Defined in

index.d.ts:27



---
url: /api/reactlynx-testing-library/TypeAlias.BoundFunction.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BoundFunction

# Type Alias: BoundFunction\<T>

```ts
type BoundFunction<T>: T extends (container: HTMLElement, ...args: infer P) => infer R ? (...args: P) => R : never;
```

## Type Parameters

| Type Parameter |
| -------------- |
| `T`            |

## Defined in

index.d.ts:33



---
url: /api/reactlynx-testing-library/TypeAlias.BoundFunctions.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BoundFunctions

# Type Alias: BoundFunctions\<Q>

```ts
type BoundFunctions<Q>: Q extends typeof queries ? object & { [P in keyof Q]: BoundFunction<Q[P]> } : { [P in keyof Q]: BoundFunction<Q[P]> };
```

## Type Parameters

| Type Parameter |
| -------------- |
| `Q`            |

## Defined in

index.d.ts:40



---
url: /api/reactlynx-testing-library/TypeAlias.BuiltQueryMethods.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / BuiltQueryMethods

# Type Alias: BuiltQueryMethods\<Arguments>

```ts
type BuiltQueryMethods<Arguments>: [QueryBy<Arguments>, GetAllBy<Arguments>, GetBy<Arguments>, FindAllBy<Arguments>, FindBy<Arguments>];
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:199



---
url: /api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ByRoleMatcher

# Type Alias: ByRoleMatcher

```ts
type ByRoleMatcher: act | string & object;
```

## Defined in

index.d.ts:207



---
url: /api/reactlynx-testing-library/TypeAlias.CreateFunction.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / CreateFunction

# Type Alias: CreateFunction()

```ts
type CreateFunction: (eventName: string, node: Document | Element | Window | Node, init?: object, options?: object) => Event;
```

## Parameters

| Parameter              | Type                                          |
| ---------------------- | --------------------------------------------- |
| `eventName`            | `string`                                      |
| `node`                 | `Document` \| `Element` \| `Window` \| `Node` |
| `init`?                | `object`                                      |
| `options`?             | `object`                                      |
| `options.defaultInit`? | `object`                                      |
| `options.EventType`?   | `string`                                      |

## Returns

`Event`

## Defined in

index.d.ts:318



---
url: /api/reactlynx-testing-library/TypeAlias.CreateObject.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / CreateObject

# Type Alias: CreateObject

```ts
type CreateObject: { [K in EventType_2]: Function };
```

## Defined in

index.d.ts:325



---
url: /api/reactlynx-testing-library/TypeAlias.ElementTree.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / ElementTree

# Type Alias: ElementTree

```ts
type ElementTree: ReturnType<typeof initElementTree>;
```

The lynx element tree

## Defined in

index.d.ts:341



---
url: /api/reactlynx-testing-library/TypeAlias.EventType.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / EventType

# Type Alias: EventType

```ts
type EventType: 
  | "focus"
  | "blur"
  | "scroll"
  | "wheel"
  | "tap"
  | "longtap"
  | "bgload"
  | "bgerror"
  | "touchstart"
  | "touchmove"
  | "touchcancel"
  | "touchend"
  | "longpress"
  | "transitionstart"
  | "transitioncancel"
  | "transitionend"
  | "animationstart"
  | "animationiteration"
  | "animationcancel"
  | "animationend"
  | "mousedown"
  | "mouseup"
  | "mousemove"
  | "mouseclick"
  | "mousedblclick"
  | "mouselongpress"
  | "keydown"
  | "keyup"
  | "layoutchange"
  | "scrolltoupper"
  | "scrolltolower"
  | "scrollend"
  | "contentsizechanged"
  | "scrolltoupperedge"
  | "scrolltoloweredge"
  | "scrolltonormalstate";
```

## Defined in

index.d.ts:349



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllBy.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllBy

# Type Alias: FindAllBy\<Arguments>

```ts
type FindAllBy<Arguments>: QueryMethod<[Arguments[0], Arguments[1]?, waitForOptions?], Promise<HTMLElement[]>>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:487



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByBoundAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByBoundAttribute

# Type Alias: FindAllByBoundAttribute()\<T>

```ts
type FindAllByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?               | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:496



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByRole

# Type Alias: FindAllByRole()\<T>

```ts
type FindAllByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `role`                   | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)   |
| `options`?               | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)   |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:515



---
url: /api/reactlynx-testing-library/TypeAlias.FindAllByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindAllByText

# Type Alias: FindAllByText()\<T>

```ts
type FindAllByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T[]>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `container`              | `HTMLElement`                                                                                               |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?               | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)                              |

## Returns

`Promise`\<`T`\[]>

## Defined in

index.d.ts:530



---
url: /api/reactlynx-testing-library/TypeAlias.FindBy.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindBy

# Type Alias: FindBy\<Arguments>

```ts
type FindBy<Arguments>: QueryMethod<[Arguments[0], Arguments[1]?, waitForOptions?], Promise<HTMLElement>>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:545



---
url: /api/reactlynx-testing-library/TypeAlias.FindByBoundAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByBoundAttribute

# Type Alias: FindByBoundAttribute()\<T>

```ts
type FindByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?               | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:554



---
url: /api/reactlynx-testing-library/TypeAlias.FindByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByRole

# Type Alias: FindByRole()\<T>

```ts
type FindByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                           |
| ------------------------ | ------------------------------------------------------------------------------ |
| `container`              | `HTMLElement`                                                                  |
| `role`                   | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md)   |
| `options`?               | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md)   |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md) |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:573



---
url: /api/reactlynx-testing-library/TypeAlias.FindByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FindByText

# Type Alias: FindByText()\<T>

```ts
type FindByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions, waitForElementOptions?: waitForOptions) => Promise<T>;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter                | Type                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `container`              | `HTMLElement`                                                                                               |
| `id`                     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?               | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |
| `waitForElementOptions`? | [`waitForOptions`](/api/reactlynx-testing-library/Interface.waitForOptions.md)                              |

## Returns

`Promise`\<`T`>

## Defined in

index.d.ts:588



---
url: /api/reactlynx-testing-library/TypeAlias.FireFunction.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FireFunction

# Type Alias: FireFunction()

```ts
type FireFunction: (element: Document | Element | Window | Node, event: Event) => boolean;
```

## Parameters

| Parameter | Type                                          |
| --------- | --------------------------------------------- |
| `element` | `Document` \| `Element` \| `Window` \| `Node` |
| `event`   | `Event`                                       |

## Returns

`boolean`

## Defined in

index.d.ts:605



---
url: /api/reactlynx-testing-library/TypeAlias.FireObject.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / FireObject

# Type Alias: FireObject

```ts
type FireObject: { [K in EventType]: FireObject_2[EventType_2] };
```

## Defined in

index.d.ts:610



---
url: /api/reactlynx-testing-library/TypeAlias.GetAllBy.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetAllBy

# Type Alias: GetAllBy\<Arguments>

```ts
type GetAllBy<Arguments>: QueryMethod<Arguments, HTMLElement[]>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:621



---
url: /api/reactlynx-testing-library/TypeAlias.GetBy.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetBy

# Type Alias: GetBy\<Arguments>

```ts
type GetBy<Arguments>: QueryMethod<Arguments, HTMLElement>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:658



---
url: /api/reactlynx-testing-library/TypeAlias.GetByBoundAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByBoundAttribute

# Type Alias: GetByBoundAttribute()\<T>

```ts
type GetByBoundAttribute<T>: (container: HTMLElement, id: Matcher, options?: MatcherOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:664



---
url: /api/reactlynx-testing-library/TypeAlias.GetByRole.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByRole

# Type Alias: GetByRole()\<T>

```ts
type GetByRole<T>: (container: HTMLElement, role: ByRoleMatcher, options?: ByRoleOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                         |
| ----------- | ---------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                |
| `role`      | [`ByRoleMatcher`](/api/reactlynx-testing-library/TypeAlias.ByRoleMatcher.md) |
| `options`?  | [`ByRoleOptions`](/api/reactlynx-testing-library/Interface.ByRoleOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:682



---
url: /api/reactlynx-testing-library/TypeAlias.GetByText.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetByText

# Type Alias: GetByText()\<T>

```ts
type GetByText<T>: (container: HTMLElement, id: Matcher, options?: SelectorMatcherOptions) => T;
```

## Type Parameters

| Type Parameter              | Default type  |
| --------------------------- | ------------- |
| `T` _extends_ `HTMLElement` | `HTMLElement` |

## Parameters

| Parameter   | Type                                                                                                        |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `container` | `HTMLElement`                                                                                               |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)                                            |
| `options`?  | [`SelectorMatcherOptions`](/api/reactlynx-testing-library/queryHelpers.Interface.SelectorMatcherOptions.md) |

## Returns

`T`

## Defined in

index.d.ts:696



---
url: /api/reactlynx-testing-library/TypeAlias.GetErrorFunction.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / GetErrorFunction

# Type Alias: GetErrorFunction()\<Arguments>

```ts
type GetErrorFunction<Arguments>: (c: Element | null, ...args: Arguments) => string;
```

## Type Parameters

| Type Parameter                 | Default type |
| ------------------------------ | ------------ |
| `Arguments` _extends_ `any`\[] | \[`string`]  |

## Parameters

| Parameter | Type                |
| --------- | ------------------- |
| `c`       | `Element` \| `null` |
| ...`args` | `Arguments`         |

## Returns

`string`

## Defined in

index.d.ts:721



---
url: /api/reactlynx-testing-library/TypeAlias.Match.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Match

# Type Alias: Match()

```ts
type Match: (textToMatch: string, node: HTMLElement | null, matcher: Matcher, options?: MatcherOptions) => boolean;
```

## Parameters

| Parameter     | Type                                                                           |
| ------------- | ------------------------------------------------------------------------------ |
| `textToMatch` | `string`                                                                       |
| `node`        | `HTMLElement` \| `null`                                                        |
| `matcher`     | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?    | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`boolean`

## Defined in

index.d.ts:979



---
url: /api/reactlynx-testing-library/TypeAlias.Matcher.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Matcher

# Type Alias: Matcher

```ts
type Matcher: MatcherFunction | RegExp | number | string;
```

## Defined in

index.d.ts:986



---
url: /api/reactlynx-testing-library/TypeAlias.MatcherFunction.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / MatcherFunction

# Type Alias: MatcherFunction()

```ts
type MatcherFunction: (content: string, element: Element | null) => boolean;
```

## Parameters

| Parameter | Type                |
| --------- | ------------------- |
| `content` | `string`            |
| `element` | `Element` \| `null` |

## Returns

`boolean`

## Defined in

index.d.ts:988



---
url: /api/reactlynx-testing-library/TypeAlias.Method.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Method

# Type Alias: Method

```ts
type Method: 
  | "AltText"
  | "alttext"
  | "DisplayValue"
  | "displayvalue"
  | "LabelText"
  | "labeltext"
  | "PlaceholderText"
  | "placeholdertext"
  | "Role"
  | "role"
  | "TestId"
  | "testid"
  | "Text"
  | "text"
  | "Title"
  | "title";
```

## Defined in

index.d.ts:1004



---
url: /api/reactlynx-testing-library/TypeAlias.NormalizerFn.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / NormalizerFn

# Type Alias: NormalizerFn()

```ts
type NormalizerFn: (text: string) => string;
```

## Parameters

| Parameter | Type     |
| --------- | -------- |
| `text`    | `string` |

## Returns

`string`

## Defined in

index.d.ts:1022



---
url: /api/reactlynx-testing-library/TypeAlias.Query.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Query

# Type Alias: Query()

```ts
type Query: (container: HTMLElement, ...args: any[]) => 
  | Error
  | HTMLElement
  | HTMLElement[]
  | Promise<HTMLElement[]>
  | Promise<HTMLElement>
  | null;
```

## Parameters

| Parameter   | Type          |
| ----------- | ------------- |
| `container` | `HTMLElement` |
| ...`args`   | `any`\[]      |

## Returns

\| `Error`
\| `HTMLElement`
\| `HTMLElement`\[]
\| `Promise`\<`HTMLElement`\[]>
\| `Promise`\<`HTMLElement`>
\| `null`

## Defined in

index.d.ts:1123



---
url: /api/reactlynx-testing-library/TypeAlias.QueryArgs.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryArgs

# Type Alias: QueryArgs

```ts
type QueryArgs: [string, QueryOptions?];
```

## Defined in

index.d.ts:1168



---
url: /api/reactlynx-testing-library/TypeAlias.QueryBy.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryBy

# Type Alias: QueryBy\<Arguments>

```ts
type QueryBy<Arguments>: QueryMethod<Arguments, HTMLElement | null>;
```

## Type Parameters

| Type Parameter                 |
| ------------------------------ |
| `Arguments` _extends_ `any`\[] |

## Defined in

index.d.ts:1170



---
url: /api/reactlynx-testing-library/TypeAlias.QueryByAttribute.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / QueryByAttribute

# Type Alias: QueryByAttribute()

```ts
type QueryByAttribute: (attribute: string, container: HTMLElement, id: Matcher, options?: MatcherOptions) => HTMLElement | null;
```

## Parameters

| Parameter   | Type                                                                           |
| ----------- | ------------------------------------------------------------------------------ |
| `attribute` | `string`                                                                       |
| `container` | `HTMLElement`                                                                  |
| `id`        | [`Matcher`](/api/reactlynx-testing-library/TypeAlias.Matcher.md)               |
| `options`?  | [`MatcherOptions`](/api/reactlynx-testing-library/Interface.MatcherOptions.md) |

## Returns

`HTMLElement` | `null`

## Defined in

index.d.ts:1179



---
url: /api/reactlynx-testing-library/TypeAlias.RenderResult.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / RenderResult

# Type Alias: RenderResult\<Q>

```ts
type RenderResult<Q>: object & { [P in keyof Q]: BoundFunction<Q[P]> };
```

The result of [render](/api/reactlynx-testing-library/Function.render.md)

## Type declaration

### asFragment()

```ts
asFragment: () => DocumentFragment;
```

#### Returns

`DocumentFragment`

### container

```ts
container: LynxElement;
```

### rerender()

```ts
rerender: (ui: React.ReactNode) => void;
```

#### Parameters

| Parameter | Type              |
| --------- | ----------------- |
| `ui`      | `React.ReactNode` |

#### Returns

`void`

### unmount()

```ts
unmount: () => boolean;
```

#### Returns

`boolean`

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Defined in

index.d.ts:1490



---
url: /api/reactlynx-testing-library/TypeAlias.Screen.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Screen

# Type Alias: Screen\<Q>

```ts
type Screen<Q>: BoundFunctions<Q> & object;
```

## Type declaration

### debug()

```ts
debug: (element?: (Element | HTMLDocument)[] | Element | HTMLDocument, maxLength?: number, options?: act) => void;
```

Convenience function for `pretty-dom` which also allows an array
of elements

#### Parameters

| Parameter    | Type                                                            |
| ------------ | --------------------------------------------------------------- |
| `element`?   | (`Element` \| `HTMLDocument`)\[] \| `Element` \| `HTMLDocument` |
| `maxLength`? | `number`                                                        |
| `options`?   | [`act`](/api/reactlynx-testing-library/Variable.act.md)         |

#### Returns

`void`

### logTestingPlaygroundURL()

```ts
logTestingPlaygroundURL: (element?: Element | HTMLDocument) => string;
```

Convenience function for `Testing Playground` which logs and returns the URL that
can be opened in a browser

#### Parameters

| Parameter  | Type                        |
| ---------- | --------------------------- |
| `element`? | `Element` \| `HTMLDocument` |

#### Returns

`string`

## Type Parameters

| Type Parameter                                                                 | Default type                                                              |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Q` _extends_ [`Queries`](/api/reactlynx-testing-library/Interface.Queries.md) | _typeof_ [`queries`](/api/reactlynx-testing-library/Namespace.queries.md) |

## Defined in

index.d.ts:1497



---
url: /api/reactlynx-testing-library/TypeAlias.Variant.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / Variant

# Type Alias: Variant

```ts
type Variant: 
  | "find"
  | "findAll"
  | "get"
  | "getAll"
  | "query"
  | "queryAll";
```

## Defined in

index.d.ts:1532



---
url: /api/reactlynx-testing-library/Variable.act.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / act

# Variable: act

```ts
act: any;
```



---
url: /api/reactlynx-testing-library/Variable.screen.md
---



[reactlynx-testing-library](/api/reactlynx-testing-library/index.md) / screen

# Variable: screen

```ts
const screen: Screen;
```

## Defined in

index.d.ts:1515



---
url: /api/engine/element-api.md
---

# Overview

## Element PAPIs

### [`__AddClass`](/api/engine/element-api/__AddClass.md)

- [Introduction](/api/engine/element-api/__AddClass.md#introduction)
- [Syntax](/api/engine/element-api/__AddClass.md#syntax)
- [Example](/api/engine/element-api/__AddClass.md#example)

### [`__AddConfig`](/api/engine/element-api/__AddConfig.md)

- [Introduction](/api/engine/element-api/__AddConfig.md#introduction)
- [Syntax](/api/engine/element-api/__AddConfig.md#syntax)
- [Example](/api/engine/element-api/__AddConfig.md#example)

### [`__AddDataset`](/api/engine/element-api/__AddDataset.md)

- [Introduction](/api/engine/element-api/__AddDataset.md#introduction)
- [Syntax](/api/engine/element-api/__AddDataset.md#syntax)
- [Example](/api/engine/element-api/__AddDataset.md#example)

### [`__AddEvent`](/api/engine/element-api/__AddEvent.md)

- [Introduction](/api/engine/element-api/__AddEvent.md#introduction)
- [Syntax](/api/engine/element-api/__AddEvent.md#syntax)
- [Example](/api/engine/element-api/__AddEvent.md#example)

### [`__AddInlineStyle`](/api/engine/element-api/__AddInlineStyle.md)

- [Introduction](/api/engine/element-api/__AddInlineStyle.md#introduction)
- [Syntax](/api/engine/element-api/__AddInlineStyle.md#syntax)
- [Example](/api/engine/element-api/__AddInlineStyle.md#example)

### [`__AppendElement`](/api/engine/element-api/__AppendElement.md)

- [Introduction](/api/engine/element-api/__AppendElement.md#introduction)
- [Syntax](/api/engine/element-api/__AppendElement.md#syntax)
- [Example](/api/engine/element-api/__AppendElement.md#example)

### [`__CreateComponent`](/api/engine/element-api/__CreateComponent.md)

- [Introduction](/api/engine/element-api/__CreateComponent.md#introduction)
- [Syntax](/api/engine/element-api/__CreateComponent.md#syntax)
- [Example](/api/engine/element-api/__CreateComponent.md#example)

### [`__CreateElement`](/api/engine/element-api/__CreateElement.md)

- [Introduction](/api/engine/element-api/__CreateElement.md#introduction)
- [Syntax](/api/engine/element-api/__CreateElement.md#syntax)
- [Example](/api/engine/element-api/__CreateElement.md#example)

### [`__CreatePage`](/api/engine/element-api/__CreatePage.md)

- [Introduction](/api/engine/element-api/__CreatePage.md#introduction)
- [Syntax](/api/engine/element-api/__CreatePage.md#syntax)
- [Example](/api/engine/element-api/__CreatePage.md#example)

### [`__ElementIsEqual`](/api/engine/element-api/__ElementIsEqual.md)

- [Introduction](/api/engine/element-api/__ElementIsEqual.md#introduction)
- [Syntax](/api/engine/element-api/__ElementIsEqual.md#syntax)
- [Example](/api/engine/element-api/__ElementIsEqual.md#example)

### [`__FirstElement`](/api/engine/element-api/__FirstElement.md)

- [Introduction](/api/engine/element-api/__FirstElement.md#introduction)
- [Syntax](/api/engine/element-api/__FirstElement.md#syntax)
- [Example](/api/engine/element-api/__FirstElement.md#example)

### [`__GetAttributes`](/api/engine/element-api/__GetAttributes.md)

- [Introduction](/api/engine/element-api/__GetAttributes.md#introduction)
- [Syntax](/api/engine/element-api/__GetAttributes.md#syntax)
- [Example](/api/engine/element-api/__GetAttributes.md#example)

### [`__GetChildren`](/api/engine/element-api/__GetChildren.md)

- [Introduction](/api/engine/element-api/__GetChildren.md#introduction)
- [Syntax](/api/engine/element-api/__GetChildren.md#syntax)
- [Example](/api/engine/element-api/__GetChildren.md#example)

### [`__GetClasses`](/api/engine/element-api/__GetClasses.md)

- [Introduction](/api/engine/element-api/__GetClasses.md#introduction)
- [Syntax](/api/engine/element-api/__GetClasses.md#syntax)
- [Example](/api/engine/element-api/__GetClasses.md#example)

### [`__GetComponentID`](/api/engine/element-api/__GetComponentID.md)

- [Introduction](/api/engine/element-api/__GetComponentID.md#introduction)
- [Syntax](/api/engine/element-api/__GetComponentID.md#syntax)
- [Example](/api/engine/element-api/__GetComponentID.md#example)

### [`__GetComputedStyleByKey`](/api/engine/element-api/__GetComputedStyleByKey.md)

- [Introduction](/api/engine/element-api/__GetComputedStyleByKey.md#introduction)
- [Syntax](/api/engine/element-api/__GetComputedStyleByKey.md#syntax)
- [Example](/api/engine/element-api/__GetComputedStyleByKey.md#example)
- [Compatability](/api/engine/element-api/__GetComputedStyleByKey.md#compatability)

### [`__GetConfig`](/api/engine/element-api/__GetConfig.md)

- [Introduction](/api/engine/element-api/__GetConfig.md#introduction)
- [Syntax](/api/engine/element-api/__GetConfig.md#syntax)
- [Example](/api/engine/element-api/__GetConfig.md#example)

### [`__GetDataByKey`](/api/engine/element-api/__GetDataByKey.md)

- [Introduction](/api/engine/element-api/__GetDataByKey.md#introduction)
- [Syntax](/api/engine/element-api/__GetDataByKey.md#syntax)
- [Example](/api/engine/element-api/__GetDataByKey.md#example)

### [`__GetDataset`](/api/engine/element-api/__GetDataset.md)

- [Introduction](/api/engine/element-api/__GetDataset.md#introduction)
- [Syntax](/api/engine/element-api/__GetDataset.md#syntax)
- [Example](/api/engine/element-api/__GetDataset.md#example)

### [`__GetElementUniqueID`](/api/engine/element-api/__GetElementUniqueID.md)

- [Introduction](/api/engine/element-api/__GetElementUniqueID.md#introduction)
- [Syntax](/api/engine/element-api/__GetElementUniqueID.md#syntax)
- [Example](/api/engine/element-api/__GetElementUniqueID.md#example)

### [`__GetEvent`](/api/engine/element-api/__GetEvent.md)

- [Introduction](/api/engine/element-api/__GetEvent.md#introduction)
- [Syntax](/api/engine/element-api/__GetEvent.md#syntax)
- [Example](/api/engine/element-api/__GetEvent.md#example)

### [`__GetEvents`](/api/engine/element-api/__GetEvents.md)

- [Introduction](/api/engine/element-api/__GetEvents.md#introduction)
- [Syntax](/api/engine/element-api/__GetEvents.md#syntax)
- [Example](/api/engine/element-api/__GetEvents.md#example)

### [`__GetID`](/api/engine/element-api/__GetID.md)

- [Introduction](/api/engine/element-api/__GetID.md#introduction)
- [Syntax](/api/engine/element-api/__GetID.md#syntax)
- [Example](/api/engine/element-api/__GetID.md#example)

### [`__GetInlineStyles`](/api/engine/element-api/__GetInlineStyles.md)

- [Introduction](/api/engine/element-api/__GetInlineStyles.md#introduction)
- [Syntax](/api/engine/element-api/__GetInlineStyles.md#syntax)
- [Example](/api/engine/element-api/__GetInlineStyles.md#example)

### [`__GetParent`](/api/engine/element-api/__GetParent.md)

- [Introduction](/api/engine/element-api/__GetParent.md#introduction)
- [Syntax](/api/engine/element-api/__GetParent.md#syntax)
- [Example](/api/engine/element-api/__GetParent.md#example)

### [`__GetTag`](/api/engine/element-api/__GetTag.md)

- [Introduction](/api/engine/element-api/__GetTag.md#introduction)
- [Syntax](/api/engine/element-api/__GetTag.md#syntax)
- [Example](/api/engine/element-api/__GetTag.md#example)

### [`__InsertElementBefore`](/api/engine/element-api/__InsertElementBefore.md)

- [Introduction](/api/engine/element-api/__InsertElementBefore.md#introduction)
- [Syntax](/api/engine/element-api/__InsertElementBefore.md#syntax)
- [Example](/api/engine/element-api/__InsertElementBefore.md#example)

### [`__LastElement`](/api/engine/element-api/__LastElement.md)

- [Introduction](/api/engine/element-api/__LastElement.md#introduction)
- [Syntax](/api/engine/element-api/__LastElement.md#syntax)
- [Example](/api/engine/element-api/__LastElement.md#example)

### [`__NextElement`](/api/engine/element-api/__NextElement.md)

- [Introduction](/api/engine/element-api/__NextElement.md#introduction)
- [Syntax](/api/engine/element-api/__NextElement.md#syntax)
- [Example](/api/engine/element-api/__NextElement.md#example)

### [`__RemoveElement`](/api/engine/element-api/__RemoveElement.md)

- [Introduction](/api/engine/element-api/__RemoveElement.md#introduction)
- [Syntax](/api/engine/element-api/__RemoveElement.md#syntax)
- [Example](/api/engine/element-api/__RemoveElement.md#example)

### [`__ReplaceElement`](/api/engine/element-api/__ReplaceElement.md)

- [Introduction](/api/engine/element-api/__ReplaceElement.md#introduction)
- [Syntax](/api/engine/element-api/__ReplaceElement.md#syntax)
- [Example](/api/engine/element-api/__ReplaceElement.md#example)

### [`__ReplaceElements`](/api/engine/element-api/__ReplaceElements.md)

- [Introduction](/api/engine/element-api/__ReplaceElements.md#introduction)
- [Syntax](/api/engine/element-api/__ReplaceElements.md#syntax)
- [Example](/api/engine/element-api/__ReplaceElements.md#example)

### [`__SetAttribute`](/api/engine/element-api/__SetAttribute.md)

- [Introduction](/api/engine/element-api/__SetAttribute.md#introduction)
- [Syntax](/api/engine/element-api/__SetAttribute.md#syntax)
- [Example](/api/engine/element-api/__SetAttribute.md#example)

### [`__SetClasses`](/api/engine/element-api/__SetClasses.md)

- [Introduction](/api/engine/element-api/__SetClasses.md#introduction)
- [Syntax](/api/engine/element-api/__SetClasses.md#syntax)
- [Example](/api/engine/element-api/__SetClasses.md#example)

### [`__SetConfig`](/api/engine/element-api/__SetConfig.md)

- [Introduction](/api/engine/element-api/__SetConfig.md#introduction)
- [Syntax](/api/engine/element-api/__SetConfig.md#syntax)
- [Example](/api/engine/element-api/__SetConfig.md#example)

### [`__SetCSSId`](/api/engine/element-api/__SetCSSId.md)

- [Introduction](/api/engine/element-api/__SetCSSId.md#introduction)
- [Syntax](/api/engine/element-api/__SetCSSId.md#syntax)
- [Example](/api/engine/element-api/__SetCSSId.md#example)

### [`__SetDataset`](/api/engine/element-api/__SetDataset.md)

- [Introduction](/api/engine/element-api/__SetDataset.md#introduction)
- [Syntax](/api/engine/element-api/__SetDataset.md#syntax)
- [Example](/api/engine/element-api/__SetDataset.md#example)

### [`__SetEvents`](/api/engine/element-api/__SetEvents.md)

- [Introduction](/api/engine/element-api/__SetEvents.md#introduction)
- [Syntax](/api/engine/element-api/__SetEvents.md#syntax)
- [Example](/api/engine/element-api/__SetEvents.md#example)

### [`__SetID`](/api/engine/element-api/__SetID.md)

- [Introduction](/api/engine/element-api/__SetID.md#introduction)
- [Syntax](/api/engine/element-api/__SetID.md#syntax)
- [Example](/api/engine/element-api/__SetID.md#example)

### [`__SetInlineStyles`](/api/engine/element-api/__SetInlineStyles.md)

- [Introduction](/api/engine/element-api/__SetInlineStyles.md#introduction)
- [Syntax](/api/engine/element-api/__SetInlineStyles.md#syntax)
- [Example](/api/engine/element-api/__SetInlineStyles.md#example)

### [`__SwapElement`](/api/engine/element-api/__SwapElement.md)

- [Introduction](/api/engine/element-api/__SwapElement.md#introduction)
- [Syntax](/api/engine/element-api/__SwapElement.md#syntax)
- [Example](/api/engine/element-api/__SwapElement.md#example)

### [`__UpdateComponentID`](/api/engine/element-api/__UpdateComponentID.md)

- [Introduction](/api/engine/element-api/__UpdateComponentID.md#introduction)
- [Syntax](/api/engine/element-api/__UpdateComponentID.md#syntax)
- [Example](/api/engine/element-api/__UpdateComponentID.md#example)



---
url: /api/engine/element-api/__AddClass.md
---

# `__AddClass`

## Introduction

Adds a class selector to the Element object without affecting existing class selectors.

## Syntax

```jsx
__AddClass(element: Element, className: string) : void;
```

### Parameters

|    Key    | Description                        |
| :-------: | ---------------------------------- |
|  element  | Any Element object.                |
| className | The new className, of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile the corresponding frontend tag into the following render directive during the compilation phase.

```jsx
<view src="xxx" class="A B C" />
```

```tsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__AddClass(element, 'A');
__AddClass(element, 'B');
__AddClass(element, 'C');
```



---
url: /api/engine/element-api/__AddConfig.md
---

# `__AddConfig`

## Introduction

Adds a config key and config value to the Element object.

## Syntax

```jsx
__AddConfig(element: Element, type: string, value: any) : void;
```

### Parameters

|   Key   | Description                                          |
| :-----: | ---------------------------------------------------- |
| element | Any Element object.                                  |
|   type  | A case-sensitive string representing the config key. |
|  value  | The config value, which can be of any type.          |

::: tip Note
Developers can set some custom configs for the Element to facilitate extensions by the frontend framework.
:::

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" bindtap="onTap" />
```

```tsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__AddConfig(element, 'anyConfig', {});
```



---
url: /api/engine/element-api/__AddDataset.md
---

# `__AddDataset`

## Introduction

Adds a data- attribute to the Element object without affecting existing data- attributes.

## Syntax

```jsx
__AddDataset(element: Element, key: string, value: any) : void;
```

### Parameters

|   Key   | Description                                           |
| :-----: | ----------------------------------------------------- |
| element | Any Element object.                                   |
|   key   | A case-sensitive string representing the dataset key. |
|  value  | The dataset value, which can be of any type.          |

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" data-key="value" />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__AddDataset(element, 'key', 'value');
```



---
url: /api/engine/element-api/__AddEvent.md
---

# `__AddEvent`

## Introduction

Adds an Event Listener to the Element object.

## Syntax

```jsx
__AddEvent(element: Element, type: string, name: string, listener: string|Function) : void;
```

### Parameters

|    Key   | Description                                                                  |
| :------: | ---------------------------------------------------------------------------- |
|  element | Any Element object.                                                          |
|   type   | A case-sensitive string representing the type of the event to listen for.    |
|   name   | A case-sensitive string representing the name of the event to listen for.    |
| listener | The listener can be a case-sensitive string, or it can be null or undefined. |

- When the listener is a case-sensitive string, upon triggering the listened event, the Lynx SDK will send the current Element's `parentComponentUniqueID`, `listener`, and `event` to the background thread.
- When the listener is null or undefined, the Lynx SDK will remove the corresponding listener for the specified type and name from the Element object.

::: tip Note
Due to limitations of the Lynx SDK, currently, only one listener can be added for the same type and name. Adding a listener with the same type and name again will overwrite the previously added listener.
:::

### Return Value

No return value.

## Example

The frontend framework can generate render directives in the following way.

```jsx
<view src="xxx" bindtap="onTap" />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__AddEvent(element, 'bindEvent', 'tap', 'onTap');
```



---
url: /api/engine/element-api/__AddInlineStyle.md
---

# `__AddInlineStyle`

## Introduction

Adds inline styles to the Element object.

## Syntax

```jsx
__AddInlineStyle(element: Element, id: number, value: string|null|undefined) : void;
```

### Parameters

|   Key   | Description                                                                                                                                                                                                                                                                                                                                  |
| :-----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | Any Element object.                                                                                                                                                                                                                                                                                                                          |
|    id   | A number that corresponds to a style key, for example, 0 corresponds to the style `top`.                                                                                                                                                                                                                                                     |
|  value  | The style value to be set, which can be a string, null, or undefined. When a string is provided, the Lynx SDK will set the corresponding key and value for the Element; if previously set, it will overwrite the previous value. When null or undefined is provided, the Lynx SDK will remove the key from the inline styles of the Element. |

### Return Value

No return value.

## Example

The frontend framework can process the corresponding frontend tags into render directives as shown below.

```jsx
<view src="xxx" style={{ top: '10px' }} />
```

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__AddInlineStyle(element, 0, '10px');
```



---
url: /api/engine/element-api/__AppendElement.md
---

# `__AppendElement`

## Introduction

Inserts an Element object after the last child of the current Element.

## Syntax

```jsx
__AppendElement(parent: Element, child: Element) : Element;
```

### Parameters

|   Key  | Description                                     |
| :----: | ----------------------------------------------- |
| parent | The parent Element object.                      |
|  child | The child Element to be appended to the parent. |

### Return Value

Returns the appended child Element.

## Example

The frontend framework can perform insertion operations as shown below.

```jsx
// main-thread.js
let child = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, child);
```



---
url: /api/engine/element-api/__CreateComponent.md
---

# `__CreateComponent`

## Introduction

Creates a ComponentElement object.

## Syntax

```jsx
__CreateComponent(componentParentUniqueID: number, componentID: string, cssID: Number, entryName: string, name: string, path: string, config: Record<string, any>|null|undefined, info: Record<string, any>|null|undefined): Element;
```

### Parameters

|           Key           | Description                                                                                                                                              |
| :---------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| parentComponentUniqueID | The Unique Component ID of the ComponentElement that creates this Element, which is a number.                                                            |
|       componentID       | The componentID set by the frontend framework for the ComponentElement, which is a case-sensitive string.                                                |
|          cssID          | The CSSFragment ID, which is of type number.                                                                                                             |
|        entryName        | The schema information of the [Lazy Bundle](/guide/spec.md#lazy-bundle) where the current ComponentElement is located, which is a case-sensitive string. |
|           name          | The frontend-defined name of the current ComponentElement, which is a case-sensitive string.                                                             |
|           path          | The frontend path of the current ComponentElement, which is a case-sensitive string.                                                                     |
|          config         | The configuration for the current ComponentElement.                                                                                                      |
|           info          | Some additional information required when creating the ComponentElement; this parameter can be omitted.                                                  |

### Return Value

Returns the ComponentElement.

## Example

The frontend framework can create a ComponentElement in the following way.

```jsx
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});
```



---
url: /api/engine/element-api/__CreateElement.md
---

# `__CreateElement`

## Introduction

Creates an Element object.

## Syntax

```jsx
__CreateElement(tagName: string, parentComponentUniqueID: number, info?: object) : Element;
```

### Parameters

|           Key           | Description                                                                                                                                                                                                                  |
| :---------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|         tagName         | A string that specifies the type of Element to create, which corresponds to the LynxUI tagName, such as input. Built-in Elements like view, image, etc. cannot use this interface and must use their respective Create APIs. |
| parentComponentUniqueID | The Unique Component ID of the ComponentElement that creates this Element, which is a number.                                                                                                                                |
|           info          | Additional information required when creating the Element; this parameter can be omitted.                                                                                                                                    |

### Return Value

The return value is currently a Value\_RefCounted type of `lepus::Value`, which is implemented as `base::scoped_refptr<Element>`.

::: tip Note
`base::scoped_refptr<Element>` manages the lifecycle of the Element based on reference counting. Therefore, the frontend framework can hold this return value to manage the Element's lifecycle. The Element will only be destroyed when the frontend framework no longer holds it and the Element is removed from the tree.
:::

## Example

The frontend framework can process the corresponding frontend tags into render directives as follows.

```jsx
<input />
```

```jsx
// main-thread.js
let element = __CreateElement('input', 0, {});
```



---
url: /api/engine/element-api/__CreatePage.md
---

# `__CreatePage`

## Introduction

Creates a PageElement object.

## Syntax

```jsx
__CreatePage(componentID: string, cssID: number, info: Record<string, any>|null|undefined) : Element;
```

### Parameters

|     Key     | Description                                                                                                                                                                                                                   |
| :---------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| componentID | The componentID assigned to the PageElement by the frontend framework, which is a case-sensitive string. The PageElement is a special type of ComponentElement that will be detailed later regarding the role of componentID. |
|    cssID    | The CSSFragment ID, which is a number.                                                                                                                                                                                        |
|     info    | Additional information required when creating the PageElement; this parameter can be omitted.                                                                                                                                 |

### Return Value

Returns the PageElement.

## Example

The frontend framework can create a PageElement in the following way.

```jsx
// main-thread.js
let page = __CreatePage('0', 0, {});
```



---
url: /api/engine/element-api/__ElementIsEqual.md
---

# `__ElementIsEqual`

## Introduction

Determines if the two passed Element objects are the same Element.

## Syntax

```jsx
__ElementIsEqual(left: Element, right: Element) : bool;
```

### Parameters

|  Key  | Description                    |
| :---: | ------------------------------ |
|  left | The left node to be compared.  |
| right | The right node to be compared. |

### Return Value

Returns true only when the left and right are the same node.

## Example

The frontend framework can perform the comparison operation as follows.

```jsx
// main-thread.js
let childA = __CreateElement('view', 0, {});

let childB = __CreateElement('view', 0, {});

let isEqual = __ElementIsEqual(childA, childB);
```



---
url: /api/engine/element-api/__FirstElement.md
---

# `__FirstElement`

## Introduction

Returns the first child node of an Element.

## Syntax

```jsx
__FirstElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the first child Element of the current Element.

## Example

The frontend framework can retrieve the first child Element of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let first = __FirstElement(element);
```



---
url: /api/engine/element-api/__GetAttributes.md
---

# `__GetAttributes`

## Introduction

Returns all attributes of an Element in the form of a map.

## Syntax

```jsx
__GetAttributes(element: Element) : object;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the attribute map of the current Element, where the map key is the attribute key and the map value is the attribute value.

## Example

The frontend framework can retrieve the attribute map of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

let attributeMap = __GetAttributes(element);
```



---
url: /api/engine/element-api/__GetChildren.md
---

# `__GetChildren`

## Introduction

Returns all child nodes of an Element in order, in the form of an array.

## Syntax

```jsx
__GetChildren(element: Element) : Array<Element>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns all child nodes of the current Element as an array.

## Example

The frontend framework can retrieve all child nodes of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let children = __GetChildren(element);
```



---
url: /api/engine/element-api/__GetClasses.md
---

# `__GetClasses`

## Introduction

Returns all class selectors of an Element in order, in the form of an array.

## Syntax

```jsx
__GetClasses(element: Element) : Array<string>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the class selectors of the current Element as an array.

## Example

The frontend framework can retrieve the class selectors of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__SetClasses(element, 'A B C');

let classNames = __GetClasses(element);
```



---
url: /api/engine/element-api/__GetComponentID.md
---

# `__GetComponentID`

## Introduction

Returns the componentID of a ComponentElement.

## Syntax

```jsx
__GetComponentID(element: Element) : string;
```

### Parameters

|   Key   | Description           |
| :-----: | --------------------- |
| element | Any ComponentElement. |

### Return Value

Returns the componentID of the ComponentElement.

## Example

The frontend framework can retrieve the componentID of a ComponentElement as follows.

```jsx
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});

let id = __GetComponentID(element);
```



---
url: /api/engine/element-api/__GetComputedStyleByKey.md
---

# `__GetComputedStyleByKey`

APISummary
## Introduction

Returns the resolved style value for a CSS property of an element

## Syntax

```jsx
__GetComputedStyleByKey(element: Element, key: string) : string;
```

### Parameters

|   Key   | Description                                                                                                                                                                              |
| :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | Any Element object.                                                                                                                                                                      |
|   key   | A string indicating the CSS property key to be retrieved. Keep in mind that not every CSS property is supported. Refer to the Compatibility table to see which properties are supported. |

### Return Value

Resolved style value for a CSS property of specified element.

:::caution
Unlike browser, this PAPI won't trigger document reflow.
:::

## Example

The frontend framework can retrieve resolved style value of an Element as follows.

```jsx
// main-thread.js
let page = __CreateElement('page', 0, {});

let element = __CreateElement('view', 0, {});
__SetInlineStyles(element, {
  top: '10px',
  left: '10px',
  right: '10px',
  bottom: '10px',
});

__AppendElement(page, element);
__FlushElementTree(page, {});

let width = __GetComputedStyleByKey(element, 'width');
```

## Compatability

**Error:** No compatibility data found for `elements.get-computed-style-supported-properties`


---
url: /api/engine/element-api/__GetConfig.md
---

# `__GetConfig`

## Introduction

Returns all configurations of an Element node in the form of a map.

## Syntax

```jsx
__GetConfig(element: Element) : Record<string, any>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the config of the current Element as a map.

## Example

The frontend framework can retrieve the config of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetConfig(element, { anyConfig: {} });

let listener = __GetConfig(element);
```



---
url: /api/engine/element-api/__GetDataByKey.md
---

# `__GetDataByKey`

## Introduction

Returns the value of a specific data- attribute of an Element.

## Syntax

```jsx
__GetDataByKey(element: Element, key: string) : any;
```

### Parameters

|   Key   | Description                         |
| :-----: | ----------------------------------- |
| element | Any Element object.                 |
|   key   | data- key, a case-sensitive string. |

### Return Value

Returns the data- value corresponding to the data- key of the current Element, which can be of any type.

## Example

The frontend framework can retrieve the value of a data- attribute of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });

let dataset = __GetDataByKey(element, 'key');
```



---
url: /api/engine/element-api/__GetDataset.md
---

# `__GetDataset`

## Introduction

Returns all data- attributes of an Element node in the form of a map.

## Syntax

```jsx
__GetDataset(element: Element) : Record<string, any>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the dataset of the current Element as a map.

## Example

The frontend framework can retrieve the dataset of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });

let dataset = __GetDataset(element);
```



---
url: /api/engine/element-api/__GetElementUniqueID.md
---

# `__GetElementUniqueID`

## Introduction

Returns the unique ID of an Element.

## Syntax

```jsx
__GetElementUniqueID(element: Element) : number;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Currently, the return value is a unique ID of the Element object within the current LynxView, represented as a number.

## Example

The frontend framework can retrieve the unique ID of an Element as follows.

```jsx
let element = __CreateElement('view', 0, {});
let id = __GetElementUniqueID(element);
```



---
url: /api/engine/element-api/__GetEvent.md
---

# `__GetEvent`

## Introduction

Returns the event listener specific to the Element.

## Syntax

```jsx
__GetEvent(element: Element, name: string, type: string) : string|Function|undefined;
```

### Parameters

|   Key   | Description                                          |
| :-----: | ---------------------------------------------------- |
| element | Any Element object.                                  |
|   name  | A case-sensitive string representing the event name. |
|   type  | A case-sensitive string representing the event type. |

### Return Value

Returns the event listener for the current Element with the specified name.

## Example

The frontend framework can retrieve the event listener of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);

let listener = __GetEvent(element, 'tap', 'bindEvent');
```



---
url: /api/engine/element-api/__GetEvents.md
---

# `__GetEvents`

## Introduction

Returns all event listeners of the Element in the form of an array.

## Syntax

```jsx
__GetEvents(element: Element) : Array<Record<string, any>>;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns an array of all event listeners for the current Element, where each element in the array is a map that describes a single event listener.

## Example

The frontend framework can retrieve the event listeners of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);

let listeners = __GetEvents(element);
```



---
url: /api/engine/element-api/__GetID.md
---

# `__GetID`

## Introduction

Returns the ID selector of the Element.

## Syntax

```jsx
__GetID(element: Element) : string;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

The ID selector of the current Element. If it has not been set, an empty string is returned.

## Example

The frontend framework can retrieve the Element ID selector as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetID(element, 'video');

let id = __GetID(element);
```



---
url: /api/engine/element-api/__GetInlineStyles.md
---

# `__GetInlineStyles`

## Introduction

Returns the inline styles of the Element.

## Syntax

```jsx
__GetInlineStyles(element: Element) : object;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the inline styles of the current Element in the form of a map.

## Example

The frontend framework can retrieve the inline styles of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetInlineStyles(element, 'top:10px;left:10px;right:10px;bottom:10px;');

let styles = __GetInlineStyles(element);
```



---
url: /api/engine/element-api/__GetParent.md
---

# `__GetParent`

## Introduction

Returns the parent node of the Element.

## Syntax

```jsx
__GetParent(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the parent node of the current node. If there is no parent node, it returns undefined.

## Example

The frontend framework can retrieve the parent node of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let parent = __GetParent(element);
```



---
url: /api/engine/element-api/__GetTag.md
---

# `__GetTag`

## Introduction

Returns the tag selector of the Element node.

## Syntax

```jsx
__GetTag(element: Element) : string;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

The return value is the tag selector of the Element object, with the type string.

## Example

The frontend framework can retrieve the tag selector of an Element as follows.

```jsx
let element = __CreateElement('view', 0, {});
let tag = __GetTag(element);
```



---
url: /api/engine/element-api/__InsertElementBefore.md
---

# `__InsertElementBefore`

## Introduction

Inserts an Element node into the specified parent node, before the reference node.

## Syntax

```jsx
__InsertElementBefore(parent: Element, child: Element, referenceNode: Element) : Element;
```

### Parameters

|      Key      | Description                                                                                                                                     |
| :-----------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|     parent    | The parent node object.                                                                                                                         |
|     child     | The child node to be inserted into the parent node.                                                                                             |
| referenceNode | The reference node before which the child node needs to be inserted. If the reference node is null, the child node will be inserted at the end. |

### Return Value

Returns the inserted child node.

## Example

The frontend framework can perform the insertion operation as follows.

```jsx
// main-thread.js
let first = __CreateElement('view', 0, {});

let last = __CreateElement('view', 0, {});

let mid = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, first);
__AppendElement(parent, last);

__InsertElementBefore(parent, mid, last);
```



---
url: /api/engine/element-api/__LastElement.md
---

# `__LastElement`

## Introduction

Returns the last child node of the Element.

## Syntax

```jsx
__LastElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the last child node of the current Element.

## Example

The frontend framework can retrieve the last child node of an Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let last = __LastElement(element);
```



---
url: /api/engine/element-api/__NextElement.md
---

# `__NextElement`

## Introduction

Returns the node that immediately follows the specified Element node in its parent's list of child nodes. If the specified node is the last node, it returns undefined.

## Syntax

```jsx
__NextElement(element: Element) : Element|undefined;
```

### Parameters

|   Key   | Description         |
| :-----: | ------------------- |
| element | Any Element object. |

### Return Value

Returns the node that immediately follows the current Element object in its parent's list of child nodes. If the current Element is the last node, it returns undefined.

## Example

The frontend framework can retrieve the next node of a specified Element as follows.

```jsx
// main-thread.js
let element = __CreateElement('view', 0, {});

let next = __NextElement(element);
```



---
url: /api/engine/element-api/__RemoveElement.md
---

# `__RemoveElement`

## Introduction

Removes an Element node from its parent's list of child nodes.

## Syntax

```jsx
__RemoveElement(parent: Element, child: Element) : Element;
```

### Parameters

|   Key  | Description                                   |
| :----: | --------------------------------------------- |
| parent | The parent node object.                       |
|  child | The child node to be removed from the parent. |

### Return Value

Returns the removed child node.

## Example

The frontend framework can perform the removal operation as follows.

```jsx
// main-thread.js
let child = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, child);

__RemoveElement(parent, child);
```



---
url: /api/engine/element-api/__ReplaceElement.md
---

# `__ReplaceElement`

## Introduction

Replaces an Element node with a specified node.

## Syntax

```jsx
__ReplaceElement(newChild: Element, oldChild: Element) : void;
```

### Parameters

|    Key   | Description                                                                                                                                        |
| :------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| newChild | The new node that will replace the old node. If this node already exists in the Element tree, it will first be removed from its original position. |
| oldChild | The original node that is being replaced.                                                                                                          |

### Return Value

No return value.

## Example

The frontend framework can perform the replacement operation as follows.

```jsx
// main-thread.js
let newChild = __CreateElement('view', 0, {});

let oldChild = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, oldChild);

__ReplaceElement(newChild, oldChild);
```



---
url: /api/engine/element-api/__ReplaceElements.md
---

# `__ReplaceElements`

## Introduction

Replaces a list of Element nodes with a specified list of nodes.

## Syntax

```jsx
__ReplaceElements(parent: Element, newChildren: Array<Element>, oldChildren: Array<Element>) : void;
```

### Parameters

|     Key     | Description                                               |
| :---------: | --------------------------------------------------------- |
|    parent   | The parent node whose child nodes will be batch-replaced. |
| newChildren | The list of new nodes that will replace the old nodes.    |
| oldChildren | The list of original nodes that are being replaced.       |

### Return Value

No return value.

## Example

The frontend framework can perform the replacement operation as follows.

```jsx
// main-thread.js
let newChild = __CreateElement('view', 0, {});

let oldChild = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, oldChild);

__ReplaceElements(parent, [newChild], [oldChild]);
```



---
url: /api/engine/element-api/__SetAttribute.md
---

# `__SetAttribute`

## Introduction

Sets an attribute for a specific Element node.

## Syntax

```jsx
__SetAttribute(element: Element, key: string, value: any) : void;
```

### Parameters

|   Key   | Description                                           |
| :-----: | ----------------------------------------------------- |
| element | Any Element object.                                   |
|   key   | A string representing the attribute key to be set.    |
|  value  | Any value representing the attribute value to be set. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
```



---
url: /api/engine/element-api/__SetClasses.md
---

# `__SetClasses`

## Introduction

Sets class selectors for a specific Element node.

## Syntax

```jsx
__SetClasses(element: Element, classNames: string) : void;
```

### Parameters

|     Key    | Description                                                                                       |
| :--------: | ------------------------------------------------------------------------------------------------- |
|   element  | Any Element object.                                                                               |
| classNames | A new list of class selectors, which will overwrite the existing class selectors, of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile the corresponding frontend tags into render instructions as shown below.

```jsx
<view src="xxx" class="A B C" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');
__SetClasses(element, 'A B C');
```



---
url: /api/engine/element-api/__SetConfig.md
---

# `__SetConfig`

## Introduction

Sets a configuration for a specific Element node.

## Syntax

```jsx
__SetConfig(element: Element, config: Record<string, any>) : void;
```

### Parameters

|   Key   | Description                                                                |
| :-----: | -------------------------------------------------------------------------- |
| element | Any Element object.                                                        |
|  config | The configuration to be set for the Element object, which is a map object. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" bindtap="onTap" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetConfig(element, { anyConfig: {} });
```



---
url: /api/engine/element-api/__SetCSSId.md
---

# `__SetCSSId`

## Introduction

Sets a CSS ID for a specific Element node.

## Syntax

```jsx
__SetCSSId(element: Element, cssID: number) : void;
```

### Parameters

|   Key   | Description                          |
| :-----: | ------------------------------------ |
| element | Any Element object.                  |
|  cssID  | The CSS ID, which is of type number. |

### Return Value

No return value.

## Example

The frontend framework can perform replacement operations as follows.

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetCSSId(element, 0);
```



---
url: /api/engine/element-api/__SetDataset.md
---

# `__SetDataset`

## Introduction

Sets data- attributes for a specific Element node.

## Syntax

```jsx
__SetDataset(element: Element, dataset: Record<string, any>) : void;
```

### Parameters

|   Key   | Description                                                          |
| :-----: | -------------------------------------------------------------------- |
| element | Any Element object.                                                  |
| dataset | The dataset to be set for the Element object, which is a map object. |

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" data-key="value" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetDataset(element, { key: 'value' });
```



---
url: /api/engine/element-api/__SetEvents.md
---

# `__SetEvents`

## Introduction

Sets event listeners for a specific Element node.

## Syntax

```jsx
__SetEvents(element: Element, listeners: Array<Record<string, any>>) : void;
```

### Parameters

|    Key    | Description                                                                                                                                                                 |
| :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|  element  | Any Element object.                                                                                                                                                         |
| listeners | An array of listeners that describes the event listeners to add. Each element is a map that represents a specific event listener and must contain the following three keys: |

- type: A case-sensitive string representing the event type to listen for.
- name: A case-sensitive string representing the event name to listen for.
- function: The function can be a case-sensitive string or null/undefined.
  - When the function is a case-sensitive string, the Lynx SDK will send the current Element's parentComponentUniqueID, function, and event to the background thread to call the corresponding entry function when the event is triggered.
  - When the function is null or undefined, the Lynx SDK will remove the corresponding listener based on the type and name from the Element object's listeners.

### Return Value

No return value.

## Example

The frontend framework can generate render instructions as follows.

```jsx
<view src="xxx" bindtap="onTap" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetEvents(element, [{ type: 'bindEvent', name: 'tap', function: 'onTap' }]);
```



---
url: /api/engine/element-api/__SetID.md
---

# `__SetID`

## Introduction

Sets an ID selector for a specific Element node.

## Syntax

```jsx
__SetID(element: Element, id: string) : void;
```

### Parameters

|   Key   | Description                                                                       |
| :-----: | --------------------------------------------------------------------------------- |
| element | Any Element object.                                                               |
|    id   | The ID selector to be set for the Element object, which should be of type string. |

### Return Value

No return value.

## Example

The frontend framework can compile corresponding frontend tags into the following render instructions.

```jsx
<view id="video" />
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetID(element, 'video');
```



---
url: /api/engine/element-api/__SetInlineStyles.md
---

# `__SetInlineStyles`

## Introduction

Sets inline styles for a specific Element node.

## Syntax

```jsx
__SetInlineStyles(element: Element, value: string | object) : void;
```

### Parameters

|   Key   | Description                                                                   |
| :-----: | ----------------------------------------------------------------------------- |
| element | Any Element object.                                                           |
|  value  | Inline styles that override existing inline styles, of type string or object. |

### Return Value

No return value.

## Example

The frontend framework can compile corresponding frontend tags into the following render instructions.

```jsx
<view
  src="xxx"
  style={{ top: '10px', left: '10px', right: '10px', bottom: '10px' }}
/>
```

```javascript
// main-thread.js
let element = __CreateElement('view', 0, {});
__SetAttribute(element, 'src', 'xx');

__SetInlineStyles(element, {
  top: '10px',
  left: '10px',
  right: '10px',
  bottom: '10px',
});
```



---
url: /api/engine/element-api/__SwapElement.md
---

# `__SwapElement`

## Introduction

Swaps the positions of two Elements.

## Syntax

```jsx
__SwapElement(childA: Element, childB: Element) : void;
```

### Parameters

|   Key  | Description                       |
| :----: | --------------------------------- |
| childA | The first element to be swapped.  |
| childB | The second element to be swapped. |

### Return Value

No return value.

## Example

The frontend framework can perform replacement operations as follows.

```javascript
// main-thread.js
let childA = __CreateElement('view', 0, {});

let childB = __CreateElement('view', 0, {});

let parent = __CreateElement('view', 0, {});

__AppendElement(parent, childA);
__AppendElement(parent, childB);

__SwapElement(childA, childB);
```



---
url: /api/engine/element-api/__UpdateComponentID.md
---

# `__UpdateComponentID`

## Introduction

Updates the componentID of a ComponentElement.

## Syntax

```jsx
__UpdateComponentID(element: Element, componentID: string) : void;
```

### Parameters

|     Key     | Description                                                                                          |
| :---------: | ---------------------------------------------------------------------------------------------------- |
|   element   | Any ComponentElement.                                                                                |
| componentID | The componentID assigned to the ComponentElement by the frontend framework, which is case-sensitive. |

### Return Value

No return value.

## Example

The frontend framework can update the componentID of a ComponentElement as follows.

```javascript
// main-thread.js
let element = __CreateComponent(0, '1', 1, '', 'name', 'path', {}, {});

__UpdateComponentID(element, '2');
```



---
url: /api/errors/lynx-error.md
---

# LynxError API

APISummary
`LynxError` is the standard error object returned by the Lynx runtime to indicate runtime failures, warnings, or recoverable issues in your app.

It contains both **machine-readable information** (error code, subcode, severity level) and a **human-readable message** to help with debugging and recovery.

## Use Cases

- Display meaningful errors in debug or development mode
- Trigger fallback UI or navigation for fatal runtime issues
- Report errors for analytics or bug tracking

***

## Core Concepts

### Error Code

A **3–4 digit number** identifying the category or behavior of an error.
For example, `301` represents an image loading error.

Refer to the [Error Codes documentation](/api/errors/error-code.md) for a full list of codes and their meanings.

### Subcode

A **5–6 digit number** derived from the error code, used to specify the exact cause of the error.
For example, `30101` indicates that the loaded image is too large.

Refer to the [Error Codes documentation](/api/errors/error-code.md) for details on individual subcodes.

### Level

`LynxError` defines four levels: `Fatal`, `Error`, `Warn`, and `Undecided`.

| Level       | Meaning                | Suggested Action             |
| ----------- | ---------------------- | ---------------------------- |
| `Fatal`     | App is likely unusable | Reload or fallback UI        |
| `Error`     | Recoverable issue      | Log and retry                |
| `Warn`      | Non-blocking warning   | Log and continue             |
| `Undecided` | Not yet categorized    | Handle gracefully, log issue |

### Message

A JSON-formatted string containing detailed error information, including:

- `code`
- `subcode`
- `level`
- `message`
- `suggestion` (optional)

***

## Platform Methods

### Android

| Method           | Return Type | Description            |
| ---------------- | ----------- | ---------------------- |
| `getErrorCode()` | `int`       | Returns the error code |
| `getSubCode()`   | `int`       | Returns the subcode    |
| `getLevel()`     | `String`    | Returns the level      |
| `getMsg()`       | `String`    | Returns the message    |

### iOS

| Property / Method | Type            | Description                                                                                       |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `errorCode`       | `NSInteger`     | Returns the error code                                                                            |
| `subcode`         | `NSInteger`     | Returns the subcode                                                                               |
| `level`           | `NSString*`     | Returns the level                                                                                 |
| `userInfo()`      | `NSDictionary*` | Returns a dictionary where the message can be queried using the key `LynxErrorUserInfoKeyMessage` |

### HarmonyOS

| Method           | Type             | Description            |
| ---------------- | ---------------- | ---------------------- |
| `getErrorCode()` | `number`         | Returns the error code |
| `getSubCode()`   | `number`         | Returns the subcode    |
| `getLevel()`     | `LynxErrorLevel` | Returns the level      |
| `getMsg()`       | `string`         | Returns the message    |

***

## Example

### JavaScript

```js
lynx.onError = (error) => {
  const detail = JSON.parse(error.message);
  if (detail.level === 'Fatal') {
    // Possibly reload or fallback to home
    console.error('Critical error occurred:', detail.message);
  }
};
```

### Kotlin

```kotlin
fun onLynxError(error: LynxError) {
  if (error.level == "Fatal") {
    println("Fatal error: ${error.msg}")
  }
}
```

### Swift

```swift
func onLynxError(_ error: LynxError) {
  if error.level == "Fatal" {
    print("Fatal error: \(error.msg)")
  }
}
```

### ETS

```ts
onLynxError(error: LynxError) {
  if (error.level == LynxErrorLevel.Fatal) {
    console.error('Fatal error:', error.getMsg());
  }
}
```

***

## Compatibility

**Compatibility Table**
**Query:** `errors.lynx-error`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.0 | - |
| iOS | 3.0 | - |
| HarmonyOS | 3.4 | - |

**Description:** Structure used to represent an error




---
url: /api/errors/error-code.md
---

# Error Codes

| Error Code    | Description                                                |
| ------------- | ---------------------------------------------------------- |
| [102](#102)   | Error occurred while loading app bundle                    |
| [105](#105)   | Error occurred while reloading app bundle                  |
| [201](#201)   | Error occurred while executing background thread script    |
| [202](#202)   | Error occurred while calling JS function from platform     |
| [301](#301)   | Error occurred while loading image resource                |
| [302](#302)   | Error occurred while loading font resource                 |
| [303](#303)   | Error occurred while loading external resource             |
| [304](#304)   | Error occurred while loading i18n resource                 |
| [321](#321)   | Error occurred while invoking LynxResourceModule           |
| [398](#398)   | Custom error for resource                                  |
| [399](#399)   | Exception occurred while loading resource                  |
| [401](#401)   | Error occurred while updating data                         |
| [501](#501)   | Error occurred while invoking Element API                  |
| [502](#502)   | Error occurred while updating element                      |
| [601](#601)   | Internal layout error                                      |
| [602](#602)   | Performance issues related to layout                       |
| [603](#603)   | Failed to update layout                                    |
| [604](#604)   | Invalid usage or exceptions on ShadowNode                  |
| [901](#901)   | Common errors for invoking native modules                  |
| [998](#998)   | Error occurred in custom native modules                    |
| [999](#999)   | Exception occurred while invoking the native module        |
| [1099](#1099) | Exception occurred while handling event                    |
| [1101](#1101) | Error occurred while executing Main thread script          |
| [1111](#1111) | Error occurred while executing renderer function           |
| [1202](#1202) | Running on the wrong thread                                |
| [1301](#1301) | Generic CSS error                                          |
| [1302](#1302) | Error while manipulating ComputedCSSValue                  |
| [1303](#1303) | Error occurred while parsing CSS                           |
| [1601](#1601) | Failed to load a lazy bundle                               |
| [1901](#1901) | Error for main thread script call exception in worklet     |
| [1902](#1902) | Error for requestAnimationFrame call exception             |
| [1903](#1903) | Error for worklet module exception                         |
| [2001](#2001) | Error occurred while calling MTSBridge module              |
| [2201](#2201) | Error occurred while invoking component API                |
| [2202](#2202) | Error from List component                                  |
| [2203](#2203) | Error from Image component                                 |
| [2298](#2298) | Custom error of components                                 |
| [9901](#9901) | Platform exceptions                                        |
| [9902](#9902) | Exceptions encountered while calling Java native interface |

## 102: `EB_APP_BUNDLE_LOAD` \{#102}

### 10201: `E_APP_BUNDLE_LOAD_RENDER_FAILED`
 Fatal
Description: Failed to render app bundle
FixSuggestion: Should not call `loadTemplate` while the rendering pipeline of app bundle has not finished

### 10202: `E_APP_BUNDLE_LOAD_ENV_NOT_READY`
 Fatal
Description: `loadTemplate` while LynxEnv has not been initialized
FixSuggestion: Please call the initialization method of LynxEnv before loadTemplate

### 10203: `E_APP_BUNDLE_LOAD_BAD_RESPONSE`
 Fatal
Description: Failed to fetch app bundle by provider
FixSuggestion: Please check if the app bundle is available

### 10204: `E_APP_BUNDLE_LOAD_PARSE_FAILED`
 Fatal
Description: Failed to parse app bundle
FixSuggestion: Please check that 1. the provided bundle is an app bundle, 2. the engine version of the bundle is compatible with that of Lynx engine, 3. the bundle file is not broken

### 10205: `E_APP_BUNDLE_LOAD_BAD_BUNDLE`
 Fatal
Description: A bad TemplateBundle is provided
FixSuggestion: Please check the error message of the bundle

### 10299: `E_APP_BUNDLE_LOAD_EXCEPTION`
 Fatal
Description: Exception occurred while rendering app bundle

## 105: `EB_APP_BUNDLE_RELOAD` \{#105}

### 10501: `E_APP_BUNDLE_RELOAD_EARLY_RELOAD`
 Error
Description: `reloadTemplate` before `loadTemplate`
FixSuggestion: Please `loadTemplate` before `reloadTemplate`

## 201: `EB_BTS_RUNTIME_ERROR` \{#201}

### 20100: `E_BTS_RUNTIME_ERROR`
 Undecided
Description: Runtime error for an unspecified reason

### 20101: `E_BTS_RUNTIME_ERROR_SCRIPT_ERROR`
 Fatal
Description: The script has syntax errors or other runtime errors
FixSuggestion: Please check the error message and fix the script

### 20102: `E_BTS_RUNTIME_ERROR_BYTECODE_SCRIPT_ERROR`
 Fatal
Description: The bytecode script has syntax errors or other runtime errors
FixSuggestion: Please check the error message and fix the script

### 20103: `E_BTS_RUNTIME_ERROR_BINDINGS_ERROR`
 Error
Description: JavaScript binding API call errors
FixSuggestion: Please check the error message and fix binding API call

## 202: `EB_BTS_PLATFORM_CALL_JS_FUNCTION` \{#202}

### 20201: `E_BTS_PLATFORM_CALL_JS_FUNCTION_TOO_FREQUENCY`
 Warn
Description: Calling JS function too frequently. This may cause OOM issues
FixSuggestion: Please throttle related calls

## 301: `EB_RESOURCE_IMAGE` \{#301}

### 30101: `E_RESOURCE_IMAGE_BIG_IMAGE`
 Error
Description: The image bitmap size is too large relative to the UI.
FixSuggestion: Please resize the image to appropriate dimensions or enable downsampling

### 30102: `E_RESOURCE_IMAGE_PIC_SOURCE`
 Error
Description: Error occurred while decoding image
FixSuggestion: Possibly due to an unsupported image format or a corrupted file. Please verify the integrity of the image file

### 30103: `E_RESOURCE_IMAGE_FROM_USER_OR_DESIGN`
 Error
Description: Error from user actions or the network conditions
FixSuggestion: In most cases, the issue arises from a canceled image request or an unavailable network connection

### 30196: `E_RESOURCE_IMAGE_FROM_NETWORK_OR_OTHERS`
 Error
Description: Network or other issues
FixSuggestion: Please investigate the corresponding image download workflow for potential issues

### 30199: `E_RESOURCE_IMAGE_EXCEPTION`
 Error
Description: Exception occurred while loading image
FixSuggestion: An unidentified exception occurred that cannot be attributed to a specific cause. Please investigate further based on the available details

## 302: `EB_RESOURCE_FONT` \{#302}

### 30200: `E_RESOURCE_FONT`
 Error
Description: Failed to process font resource

### 30201: `E_RESOURCE_FONT_SRC_FORMAT_ERROR`
 Error
Description: Font src format error
FixSuggestion: Please check the font-face format

### 30202: `E_RESOURCE_FONT_RESOURCE_LOAD_ERROR`
 Error
Description: Failed to load font resource
FixSuggestion: Please check whether font resource is available

### 30203: `E_RESOURCE_FONT_BASE64_PARSING_ERROR`
 Error
Description: Failed to parse base64 resource
FixSuggestion: Please check whether the base64 resource is available

### 30204: `E_RESOURCE_FONT_FILE_FORMAT_NOT_SUPPORTED`
 Error
Description: Font file format is not supported
FixSuggestion: Please use a font file in ttf or otf format

### 30205: `E_RESOURCE_FONT_REGISTER_FAILED`
 Undecided
Description: Failed to register font
FixSuggestion: If the font is displayed correctly, there is no need to deal with it

## 303: `EB_RESOURCE_EXTERNAL_RESOURCE` \{#303}

### 30301: `E_RESOURCE_EXTERNAL_RESOURCE_REQUEST_FAILED`
 Error
Description: Lynx resource fetcher requests failed
FixSuggestion: Please check whether the url of the external resource is available

### 30302: `E_RESOURCE_EXTERNAL_RESOURCE_LOCAL_RESOURCE_LOAD_FAIL`
 Error
Description: Failed to load local resource
FixSuggestion: Please check whether the local external resource is available

## 304: `EB_RESOURCE_I18N` \{#304}

### 30400: `E_RESOURCE_I18N`
 Error
Description: i18n Resource Error

## 321: `EB_RESOURCE_MODULE` \{#321}

### 32101: `E_RESOURCE_MODULE_PARAMS_ERROR`
 Error
Description: Parameter type mismatch or incorrect number of parameters while calling the requestResourcePrefetch or cancelResourcePrefetch API
FixSuggestion: Please refer to the parameter descriptions of this API in documentation and check the parameters used in the call

### 32102: `E_RESOURCE_MODULE_IMG_PREFETCH_HELPER_NOT_EXIST`
 Error
Description: Unable to access the image service because the app has not integrated LynxImageService
FixSuggestion: Please refer to the official documentation to integrate LynxImageService into your app

### 32103: `E_RESOURCE_MODULE_RESOURCE_SERVICE_NOT_EXIST`
 Error
Description: Unable to access resources because the app has not integrated the resource service
FixSuggestion: Please refer to the official documentation to implement the ILynxResourceService and integrate it into your app

## 398: `EB_RESOURCE_CUSTOM` \{#398}

### 39800: `E_RESOURCE_CUSTOM`
 Error
Description: Unexpected custom error
FixSuggestion: This is unexpected. Please file an issue to Lynx to help address it

## 399: `EB_RESOURCE_EXCEPTION` \{#399}

### 39900: `E_RESOURCE_EXCEPTION`
 Error
Description: Unexpect exception in loading resource
FixSuggestion: This is unexpected. Please file an issue to Lynx to help address it

## 401: `EB_DATA_FLOW_UPDATE` \{#401}

### 40101: `E_DATA_FLOW_UPDATE_INVALID_PROCESSOR`
 Error
Description: Call built-in function as data processor
FixSuggestion: Should not call `getDerivedStateFromProps`, `getDerivedStateFromError`, `shouldComponentUpdate` as data processor

### 40102: `E_DATA_FLOW_UPDATE_INVALID_TYPE`
 Error
Description: Invalid data type
FixSuggestion: Target string data should be enabled to be parsed into a table

### 40199: `E_DATA_FLOW_UPDATE_EXCEPTION`
 Error
Description: Exception occurred while updating data

## 501: `EB_ELEMENT_API` \{#501}

### 50101: `E_ELEMENT_API_FATAL`
 Fatal
Description: Fatal error in element API. Please find detailed information in the context

### 50102: `E_ELEMENT_API_ERROR`
 Error
Description: Error in element API. Please find detailed information in the context

## 502: `EB_ELEMENT_UPDATE` \{#502}

### 50201: `E_ELEMENT_UPDATE_NODE_IS_NULL`
 Fatal
Description: Element update error for an unspecified reason

## 601: `EB_LAYOUT_INTERNAL` \{#601}

### 60100: `E_LAYOUT_INTERNAL`
 Error
Description: Cannot find ShadowNode
FixSuggestion: Lynx internal error. Please check whether the creating of corresponding ShadowNode failed

## 602: `EB_LAYOUT_PERF` \{#602}

### 60201: `E_LAYOUT_PERF_INFINITE_LOOP`
 Error
Description: Infinite Loop of layout is detected
FixSuggestion: Infinite loop of layout happens. It usually happens when the front-end decides the content size based on the viewport size, while the client is deciding the viewport size based on the content size

## 603: `EB_LAYOUT_UPDATE` \{#603}

### 60301: `E_LAYOUT_UPDATE_UI_NOT_FOUND`
 Error
Description: Can not find UI while updating layout
FixSuggestion: This is an internal error of Lynx. LynxUI has not been created or the creation failed while updating

## 604: `EB_LAYOUT_PLATFORM` \{#604}

### 60401: `E_LAYOUT_PLATFORM_NODE_NULL`
 Error
Description: ShadowNode is accessed after destroyed
FixSuggestion: This is an internal error of Lynx, which usually occurs when multiple threads access ShadowNode at the same time

## 901: `EB_NATIVE_MODULES_COMMON` \{#901}

### 90101: `E_NATIVE_MODULES_COMMON_MODULE_NOT_FOUND`
 Error
Description: Native module not found
FixSuggestion: Please verify that the invoked native module name matches the registered name and confirm module registration status

### 90102: `E_NATIVE_MODULES_COMMON_FUNCTION_NOT_FOUND`
 Error
Description: Native module method not found
FixSuggestion: Please verify proper method registration using platform-specific annotations on Android or static method declarations on iOS (For details, refer to the native module documentation). Additionally, ensure that the invoked method name exactly matches the registered name in the native module implementation

### 90103: `E_NATIVE_MODULES_COMMON_WRONG_PARAM_NUM`
 Error
Description: Parameter count mismatch in native module method invocation
FixSuggestion: Please ensure that the number of parameters passed to the native method exactly matches the declared parameters in the native module implementation

### 90104: `E_NATIVE_MODULES_COMMON_WRONG_PARAM_TYPE`
 Error
Description: Parameter type mismatch in native module method invocation
FixSuggestion: Please verify that the parameter types in the method call exactly match the native module implementation. Ensure type compatibility across all parameters and validate the parameter order corresponds to the native method signature. You can check the native module documentation for expected data types

### 90105: `E_NATIVE_MODULES_COMMON_AUTHORIZATION_ERROR`
 Error
Description: Does not have permission to call the method
FixSuggestion: Please file an issue to Lynx to help address it

### 90106: `E_NATIVE_MODULES_COMMON_SYSTEM_AUTHORIZATION_ERROR`
 Error
Description: Does not have permission to call the method
FixSuggestion: Please file an issue to Lynx to help address it

### 90107: `E_NATIVE_MODULES_COMMON_RETURN_ERROR`
 Error
Description: The value returned by module method is invalid
FixSuggestion: Please file an issue to Lynx to help address it

## 998: `EB_NATIVE_MODULES_CUSTOM_ERROR` \{#998}

### 99800: `E_NATIVE_MODULES_CUSTOM_ERROR`
 Error
Description: Custom error reported from native module
FixSuggestion: This error is explicitly defined by the native module implementation. Please refer to the module error handling guide or contact the module maintainer with complete error context

## 999: `EB_NATIVE_MODULES_EXCEPTION` \{#999}

### 99900: `E_NATIVE_MODULES_EXCEPTION`
 Error
Description: Internal exception in native module method execution
FixSuggestion: This error indicates an unhandled runtime exception within the native module implementation. Please refer to the module error handling guide or contact the module maintainer with complete error context

## 1099: `EB_EVENT_EXCEPTION` \{#1099}

### 109900: `E_EVENT_EXCEPTION`
 Error
Description: An exception occurred during LynxView dispatchTouchEvent
FixSuggestion: This error is caught by the Lynx Engine. Please file an issue to Lynx to help address it

## 1101: `EB_MTS_RUNTIME_ERROR` \{#1101}

### 110100: `E_MTS_RUNTIME_ERROR`
 Undecided
Description: Main thread script error for an unspecified reason

## 1111: `EB_MTS_RENDERER_FUNCTION` \{#1111}

### 111101: `E_MTS_RENDERER_FUNCTION_FATAL`
 Fatal
Description: Fatal error during rendering. Please find detailed information in the context

### 111102: `E_MTS_RENDERER_FUNCTION_ERROR`
 Error
Description: Fatal error during rendering. Please find detailed information in the context

## 1202: `EB_THREAD_WRONG_THREAD` \{#1202}

### 120201: `E_THREAD_WRONG_THREAD_DESTROY_ERROR`
 Error
Description: Please ensure that `destroy` is called on UI thread

### 120202: `E_THREAD_WRONG_THREAD_SYNC_FLUSH_ERROR`
 Error
Description: Please ensure that `SyncFlush` is called on UI thread

## 1301: `EB_CSS` \{#1301}

### 130100: `E_CSS`
 Undecided
Description: CSS error for an unspecified reason

### 130101: `E_CSS_UNKNOWN_PROPERTY`
 Undecided
Description: Unknown CSS property id

### 130102: `E_CSS_UNSUPPORTED_VALUE`
 Undecided
Description: Unsupported CSS value
FixSuggestion: Please check your value for the property follow the detailed message

## 1302: `EB_CSS_COMPUTED_CSS_VALUE` \{#1302}

### 130201: `E_CSS_COMPUTED_CSS_VALUE_UNKNOWN_SETTER`
 Error
Description: Error occurred while setting value to ComputedCSSValue
FixSuggestion: Ignore it or raise an issue on github to let us know. This error is unexpected, which might be caused by internal pipeline fault

### 130202: `E_CSS_COMPUTED_CSS_VALUE_UNKNOWN_GETTER`
 Error
Description: Error occurred while getting value from ComputedCSSValue
FixSuggestion: Ignore it or raise an issue on github to let us know. This error is unexpected, which might be caused by internal pipeline fault

### 130203: `E_CSS_COMPUTED_CSS_VALUE_UNSUPPORTED_INHERITANCE`
 Error
Description: Property is not inheritable
FixSuggestion: Remove property name from inheritance list

## 1303: `EB_CSS_PARSER` \{#1303}

### 130300: `E_CSS_PARSER`
 Error
Description: Generic error while parsing CSS value. Value is not acceptable for the property
FixSuggestion: Please use values following the property definitions. You can get the definitions at the official website

## 1601: `EB_LAZY_BUNDLE_LOAD` \{#1601}

### 160101: `E_LAZY_BUNDLE_LOAD_BAD_RESPONSE`
 Error
Description: Lazy bundle request returned with bad response
FixSuggestion: Please check whether the url of the lazy bundle is available

### 160102: `E_LAZY_BUNDLE_LOAD_EMPTY_FILE`
 Error
Description: The binary data of lazy bundle is empty
FixSuggestion: Please check whether the lazy bundle file is empty

### 160103: `E_LAZY_BUNDLE_LOAD_DECODE_FAILED`
 Error
Description: Failed to decode lazy bundle binary data
FixSuggestion: Please check whether the lazy bundle file is broken or it is compatible with the host page

### 160104: `E_LAZY_BUNDLE_LOAD_BAD_BUNDLE`
 Error
Description: A bad lazy bundle is provided
FixSuggestion: Please check the error message of the bundle

## 1901: `EB_WORKLET_MTS_CALL_EXCEPTION` \{#1901}

### 190100: `E_WORKLET_MTS_CALL_EXCEPTION`
 Error
Description: Please check the worklet function is callable, and the worklet file is imported correctly

## 1902: `EB_WORKLET_RAF_CALL_EXCEPTION` \{#1902}

### 190200: `E_WORKLET_RAF_CALL_EXCEPTION`
 Error
Description: Error for calling requestAnimationFrame
FixSuggestion: Calling requestAnimationFrame failed. This is usually caused by an error in the callback function. Please ensure that the callback function executes without errors

## 1903: `EB_WORKLET_MODULE_EXCEPTION` \{#1903}

### 190300: `E_WORKLET_MODULE_EXCEPTION`
 Error
Description: Can not find worklet module
FixSuggestion: Make sure you have imported worklet file correctly

## 2001: `EB_MTS_BRIDGE_MODULE` \{#2001}

### 200101: `E_MTS_BRIDGE_MODULE_WRONG_PARAM`
 Error
Description: Invoke function with wrong parameter

## 2201: `EB_COMPONENT_API` \{#2201}

### 220101: `E_COMPONENT_API_DEPRECATED`
 Error
Description: A deprecated component API is invoked

## 2202: `EB_COMPONENT_LIST` \{#2202}

### 220201: `E_COMPONENT_LIST_ILLEGAL_ITEM_KEY`
 Error
Description: Error for illegal list item-key
FixSuggestion: Please check the legality of the item-key

### 220202: `E_COMPONENT_LIST_DUPLICATED_CELL`
 Error
Description: List has duplicated cell in cache
FixSuggestion: We have encountered a system-level error. Please file an issue to Lynx to help resolve this problem

### 220203: `E_COMPONENT_LIST_CELL_NOT_FOUND`
 Error
Description: List cell not found in cache
FixSuggestion: We have encountered a system-level error. Please file an issue to Lynx to help resolve this problem

### 220204: `E_COMPONENT_LIST_DYNAMIC_CHANGE_ORIENTATION`
 Error
Description: List does not support changing orientation dynamically
FixSuggestion: Please do not change the value of `vertical-orientation` dynamically

### 220205: `E_COMPONENT_LIST_INVALID_PROPS_ARG`
 Error
Description: There is an invalid parameter set in some props
FixSuggestion: For parameter usage, please check documentation of list component

### 220206: `E_COMPONENT_LIST_CHILD_COMPONENT_NOT_EXIST`
 Error
Description: Child component of list does not exist
FixSuggestion: The internal state of the engine has become inconsistent. Please file an issue to Lynx for help resolving this problem

### 220207: `E_COMPONENT_LIST_UNSUPPORTED_THREAD_STRATEGY`
 Error
Description: Multi thread strategy can not be used by default
FixSuggestion: Please set the attribute enable-async-list of  to true
### 220208: `E_COMPONENT_LIST_DUPLICATE_ITEM_KEY`
 Error
Description: Error for duplicate list item-key
FixSuggestion: Please check the legality of the item-key

## 2203: `EB_COMPONENT_IMAGE` \{#2203}

### 220301: `E_COMPONENT_IMAGE_UNSUPPORTED_PROP`
 Error
Description: Failed to apply blur-radius on \<image> element, meaning that the effect will not be visible on this platform
FixSuggestion: This may be due to platform-specific limitations or system restrictions. If blur-radius is not supported on this platform, consider using CSS filter: blur() as an alternative

## 2298: `EB_COMPONENT_CUSTOM` \{#2298}

### 229800: `E_COMPONENT_CUSTOM`
 Error
Description: An error occurs in an customized element

## 9901: `EB_EXCEPTION_PLATFORM` \{#9901}

### 990100: `E_EXCEPTION_PLATFORM`
 Error
Description: Platform exceptions for an unspecified reason
FixSuggestion: This error is caught by Lynx engine. Please file an issue to Lynx for help

## 9902: `EB_EXCEPTION_JNI` \{#9902}

### 990200: `E_EXCEPTION_JNI`
 Error
Description: JNI exceptions for an unspecified reason
FixSuggestion: This error is caught by Lynx engine. Please file an issue to Lynx for help



---
url: /api/elements/built-in/frame-API.md
---

# 

## Attributes

### `auto-height`

Android
iOS
3.8

```tsx
// @defaultValue: false
'auto-height'?: boolean;
```

Lets the frame height follow the embedded Lynx page’s content height. When enabled, the embedded page can report its content size, and the frame uses that value as its measured height.

### `auto-width`

Android
iOS
3.8

```tsx
// @defaultValue: false
'auto-width'?: boolean;
```

Lets the frame width follow the embedded Lynx page’s content width. When enabled, the embedded page can report its content size, and the frame uses that value as its measured width.

### `data`

Android
iOS
3.4

```tsx
data?: Record<string, unknown>;
```

Passes data to the nested Lynx page within the frame.

### `global-props`

Android
iOS
3.6

```tsx
'global-props'?: Record<string, unknown>;
```

Passes
`globalProps`
to the Lynx page embedded in the frame. The embedded page can read it via
`lynx.__globalProps`
.

### `src`

Android
iOS
3.4

```tsx
src: string;
```

Sets the loading path for the frame resource.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindload`

Android
iOS
3.6

```tsx
bindload = (e: FrameLoadEvent) => {};
```

| Field         | Type   | Optional | Default | Platforms                                                    | Since | Description                  |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------------ | ----- | ---------------------------- |
| statusCode    | number | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | Frame loaded status code.    |
| statusMessage | string | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | Frame loaded status message. |
| url           | string | No       | –       | <AndroidOnly /> <IOSOnly /> <VersionBadge>3.6</VersionBadge> | 3.6   | The loaded url of the frame. |

Bind frame load event callback.



---
url: /api/elements/built-in/image-API.md
---

# 

Used to display images

## Attributes

### `auto-size`

Android
iOS
Clay
Harmony
2.6

```tsx
// @defaultValue: false
'auto-size'?: boolean;
```

When set to true and the
`<image>`
element has no width or height,
the size of the
`<image>`
will be automatically adjusted
to match the image's original dimensions after the image is successfully loaded,
ensuring that the aspect ratio is maintained.

### `autoplay`

Android
iOS
Clay
Harmony
2.11

```tsx
// @defaultValue: true
autoplay?: boolean;
```

Specifies whether the animated image should start playing automatically once it is loaded.

### `blur-radius`

Android
iOS
Clay
Harmony
0.2

```tsx
'blur-radius'?: string;
```

Image blur radius

### `cap-insets`

Android
iOS
Clay
Harmony
1.4

```tsx
'cap-insets'?: string;
```

Stretchable area for 9patch images, in percentage or decimal, four values for top, right, bottom, left

:::note
Using cap-insets does not require the original image to be a 9-patch image.
:::

### `cap-insets-scale`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 1
'cap-insets-scale'?: number;
```

Adjust the scale of stretchable area for 9patch images

### `defer-src-invalidation`

Android
iOS
Clay
Harmony
2.7

```tsx
// @defaultValue: false
'defer-src-invalidation'?: boolean;
```

When set to true, the
`<image>`
will only clear the previously displayed image resource after a new image has successfully loaded.
The default behavior is to clear the image resource before starting a new load.
This can resolve flickering issues when the image src is switched and reloaded. It is not recommended to enable this in scenarios where there is node reuse in views like lists.

### `image-config`

Android
Clay
1.4

```tsx
// @defaultValue: "ARGB_8888"
'image-config'?: 'ARGB_8888' | 'RGB_565';
```

`ARGB_8888`
: 32-bit memory per pixel, supports semi-transparent images.

`RGB_565`
: 16-bit memory per pixel, reduces memory usage but loses transparency.

Support PC platform since 3.5

:::note

Affects the actual memory usage of the image bitmap.

Taking an image with a resolution of 1024\*768 as an example, the actual memory usage is (1024 \* 768 \* bits per pixel / 8) Bytes.

The default is ARGB\_8888. Frontend developers can optimize image memory usage by setting it to RGB\_565.

`ARGB_8888`
: Each pixel occupies 32 bits of memory and includes an alpha channel.

`RGB_565`
: Each pixel occupies 16 bits of memory, which reduces memory usage but results in the loss of transparency.

Setting RGB\_565 may affect the display of
`<image>`
's border-radius. You can set border-radius on the parent view of the
`<image>`
and add the clip-radius attribute to the parent view.

It is not recommended to use RGB\_565 when mode="aspectFit", as it may cause black borders in the cropped area.

:::

### `loop-count`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'loop-count'?: number;
```

Number of times an animated image plays, 0 stands for infinite

### `mode`

Android
iOS
Clay
Harmony
0.2

```tsx
// @defaultValue: 'scaleToFill'
mode?: 'scaleToFill' | 'aspectFit' | 'aspectFill' | 'center';
```

Specifies image cropping/scaling mode

`scaleToFill`
: Scales the image without preserving the aspect ratio, stretching the image to fill the element.

`aspectFit`
: Scales the image while preserving aspect ratio so that the long side is fully visible.

`aspectFill`
: Scales the image while preserving aspect ratio, ensuring the short side fills the element.

`center`
: Does not scale the image; image is centered.

### `placeholder`

Android
iOS
Clay
Harmony
1.4

```tsx
placeholder?: string;
```

Placeholder image, used same as src

### `prefetch-height`

Android
iOS
1.4

```tsx
// @defaultValue: "0px"
'prefetch-height'?: string;
```

Image won't load if its size is 0, but will load if prefetch-height is set

### `prefetch-width`

Android
iOS
1.4

```tsx
// @defaultValue: "0px"
'prefetch-width'?: string;
```

Image won't load if its size is 0, but will load if prefetch-width is set

### `src`

Android
iOS
Clay
Harmony
0.2

```tsx
// @defaultValue: undefined
src?: string;
```

Supports http/https/base64

### `tint-color`

Android
iOS
Clay
Harmony
2.12

```tsx
'tint-color'?: string;
```

Changes the color of all non-transparent pixels to the tint-color specified. The value is a
`<color>`
.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindcurrentloopcomplete`

Android
iOS
Harmony
3.7

```tsx
bindcurrentloopcomplete = (e: BaseEvent) => {};
```

Triggered when one loop of the animated image finishes playing.

### `binderror`

Android
iOS
Clay
Harmony
0.2

```tsx
binderror = (e: ErrorEvent) => {};
```

Image load error event

### `bindfinalloopcomplete`

Android
iOS
Harmony
3.7

```tsx
bindfinalloopcomplete = (e: BaseEvent) => {};
```

Triggered when the animated image finishes playing all
`loop-count`
loops. If
`loop-count`
is not set, this callback will not be triggered.

### `bindload`

Android
iOS
Clay
Harmony
0.2

```tsx
bindload = (e: LoadEvent) => {};
```

Image load success event

### `bindstartplay`

Android
iOS
Harmony
3.7

```tsx
bindstartplay = (e: BaseEvent) => {};
```

Triggered when the animated image starts playing.

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `pauseAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'pauseAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Pauses the animation, without resetting the loop-count.

### `resumeAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'resumeAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Resumes the animation, without resetting the loop-count.

### `startAnimate`

Android
iOS
Clay
Harmony
Deprecated
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'startAnimate',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Restart the animation playback method controlled by the front end, and the animation playback progress and loop count will be reset.

### `stopAnimation`

Android
iOS
Clay
Harmony
2.11

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'stopAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Stops the animation, and it will reset the loop-count.



---
url: /api/elements/built-in/input-API.md
---

# 

## Attributes

### `android-fullscreen-mode`

Android
3.4

```tsx
// @defaultValue: true
'android-fullscreen-mode'?: boolean;
```

Whether to enter the full-screen input mode when in landscape screen, in which the keyboard and input box will take up the entire screen

### `confirm-type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 'send'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

Android
iOS
Harmony
3.5

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `input-filter`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

iOS
3.4

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

iOS
3.4

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `maxlength`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `placeholder`

Android
iOS
Harmony
3.4

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: "text"
type?: 'number' | 'text' | 'digit' | 'password' | 'tel' | 'email';
```

Input content type

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindblur`

Android
iOS
Harmony
3.4

```tsx
bindblur = (e: InputBlurEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Blurred

### `bindconfirm`

Android
iOS
Harmony
3.4

```tsx
bindconfirm = (e: InputConfirmEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Confirm button clicked

### `bindfocus`

Android
iOS
Harmony
3.4

```tsx
bindfocus = (e: InputFocusEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Focused

### `bindinput`

Android
iOS
Harmony
3.4

```tsx
bindinput = (e: InputInputEvent) => {};
```

| Field          | Type    | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| isComposing    | boolean | Yes      | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Is composing or not                 |
| selectionEnd   | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |
| value          | string  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content                       |

Input content changed

### `bindselection`

Android
iOS
Harmony
3.4

```tsx
bindselection = (e: InputSelectionEvent) => {};
```

| Field          | Type   | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| selectionEnd   | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |

Input selection changed

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `blur`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'blur',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Release focus

### `focus`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getValue',
      success: Callback<{
        /**
         * Is composing or not, iOS only
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        isComposing: boolean;
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Begin position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get input content

### `setSelectionRange`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setSelectionRange',
      params: {
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Start position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set selection range

### `setValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setValue',
      params: {
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set input content



---
url: /api/elements/built-in/overlay-API.md
---

# 

## Attributes

### `ios-enable-swipe-back`

iOS
```tsx
// @defaultValue: false
'ios-enable-swipe-back'?: boolean;
```

When overlay is displayed, 'true' allows swiping right to close the current page, 'false' does not allow it

### `level`

Android
iOS
Clay
Harmony
```tsx
// @defaultValue: 1
level?: 4 | 2 | 1 | 3;
```

Introduces the concept of layers, which are divided into four levels. The larger the layer, the closer it is to the bottom. By default, it is the first level. The layers are arranged in order from 1 to 4. The displayed layer is specified and is not affected by the order of display. Within each layer, the arrangement is based on the 'last in, first out' logic. The layer cannot be dynamically adjusted when the overlay is displayed, and can only be adjusted when it is hidden.     \*

### `mode`

iOS
```tsx
// @defaultValue: 'window'
mode?: string;
```

Specifies the level at which the overlay content resides on iOS. window: Mounted on the window, the top level of the app; top: Mounted on the topViewController; page: Mounted on UINavigationController; others: customize the name of class in the client.

### `visible`

Android
iOS
Clay
Harmony
```tsx
// @defaultValue: false
visible?: boolean;
```

Control whether the overlay is displayed

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `binddismissoverlay`

Android
iOS
Clay
Harmony
```tsx
binddismissoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is hidden.

### `binderror`

Android
2.18

```tsx
binderror = (e: OverlayErrorEvent) => {};
```

| Field     | Type   | Optional | Default | Platforms       | Since | Description                                                                                                                                                  |
| --------- | ------ | -------- | ------- | --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| errorCode | string | No       | –       | <AndroidOnly /> |       | Error code: 0 - Display normally; non-0 - Unable to display, you can try to solve it by using the preloading scheme mentioned below for adapting containers. |
| errorMsg  | string | No       | –       | <AndroidOnly /> |       | Error message                                                                                                                                                |

Callback when touch on the overlay

### `bindoverlaytouch`

Android
iOS
Clay
```tsx
bindoverlaytouch = (e: OverlayTouchEvent) => {};
```

| Field | Type              | Optional | Default | Platforms                                | Since | Description                              |
| ----- | ----------------- | -------- | ------- | ---------------------------------------- | ----- | ---------------------------------------- |
| state | OverlayTouchState | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | Touch state                              |
| x     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | x position relative to the window, in px |
| y     | number            | No       | –       | <AndroidOnly /> <IOSOnly /> <ClayOnly /> |       | y position relative to the window, in px |

Callback when touch on the overlay

### `bindrequestclose`

Android
Clay
Harmony
```tsx
bindrequestclose = (e: BaseEvent) => {};
```

Callback when the back button is clicked.

### `bindshowoverlay`

Android
iOS
Clay
Harmony
```tsx
bindshowoverlay = (e: BaseEvent) => {};
```

Callback when the overlay is displayed



---
url: /api/elements/built-in/refresh-API.md
---

# 

## Attributes

### `enable-refresh`

Android
iOS
Harmony
```tsx
// @defaultValue: true
'enable-refresh'?: boolean;
```

Determines if dragging down or calling autoStartRefresh can trigger the startrefresh event.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindheaderoffset`

Android
iOS
Harmony
```tsx
bindheaderoffset = (e: RefreshHeaderOffsetEvent) => {};
```

| Field         | Type    | Optional | Default | Platforms                                   | Since | Description                                                    |
| ------------- | ------- | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------------------- |
| isDragging    | boolean | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates if  `<refresh-header>`  is being dragged             |
| offsetPercent | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | The ratio of the pull-down movement distance to its own height |

Triggered during movement when
`<refresh-header>`
is exposed.

### `bindrefreshstatechange`

Android
iOS
Harmony
```tsx
bindrefreshstatechange = (e: RefreshStateChangeEvent) => {};
```

| Field | Type         | Optional | Default | Platforms                                   | Since | Description                                        |
| ----- | ------------ | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------- |
| state | RefreshState | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates if  `<refresh-header>`  is being dragged |

Triggered when
`<refresh-header>`
state changes.

### `bindstartrefresh`

Android
iOS
Harmony
```tsx
bindstartrefresh = (e: RefreshStartRefreshEvent) => {};
```

| Field    | Type    | Optional | Default | Platforms                                   | Since | Description                                                          |
| -------- | ------- | -------- | ------- | ------------------------------------------- | ----- | -------------------------------------------------------------------- |
| isManual | boolean | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> |       | Indicates whether the startrefresh event is triggered by manual drag |

Triggered when enable-refresh is true, and dragging down or calling autoStartRefresh (enters refresh state).

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `autoStartRefresh`

Android
iOS
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'autoStartRefresh',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

When enable-refresh is true, call this method to expose the entire
`<refresh-header>`
, triggering the startrefresh event, after which
`<refresh-header>`
will attach to the top edge of the refresh's viewport.

### `finishRefresh`

Android
iOS
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'finishRefresh',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Called after the startrefresh event to end the refresh state, making
`<refresh-header>`
rebound.



---
url: /api/elements/built-in/scroll-view-API.md
---

# 

## Attributes

### `bounces`

iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
bounces?: boolean;
```

Enable bounce effect

### `enable-scroll`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
'enable-scroll'?: boolean;
```

Enable dragging

### `initial-scroll-offset`

Android
iOS
Clay
Harmony
2.17

```tsx
// @defaultValue: 0
'initial-scroll-offset'?: number;
```

Initial scroll position, only effective once, in PX

### `initial-scroll-to-index`

Android
iOS
Clay
Harmony
2.17

```tsx
// @defaultValue: 0
'initial-scroll-to-index'?: number;
```

Scroll to specified child node on first screen, only effective once. All direct child nodes must be flatten=false.

### `lower-threshold`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'lower-threshold'?: number;
```

Set upper threshold to bindscrolltoupper event.

### `scroll-bar-enable`

iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: true
'scroll-bar-enable'?: boolean;
```

Enable scrollbar

### `scroll-orientation`

Android
iOS
Clay
Harmony
3.0

```tsx
// @defaultValue: 'vertical'
'scroll-orientation'?: 'vertical' | 'horizontal';
```

Replacement of scroll-x and scroll-y

### `upper-threshold`

Android
iOS
Clay
Harmony
1.4

```tsx
// @defaultValue: 0
'upper-threshold'?: number;
```

Set upper threshold to bindscrolltoupper event.

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindcontentsizechanged`

Android
iOS
Harmony
1.6

```tsx
bindcontentsizechanged = (e: ContentSizeChangedEvent) => {};
```

This event is triggered when the scrollview's content size changed.

### `bindscroll`

Android
iOS
Clay
Harmony
1.4

```tsx
bindscroll = (e: ScrollEvent) => {};
```

This event is triggered when the scrollview is scrolling.

### `bindscrollend`

Android
iOS
Clay
Harmony
1.6

```tsx
bindscrollend = (e: ScrollEndEvent) => {};
```

This event is triggered when the scrollview's scroll ended.

### `bindscrolltolower`

Android
iOS
Harmony
1.4

```tsx
bindscrolltolower = (e: ScrollToLowerEvent) => {};
```

This event is triggered when the lower/right edge of the scrolling area intersects with the visible area defined by the lowerThreshold.

### `bindscrolltoupper`

Android
iOS
Harmony
1.4

```tsx
bindscrolltoupper = (e: ScrollToUpperEvent) => {};
```

This event is triggered when the upper/left edge of the scrolling area intersects with the visible area defined by the upperThreshold.

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `autoScroll`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'autoScroll',
      params: {
        /**
         * The distance of each second's scrolling, which supports positive and negative values. The unit of distance can be "px", "rpx", "ppx", or null (for iOS, the value must be greater than 1/screen.scale px).
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        rate: number;
        /**
         * Start/stop automatic scrolling.
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        start: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Automatic scrolling

### `getScrollInfo`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getScrollInfo',
      success: Callback<{
        /**
         * Total scrollable range along orientation, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollRange: number;
        /**
         * Content offset on X-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollX: number;
        /**
         * Content offset on Y-axis, in PX
         * @Android
         * @iOS
         * @Harmony
         * @PC
         */
        scrollY: number;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get scroll info

### `scrollBy`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollBy',
      params: {
        /**
         * Offset to scroll
         */
        offset?: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Scroll by specified offset

### `scrollTo`

Android
iOS
Clay
Harmony
```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'scrollTo',
      params: {
        /**
         * Target item index
         * @defaultValue 0
         */
        index?: number;
        /**
         * Offset relative to target node
         */
        offset?: number;
        /**
         * Enable scroll animation
         */
        smooth?: boolean;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Scroll to specified position



---
url: /api/elements/built-in/svg-API.md
---

# 

## Attributes

### `content`

Android
iOS
Clay
Harmony
```tsx
content?: string;
```

SVG XML content

### `src`

Android
iOS
Clay
Harmony
```tsx
src?: string;
```

SVG resource URL

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindload`

Android
iOS
Clay
Harmony
```tsx
bindload = (e: BaseEvent) => {};
```

SVG Loaded



---
url: /api/elements/built-in/textarea-API.md
---

# 

## Attributes

### `android-fullscreen-mode`

Android
3.4

```tsx
// @defaultValue: true
'android-fullscreen-mode'?: boolean;
```

Whether to enter the full-screen input mode when in landscape screen, in which the keyboard and input box will take up the entire screen

### `bounces`

iOS
3.4

```tsx
// @defaultValue: true
bounces?: boolean;
```

Bounce effect for iOS

### `confirm-type`

iOS
Harmony
3.4

```tsx
// @defaultValue: 'done'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

Android
iOS
Harmony
3.5

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `enable-scroll-bar`

Android
iOS
3.6

```tsx
// @defaultValue: false
'enable-scroll-bar'?: boolean;
```

Whether to show scroll bar, on HarmonyOS, the scroll bar will always be shown

### `input-filter`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

iOS
3.4

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

iOS
3.4

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `line-spacing`

Android
iOS
3.4

```tsx
// @defaultValue: undefined
'line-spacing'?: number | any | any;
```

Line spacing

### `maxlength`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `maxlines`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: undefined
maxlines?: number;
```

Max input lines

### `placeholder`

Android
iOS
Harmony
3.4

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

Android
iOS
3.4

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

Android
iOS
Harmony
3.4

```tsx
// @defaultValue: "text"
type?: 'number' | 'text' | 'digit' | 'tel' | 'email';
```

Input content type

## Events

Frontend can bind corresponding event callbacks to listen for runtime behaviors of the element, as shown below.

### `bindblur`

Android
iOS
Harmony
3.4

```tsx
bindblur = (e: TextAreaBlurEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Blurred

### `bindconfirm`

Android
iOS
Harmony
3.4

```tsx
bindconfirm = (e: TextAreaConfirmEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Confirm button clicked, only work when confirm-type is defined

### `bindfocus`

Android
iOS
Harmony
3.4

```tsx
bindfocus = (e: TextAreaFocusEvent) => {};
```

| Field | Type   | Optional | Default | Platforms                                                                    | Since | Description   |
| ----- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ------------- |
| value | string | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content |

Focused

### `bindinput`

Android
iOS
Harmony
3.4

```tsx
bindinput = (e: TextAreaInputEvent) => {};
```

| Field          | Type    | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| isComposing    | boolean | Yes      | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Is composing or not                 |
| selectionEnd   | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |
| value          | string  | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | Input content                       |

Input content changed

### `bindselection`

Android
iOS
Harmony
3.4

```tsx
bindselection = (e: TextAreaSelectionChangeEvent) => {};
```

| Field          | Type   | Optional | Default | Platforms                                                                    | Since | Description                         |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | ----- | ----------------------------------- |
| selectionEnd   | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The end position of the selection   |
| selectionStart | number | No       | –       | <AndroidOnly /> <IOSOnly /> <HarmonyOnly /> <VersionBadge>3.4</VersionBadge> | 3.4   | The start position of the selection |

Input selection changed

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `blur`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'blur',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Release focus

### `focus`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'getValue',
      success: Callback<{
        /**
         * Is composing or not, iOS only
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        isComposing: boolean;
        /**
         * End position of the cursor
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Begin position of the cursor
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      }>;
      fail: function (res) {},
    })
    .exec();

```

Get input content

### `setSelectionRange`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setSelectionRange',
      params: {
        /**
         * End position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionEnd: number;
        /**
         * Start position of the selection
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        selectionStart: number;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set selection range

### `setValue`

Android
iOS
Harmony
3.4

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'setValue',
      params: {
        /**
         * Input content
         * @Android
         * @iOS
         * @Harmony
         * @Web
         * @since 3.4
         */
        value: string;
      };
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Set input content



---
url: /api/elements/built-in/title-bar-view-API.md
---

# 

`<title-bar-view>` is similar to the `app-region` style on the web and allows developers to customize the draggable area of the window.

## Attributes

### `moveable`

Clay Windows
Clay macOS
```tsx
// @defaultValue: false
moveable?: boolean;
```

When set to `true`, dragging the title bar view moves the window.



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.rootpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetContext](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.md) > [rootPath](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetcontext.rootpath.md)

## ExternalsPresetContext.rootPath property

The current Rsbuild project root path.

**Signature:**

```typescript
rootPath: string;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.extends.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md) > [extends](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.extends.md)

## ExternalsPresetDefinition.extends property

Other preset names to apply before the current preset.

**Signature:**

```typescript
extends?: string | string[];
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolveexternals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md) > [resolveExternals](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolveexternals.md)

## ExternalsPresetDefinition.resolveExternals property

Resolve external request mappings contributed by this preset.

**Signature:**

```typescript
resolveExternals?: (value: boolean | object, context: ExternalsPresetContext) => ExternalsLoadingPluginOptions['externals'];
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolvemanagedassets.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresetDefinition](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.md) > [resolveManagedAssets](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresetdefinition.resolvemanagedassets.md)

## ExternalsPresetDefinition.resolveManagedAssets property

Resolve managed bundle assets contributed by this preset.

**Signature:**

```typescript
resolveManagedAssets?: (value: boolean | object, context: ExternalsPresetContext) => Map<string, string> | Record<string, string>;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.reactlynx.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ExternalsPresets](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.md) > [reactlynx](/api/rspeedy/external-bundle-rsbuild-plugin.externalspresets.reactlynx.md)

## ExternalsPresets.reactlynx property

Load the ReactLynx runtime bundle and wire its standard module globals.

**Signature:**

```typescript
reactlynx?: boolean | ReactLynxExternalsPresetOptions;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalbundleroot.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) > [externalBundleRoot](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalbundleroot.md)

## PluginExternalBundleOptions.externalBundleRoot property

Root directory that stores project-owned external bundles referenced by `bundlePath`<!-- -->.

`pluginExternalBundle` uses this directory for both development serving and build-time asset emission. Prefer setting this explicitly when external bundles are built into a separate output folder, such as `dist-external-bundle`<!-- -->.

**Signature:**

```typescript
externalBundleRoot?: string;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) > [externals](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externals.md)

## PluginExternalBundleOptions.externals property

Additional explicit externals to load.

**Signature:**

```typescript
externals?: Record<string, PluginExternalConfig>;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresetdefinitions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) > [externalsPresetDefinitions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresetdefinitions.md)

## PluginExternalBundleOptions.externalsPresetDefinitions property

Definitions for custom externals presets enabled by `externalsPresets`<!-- -->.

Use this to add business-specific presets such as `lynxUi`<!-- -->, or to extend a built-in preset through `extends`<!-- -->.

**Signature:**

```typescript
externalsPresetDefinitions?: ExternalsPresetDefinitions;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresets.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalBundleOptions](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.md) > [externalsPresets](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundleoptions.externalspresets.md)

## PluginExternalBundleOptions.externalsPresets property

Presets for external libraries.

Same as [https://rspack.rs/config/externals\\#externalspresets](https://rspack.rs/config/externals\\#externalspresets) but for Lynx.

**Signature:**

```typescript
externalsPresets?: ExternalsPresets;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.bundlepath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalValue](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md) > [bundlePath](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.bundlepath.md)

## PluginExternalValue.bundlePath property

Bundle path resolved against the runtime public path.

Prefer this over `url` when the external bundle should be emitted or served as part of the current project. `pluginExternalBundle` can use this information to manage local bundle files, while the runtime keeps the final URL aligned with the active `publicPath`<!-- -->.

**Signature:**

```typescript
bundlePath?: string;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.url.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [PluginExternalValue](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.md) > [url](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalvalue.url.md)

## PluginExternalValue.url property

> Warning: This API is now obsolete.
>
> Prefer `bundlePath`<!-- -->, which resolves through the runtime public path and lets higher-level tooling manage asset emission.

Bundle URL.

Use this only when the external bundle lives outside the current build output and should not be emitted or served by `pluginExternalBundle`<!-- -->.

**Signature:**

```typescript
url?: string;
```



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.bundlepath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) > [bundlePath](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.bundlepath.md)

## ReactLynxExternalsPresetOptions.bundlePath property

Emit the ReactLynx runtime bundle into the current build output and load it through the generated runtime public path.

Prefer this over `url` for normal Rspeedy projects. In addition to letting the runtime resolve the final URL from `publicPath`<!-- -->, the plugin will also copy the corresponding `@lynx-js/react-umd` bundle into the emitted assets, so application bundles can reference it without requiring an extra manual copy step when publishing.

**Signature:**

```typescript
bundlePath?: string;
```

## Default Value

`'react.lynx.bundle'`



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.reactumdpackagename.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) > [reactUmdPackageName](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.reactumdpackagename.md)

## ReactLynxExternalsPresetOptions.reactUmdPackageName property

Package name that provides the ReactLynx runtime bundle.

Override this when wrapping the plugin for another distribution, such as `@byted-lynx/react-umd`<!-- -->.

**Signature:**

```typescript
reactUmdPackageName?: string;
```

## Default Value

`'@lynx-js/react-umd'`



---
url: /api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.url.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/external-bundle-rsbuild-plugin](/api/rspeedy/external-bundle-rsbuild-plugin.md) > [ReactLynxExternalsPresetOptions](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.md) > [url](/api/rspeedy/external-bundle-rsbuild-plugin.reactlynxexternalspresetoptions.url.md)

## ReactLynxExternalsPresetOptions.url property

> Warning: This API is now obsolete.
>
> Prefer `bundlePath`<!-- -->, which resolves through the runtime public path and enables automatic asset emission.

Override the runtime bundle URL directly.

Use this only when the ReactLynx runtime is hosted outside the current build output, for example on a CDN. Unlike `bundlePath`<!-- -->, this does not emit any extra asset into the current compilation.

**Signature:**

```typescript
url?: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin._constructor_.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPlugin](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.md) > [(constructor)](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin._constructor_.md)

## ExternalsLoadingPlugin.(constructor)

Constructs a new instance of the `ExternalsLoadingPlugin` class

**Signature:**

```typescript
constructor(options: ExternalsLoadingPluginOptions);
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

options

</td><td>

[ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md)

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.apply.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPlugin](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.md) > [apply](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.apply.md)

## ExternalsLoadingPlugin.apply() method

**Signature:**

```typescript
apply(compiler: Compiler): void;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

compiler

</td><td>

Compiler

</td><td>

</td></tr>
</tbody></table>

**Returns:**

void



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPlugin](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.md)

## ExternalsLoadingPlugin class

The webpack plugin to load lynx external bundles.

**Signature:**

```typescript
export declare class ExternalsLoadingPlugin 
```

## Example

```js
// webpack.config.js
import { ExternalsLoadingPlugin } from '@lynx-js/externals-loading-webpack-plugin';

export default {
  plugins: [
    new ExternalsLoadingPlugin({
      mainThreadLayer: 'main-thread',
      backgroundLayer: 'background',
      mainThreadChunks: ['index__main-thread'],
      backgroundChunks: ['index'],
      externals: {
       'lodash': {
         url: 'http://lodash.lynx.bundle',
         async: true,
         background: {
           sectionPath: 'background',
         },
         mainThread: {
           sectionPath: 'mainThread',
         },
       },
      }
    })
  ]
}
```

## Constructors

<table><thead><tr><th>

Constructor

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[(constructor)(options)](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin._constructor_.md)

</td><td>

</td><td>

Constructs a new instance of the `ExternalsLoadingPlugin` class

</td></tr>
</tbody></table>

## Methods

<table><thead><tr><th>

Method

</th><th>

Modifiers

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[apply(compiler)](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.apply.md)

</td><td>

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.backgroundlayer.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [backgroundLayer](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.backgroundlayer.md)

## ExternalsLoadingPluginOptions.backgroundLayer property

The name of the background layer.

**Signature:**

```typescript
backgroundLayer: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.externals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [externals](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.externals.md)

## ExternalsLoadingPluginOptions.externals property

Specify the externals to be loaded. The externals should be Lynx Bundles.

**Signature:**

```typescript
externals: Record<string, ExternalValue>;
```

## Example 1

Load `lodash` library in background layer and `main-thread` layer.

```js
module.exports = {
 plugins: [
   new ExternalsLoadingPlugin({
     externals: {
       lodash: {
         url: 'http://lodash.lynx.bundle',
         background: { sectionPath: 'background' },
         mainThread: { sectionPath: 'mainThread' },
       },
     },
   }),
 ],
};
```

## Example 2

Load `lodash` library only in background layer.

```js
module.exports = {
 plugins: [
   new ExternalsLoadingPlugin({
     externals: {
       lodash: {
         url: 'http://lodash.lynx.bundle',
         background: { sectionPath: 'background' }
       },
     },
   }),
 ],
};
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.globalobject.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [globalObject](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.globalobject.md)

## ExternalsLoadingPluginOptions.globalObject property

This option indicates what global object will be used to mount the library.

In Lynx, the library will be mounted to `lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")]` by default.

If you have enabled share js context and want to reuse the library by mounting to the global object, you can set this option to `'globalThis'`<!-- -->.

'lynx'

**Signature:**

```typescript
globalObject?: 'lynx' | 'globalThis' | undefined;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.mainthreadlayer.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [mainThreadLayer](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.mainthreadlayer.md)

## ExternalsLoadingPluginOptions.mainThreadLayer property

The name of the main thread layer.

**Signature:**

```typescript
mainThreadLayer: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md)

## ExternalsLoadingPluginOptions interface

The options of the `ExternalsLoadingPlugin`<!-- -->.

**Signature:**

```typescript
export interface ExternalsLoadingPluginOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[backgroundLayer](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.backgroundlayer.md)

</td><td>

</td><td>

string

</td><td>

The name of the background layer.

</td></tr>
<tr><td>

[externals](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.externals.md)

</td><td>

</td><td>

Record\<string, [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md)<!-- -->>

</td><td>

Specify the externals to be loaded. The externals should be Lynx Bundles.

</td></tr>
<tr><td>

[globalObject?](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.globalobject.md)

</td><td>

</td><td>

'lynx' | 'globalThis' | undefined

</td><td>

_(Optional)_ This option indicates what global object will be used to mount the library.

In Lynx, the library will be mounted to `lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")]` by default.

If you have enabled share js context and want to reuse the library by mounting to the global object, you can set this option to `'globalThis'`<!-- -->.

'lynx'

</td></tr>
<tr><td>

[mainThreadLayer](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.mainthreadlayer.md)

</td><td>

</td><td>

string

</td><td>

The name of the main thread layer.

</td></tr>
<tr><td>

[retries?](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.retries.md)

</td><td>

</td><td>

number | undefined

</td><td>

_(Optional)_ The number of additional attempts when fetching the external bundle times out (`response.code === -2`<!-- -->).

</td></tr>
<tr><td>

[timeout?](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.timeout.md)

</td><td>

</td><td>

number | undefined

</td><td>

_(Optional)_ The timeout in milliseconds for loading the externals.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.retries.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [retries](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.retries.md)

## ExternalsLoadingPluginOptions.retries property

The number of additional attempts when fetching the external bundle times out (`response.code === -2`<!-- -->).

**Signature:**

```typescript
retries?: number | undefined;
```

## Default Value

0



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.timeout.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md) > [timeout](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.timeout.md)

## ExternalsLoadingPluginOptions.timeout property

The timeout in milliseconds for loading the externals.

**Signature:**

```typescript
timeout?: number | undefined;
```

## Default Value

2000



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.async.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [async](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.async.md)

## ExternalValue.async property

Whether the source should be loaded asynchronously or not.

**Signature:**

```typescript
async?: boolean;
```

## Default Value

`true`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.background.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [background](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.background.md)

## ExternalValue.background property

The options of the background layer.

**Signature:**

```typescript
background?: LayerOptions;
```

## Default Value

`undefined`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.bundlepath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [bundlePath](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.bundlepath.md)

## ExternalValue.bundlePath property

The bundle path resolved against the runtime public path.

Prefer this over `url` when the bundle should follow the active `publicPath`<!-- -->. The runtime will load it with `publicPath + bundlePath`<!-- -->, which keeps external bundle resolution aligned with the current build output without hard-coding an absolute URL into the generated runtime code.

**Signature:**

```typescript
bundlePath?: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.libraryname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [libraryName](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.libraryname.md)

## ExternalValue.libraryName property

The name of the library. Same as [https://webpack.js.org/configuration/externals/\\#string](https://webpack.js.org/configuration/externals/\\#string).

By default, the library name is the same as the externals key. For example:

The config

```js
ExternalsLoadingPlugin({
  externals: {
    lodash: {
      url: '……',
    }
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].lodash',
}
```

If one external bundle contains multiple modules, should set the same library name to ensure it's loaded only once. For example:

```js
ExternalsLoadingPlugin({
  externals: {
    lodash: {
      libraryName: 'Lodash',
      url: '……',
    },
    'lodash-es': {
      libraryName: 'Lodash',
      url: '……',
    }
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
  'lodash-es': 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
}
```

You can pass an array to specify subpath of the external. Same as [https://webpack.js.org/configuration/externals/\\#string-1](https://webpack.js.org/configuration/externals/\\#string-1). For example:

```js
ExternalsLoadingPlugin({
  externals: {
    preact: {
      libraryName: ['ReactLynx', 'Preact'],
      url: '……',
    },
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  preact: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].ReactLynx.Preact',
}
```

**Signature:**

```typescript
libraryName?: string | string[];
```

## Default Value

`undefined`

## Example

`Lodash`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.mainthread.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [mainThread](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.mainthread.md)

## ExternalValue.mainThread property

The options of the main-thread layer.

**Signature:**

```typescript
mainThread?: LayerOptions;
```

## Default Value

`undefined`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md)

## ExternalValue interface

The value item of the externals.

**Signature:**

```typescript
export interface ExternalValue 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[async?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.async.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ Whether the source should be loaded asynchronously or not.

</td></tr>
<tr><td>

[background?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.background.md)

</td><td>

</td><td>

[LayerOptions](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.md)

</td><td>

_(Optional)_ The options of the background layer.

</td></tr>
<tr><td>

[bundlePath?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.bundlepath.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ The bundle path resolved against the runtime public path.

Prefer this over `url` when the bundle should follow the active `publicPath`<!-- -->. The runtime will load it with `publicPath + bundlePath`<!-- -->, which keeps external bundle resolution aligned with the current build output without hard-coding an absolute URL into the generated runtime code.

</td></tr>
<tr><td>

[libraryName?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.libraryname.md)

</td><td>

</td><td>

string | string\[]

</td><td>

_(Optional)_ The name of the library. Same as [https://webpack.js.org/configuration/externals/\\#string](https://webpack.js.org/configuration/externals/\\#string).

By default, the library name is the same as the externals key. For example:

The config

```js
ExternalsLoadingPlugin({
  externals: {
    lodash: {
      url: '……',
    }
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].lodash',
}
```

If one external bundle contains multiple modules, should set the same library name to ensure it's loaded only once. For example:

```js
ExternalsLoadingPlugin({
  externals: {
    lodash: {
      libraryName: 'Lodash',
      url: '……',
    },
    'lodash-es': {
      libraryName: 'Lodash',
      url: '……',
    }
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
  'lodash-es': 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
}
```

You can pass an array to specify subpath of the external. Same as [https://webpack.js.org/configuration/externals/\\#string-1](https://webpack.js.org/configuration/externals/\\#string-1). For example:

```js
ExternalsLoadingPlugin({
  externals: {
    preact: {
      libraryName: ['ReactLynx', 'Preact'],
      url: '……',
    },
  }
})
```

Will generate the following webpack externals config:

```js
externals: {
  preact: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].ReactLynx.Preact',
}
```

</td></tr>
<tr><td>

[mainThread?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.mainthread.md)

</td><td>

</td><td>

[LayerOptions](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.md)

</td><td>

_(Optional)_ The options of the main-thread layer.

</td></tr>
<tr><td>

[retries?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.retries.md)

</td><td>

</td><td>

number

</td><td>

_(Optional)_ The number of additional attempts when fetching the external bundle times out (`response.code === -2`<!-- -->).

</td></tr>
<tr><td>

[timeout?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.timeout.md)

</td><td>

</td><td>

number

</td><td>

_(Optional)_ The wait time in milliseconds.

</td></tr>
<tr><td>

[url?](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.url.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ The final bundle URL to fetch directly at runtime.

Use this when the external bundle is hosted outside the current build output, such as on a CDN. If both `url` and `bundlePath` are provided, `url` takes precedence because it is already the fully resolved address.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.retries.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [retries](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.retries.md)

## ExternalValue.retries property

The number of additional attempts when fetching the external bundle times out (`response.code === -2`<!-- -->).

**Signature:**

```typescript
retries?: number;
```

## Default Value

`0`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.timeout.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [timeout](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.timeout.md)

## ExternalValue.timeout property

The wait time in milliseconds.

**Signature:**

```typescript
timeout?: number;
```

## Default Value

`2000`



---
url: /api/rspeedy/externals-loading-webpack-plugin.externalvalue.url.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md) > [url](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.url.md)

## ExternalValue.url property

The final bundle URL to fetch directly at runtime.

Use this when the external bundle is hosted outside the current build output, such as on a CDN. If both `url` and `bundlePath` are provided, `url` takes precedence because it is already the fully resolved address.

**Signature:**

```typescript
url?: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.layeroptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [LayerOptions](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.md)

## LayerOptions interface

The options of the background or main-thread layer.

**Signature:**

```typescript
export interface LayerOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[sectionPath](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.sectionpath.md)

</td><td>

</td><td>

string

</td><td>

The path in `customSections`<!-- -->.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/externals-loading-webpack-plugin.layeroptions.sectionpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md) > [LayerOptions](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.md) > [sectionPath](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.sectionpath.md)

## LayerOptions.sectionPath property

The path in `customSections`<!-- -->.

**Signature:**

```typescript
sectionPath: string;
```



---
url: /api/rspeedy/externals-loading-webpack-plugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/externals-loading-webpack-plugin](/api/rspeedy/externals-loading-webpack-plugin.md)

## externals-loading-webpack-plugin package

A webpack plugin to load externals in Lynx. Use `lynx.fetchBundle()` and `lynx.loadScript()` API to load and parse the externals.

## Remarks

Requires Lynx version 3.5 or later.

## Classes

<table><thead><tr><th>

Class

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ExternalsLoadingPlugin](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingplugin.md)

</td><td>

The webpack plugin to load lynx external bundles.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ExternalsLoadingPluginOptions](/api/rspeedy/externals-loading-webpack-plugin.externalsloadingpluginoptions.md)

</td><td>

The options of the `ExternalsLoadingPlugin`<!-- -->.

</td></tr>
<tr><td>

[ExternalValue](/api/rspeedy/externals-loading-webpack-plugin.externalvalue.md)

</td><td>

The value item of the externals.

</td></tr>
<tr><td>

[LayerOptions](/api/rspeedy/externals-loading-webpack-plugin.layeroptions.md)

</td><td>

The options of the background or main-thread layer.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.encodeoptions.engineversion.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [EncodeOptions](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.md) > [engineVersion](/api/rspeedy/lynx-bundle-rslib-config.encodeoptions.engineversion.md)

## EncodeOptions.engineVersion property

The engine version of the external bundle.

**Signature:**

```typescript
engineVersion?: string;
```

## Default Value

'3.5'



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.output.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleLibConfig](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.md) > [output](/api/rspeedy/lynx-bundle-rslib-config.externalbundlelibconfig.output.md)

## ExternalBundleLibConfig.output property

**Signature:**

```typescript
output?: OutputConfig;
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md) > [(constructor)](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin._constructor_.md)

## ExternalBundleWebpackPlugin.(constructor)

Constructs a new instance of the `ExternalBundleWebpackPlugin` class

**Signature:**

```typescript
constructor(options: ExternalBundleWebpackPluginOptions);
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

options

</td><td>

[ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md)

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.apply.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.md) > [apply](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackplugin.apply.md)

## ExternalBundleWebpackPlugin.apply() method

**Signature:**

```typescript
apply(compiler: Compiler): void;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

compiler

</td><td>

Compiler

</td><td>

</td></tr>
</tbody></table>

**Returns:**

void



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [bundleFileName](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.bundlefilename.md)

## ExternalBundleWebpackPluginOptions.bundleFileName property

The external bundle filename.

**Signature:**

```typescript
bundleFileName: string;
```

## Example

```js
new ExternalBundleWebpackPlugin({
  bundleFileName: 'lib.lynx.bundle'
})
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [encode](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.encode.md)

## ExternalBundleWebpackPluginOptions.encode property

The encode method which is exported from lynx-tasm package.

**Signature:**

```typescript
encode: (opts: unknown) => Promise<{
        buffer: Buffer;
    }>;
```

## Example

```js
import { getEncodeMode } from '@lynx-js/tasm';

new ExternalBundleWebpackPlugin({
  encode: getEncodeMode()
})
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.engineversion.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [engineVersion](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.engineversion.md)

## ExternalBundleWebpackPluginOptions.engineVersion property

The engine version of the external bundle.

**Signature:**

```typescript
engineVersion?: string | undefined;
```

## Default Value

'3.5'



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.mainthreadchunks.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalBundleWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.md) > [mainThreadChunks](/api/rspeedy/lynx-bundle-rslib-config.externalbundlewebpackpluginoptions.mainthreadchunks.md)

## ExternalBundleWebpackPluginOptions.mainThreadChunks property

The main thread chunks of the external bundle.

**Signature:**

```typescript
mainThreadChunks?: string[] | undefined;
```

## Default Value

\[]



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.extends.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalsPresetDefinition](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md) > [extends](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.extends.md)

## ExternalsPresetDefinition.extends property

Other preset names to include before applying the current preset.

**Signature:**

```typescript
extends?: string | string[];
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.externals.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [ExternalsPresetDefinition](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.md) > [externals](/api/rspeedy/lynx-bundle-rslib-config.externalspresetdefinition.externals.md)

## ExternalsPresetDefinition.externals property

Externals contributed by this preset.

**Signature:**

```typescript
externals?: Externals;
```



---
url: /api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) > [(constructor)](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin._constructor_.md)

## MainThreadRuntimeWrapperWebpackPlugin.(constructor)

Constructs a new instance of the `MainThreadRuntimeWrapperWebpackPlugin` class

**Signature:**

```typescript
constructor(options?: Partial<MainThreadRuntimeWrapperWebpackPluginOptions>);
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

options

</td><td>

Partial\<[MainThreadRuntimeWrapperWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md)<!-- -->>

</td><td>

_(Optional)_

</td></tr>
</tbody></table>



---
url: /api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [MainThreadRuntimeWrapperWebpackPlugin](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.md) > [apply](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackplugin.apply.md)

## MainThreadRuntimeWrapperWebpackPlugin.apply() method

**Signature:**

```typescript
apply(compiler: Compiler): void;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

compiler

</td><td>

Compiler

</td><td>

</td></tr>
</tbody></table>

**Returns:**

void



---
url: /api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/lynx-bundle-rslib-config](/api/rspeedy/lynx-bundle-rslib-config.md) > [MainThreadRuntimeWrapperWebpackPluginOptions](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.md) > [test](/api/rspeedy/lynx-bundle-rslib-config.mainthreadruntimewrapperwebpackpluginoptions.test.md)

## MainThreadRuntimeWrapperWebpackPluginOptions.test property

Include all modules that pass test assertion.

**Signature:**

```typescript
test: BannerPlugin['options']['test'];
```

## Default Value

`/\.js$/`



---
url: /api/rspeedy/qrcode-rsbuild-plugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md)

## qrcode-rsbuild-plugin package

A rsbuild plugin that print the template.js url using QRCode.

## Functions

<table><thead><tr><th>

Function

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[pluginQRCode(options)](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)

</td><td>

Create a rsbuild plugin for printing QRCode.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md)

</td><td>

The options for [pluginQRCode()](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->.

</td></tr>
</tbody></table>

## Type Aliases

<table><thead><tr><th>

Type Alias

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md)

</td><td>

Customize the generated schema.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/qrcode-rsbuild-plugin](/api/rspeedy/qrcode-rsbuild-plugin.md) > [PluginQRCodeOptions](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.md)

## PluginQRCodeOptions interface

The options for [pluginQRCode()](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcode.md)<!-- -->.

**Signature:**

```typescript
export interface PluginQRCodeOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[schema?](/api/rspeedy/qrcode-rsbuild-plugin.pluginqrcodeoptions.schema.md)

</td><td>

</td><td>

[CustomizedSchemaFn](/api/rspeedy/qrcode-rsbuild-plugin.customizedschemafn.md) | undefined

</td><td>

_(Optional)_ Customize the generated schema.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md)

## AddComponentElementConfig interface

Controls whether to add wrapper elements for components

**Signature:**

```typescript
export interface AddComponentElementConfig 
```

## Remarks

Default value: `false`

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[compilerOnly](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.compileronly.md)

</td><td>

</td><td>

boolean

</td><td>

Whether to only add component element during compilation

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)

## CompatVisitorConfig interface

The `compat` option controls compatibilities with ReactLynx2.0.

**Signature:**

```typescript
export interface CompatVisitorConfig 
```

## Remarks

These options should only be used for migrating from ReactLynx2.0.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[addComponentElement](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.addcomponentelement.md)

</td><td>

</td><td>

boolean | [AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md)

</td><td>

Controls whether to add wrapper elements for components

</td></tr>
<tr><td>

[additionalComponentAttributes](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.additionalcomponentattributes.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Specifies additional component attributes list, these attributes will be passed to the wrapped `<view>` instead of the component.

</td></tr>
<tr><td>

[componentsPkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.componentspkg.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Specifies the list of component package names that need compatibility processing

</td></tr>
<tr><td>

[darkMode?](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.darkmode.md)

</td><td>

</td><td>

boolean | DarkModeConfig

</td><td>

_(Optional)_

</td></tr>
<tr><td>

[disableDeprecatedWarning](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.disabledeprecatedwarning.md)

</td><td>

</td><td>

boolean

</td><td>

Whether to disable deprecated warnings

</td></tr>
<tr><td>

[newRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.newruntimepkg.md)

</td><td>

</td><td>

string

</td><td>

Specifies the new runtime package name

</td></tr>
<tr><td>

[oldRuntimePkg](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.oldruntimepkg.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Specifies the list of old runtime package names that need compatibility processing

</td></tr>
<tr><td>

[removeComponentAttrRegex?](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.removecomponentattrregex.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ Regular expression used to remove component attributes

</td></tr>
<tr><td>

[simplifyCtorLikeReactLynx2](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.simplifyctorlikereactlynx2.md)

</td><td>

</td><td>

boolean

</td><td>

Whether to simplify constructor calls like ReactLynx 2

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)

## DefineDceVisitorConfig interface

Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

**Signature:**

```typescript
export interface DefineDceVisitorConfig 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[define](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.define.md)

</td><td>

</td><td>

Record\<string, string>

</td><td>

Replaces variables in your code with other values or expressions at compile time.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.extractstrconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)

## ExtractStrConfig interface

Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

**Signature:**

```typescript
export interface ExtractStrConfig 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[strLength](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.strlength.md)

</td><td>

</td><td>

number

</td><td>

The minimum length of string literals to be extracted.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.getlynxtemplatepluginhooks.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [LynxTemplatePlugin](/api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.md) > [getLynxTemplatePluginHooks](/api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.getlynxtemplatepluginhooks.md)

## LynxTemplatePlugin.getLynxTemplatePluginHooks property

**Signature:**

```typescript
getLynxTemplatePluginHooks: typeof InnerLynxTemplatePlugin.getLynxTemplatePluginHooks;
```



---
url: /api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [LynxTemplatePlugin](/api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.md)

## LynxTemplatePlugin interface

**Signature:**

```typescript
interface LynxTemplatePlugin 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[getLynxTemplatePluginHooks](/api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.getlynxtemplatepluginhooks.md)

</td><td>

</td><td>

typeof InnerLynxTemplatePlugin.getLynxTemplatePluginHooks

</td><td>

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md)

## react-rsbuild-plugin package

A rsbuild plugin that integrates with ReactLynx.

## Functions

<table><thead><tr><th>

Function

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[pluginReactLynx(userOptions)](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

</td><td>

Create a rsbuild plugin for ReactLynx.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[AddComponentElementConfig](/api/rspeedy/react-rsbuild-plugin.addcomponentelementconfig.md)

</td><td>

Controls whether to add wrapper elements for components

</td></tr>
<tr><td>

[CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)

</td><td>

The `compat` option controls compatibilities with ReactLynx2.0.

</td></tr>
<tr><td>

[DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)

</td><td>

Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

</td></tr>
<tr><td>

[ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)

</td><td>

Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

</td></tr>
<tr><td>

[LynxTemplatePlugin](/api/rspeedy/react-rsbuild-plugin.lynxtemplateplugin.md)

</td><td>

</td></tr>
<tr><td>

[PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md)

</td><td>

Options of [pluginReactLynx()](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

</td></tr>
<tr><td>

[ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)

</td><td>

How main-thread code will be shaken.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [globalPropsMode](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.md)

## PluginReactLynxOptions.globalPropsMode property

Configure the update mode of `lynx.__globalProps`<!-- -->.

This flag has two options:

`'reactive'`<!-- -->: `UpdateGlobalProps` will trigger update automatically.

`'event'`<!-- -->: `UpdateGlobalProps` will trigger global event and users need to trigger update in the event handler.

**Signature:**

```typescript
globalPropsMode?: 'reactive' | 'event';
```

## Default Value

`'reactive'`



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md)

## PluginReactLynxOptions interface

Options of [pluginReactLynx()](/api/rspeedy/react-rsbuild-plugin.pluginreactlynx.md)

**Signature:**

```typescript
export interface PluginReactLynxOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[compat?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.compat.md)

</td><td>

</td><td>

Partial\<[CompatVisitorConfig](/api/rspeedy/react-rsbuild-plugin.compatvisitorconfig.md)<!-- -->> & \{ disableCreateSelectorQueryIncompatibleWarning?: boolean; } | undefined

</td><td>

_(Optional)_ The `compat` option controls compatibilities with ReactLynx2.0.

</td></tr>
<tr><td>

[customCSSInheritanceList?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.customcssinheritancelist.md)

</td><td>

</td><td>

string\[] | undefined

</td><td>

_(Optional)_ When [PluginReactLynxOptions.enableCSSInheritance](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md) is enabled, `customCSSInheritanceList` can control which properties are inheritable, not just the default ones.

</td></tr>
<tr><td>

[debugInfoOutside?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.debuginfooutside.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ debugInfoOutside controls whether the debug info is placed outside the template.

</td></tr>
<tr><td>

[defaultDisplayLinear?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.defaultdisplaylinear.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ defaultDisplayLinear controls whether the default value of `display` in CSS is `linear`<!-- -->.

If `defaultDisplayLinear === false`<!-- -->, the default `display` would be `flex` instead of `linear`<!-- -->.

</td></tr>
<tr><td>

[defineDCE?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.definedce.md)

</td><td>

</td><td>

Partial\<[DefineDceVisitorConfig](/api/rspeedy/react-rsbuild-plugin.definedcevisitorconfig.md)<!-- -->> | undefined

</td><td>

_(Optional)_ Like `define` in various bundlers, but this one happens at transform time, and a DCE pass will be performed.

</td></tr>
<tr><td>

[enableAccessibilityElement?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableaccessibilityelement.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ enableAccessibilityElement set the default value of `accessibility-element` for all `<view />` elements.

</td></tr>
<tr><td>

[enableCSSInheritance?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinheritance.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ enableCSSInheritance enables the default inheritance properties.

</td></tr>
<tr><td>

[enableCSSInvalidation?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssinvalidation.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ CSS Invalidation refers to the process of determining which elements need to have their styles recalculated when the DOM is updated.

</td></tr>
<tr><td>

[enableCSSSelector?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablecssselector.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ enableCSSSelector controls whether enabling the new CSS implementation.

</td></tr>
<tr><td>

[enableNewGesture?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablenewgesture.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ enableNewGesture enables the new gesture system.

</td></tr>
<tr><td>

[enableRemoveCSSScope?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableremovecssscope.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ enableRemoveCSSScope controls whether CSS is restrict to use in the component scope.

`true`<!-- -->: All CSS files are treated as global CSS.

`false`<!-- -->: All CSS files are treated as scoped CSS, and only take effect in the component that explicitly imports it.

`undefined`<!-- -->: Only use scoped CSS for CSS Modules, and treat other CSS files as global CSS. Scoped CSS is faster than global CSS, thus you can use CSS Modules to speedy up your CSS if there are performance issues.

</td></tr>
<tr><td>

[enableSSR?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enablessr.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ `enableSSR` enable Lynx SSR feature for this build.

</td></tr>
<tr><td>

[enableUiSourceMap?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.enableuisourcemap.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ Enable UI source map generation and debug-metadata asset emission.

</td></tr>
<tr><td>

[engineVersion?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.engineversion.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ `engineVersion` specifies the minimum Lynx Engine version required for an App bundle to function properly.

</td></tr>
<tr><td>

[experimental\_isLazyBundle?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md)

</td><td>

</td><td>

boolean

</td><td>

**_(ALPHA)_** _(Optional)_ Generate standalone lazy bundle.

</td></tr>
<tr><td>

[experimental\_useElementTemplate?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_useelementtemplate.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ Enable Element Template compile and runtime entries.

</td></tr>
<tr><td>

[extractStr?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.extractstr.md)

</td><td>

</td><td>

Partial\<[ExtractStrConfig](/api/rspeedy/react-rsbuild-plugin.extractstrconfig.md)<!-- -->> | boolean

</td><td>

_(Optional)_ Merge same string literals in JS and Lepus to reduce output bundle size. Set to `false` to disable.

</td></tr>
<tr><td>

[firstScreenSyncTiming?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.firstscreensynctiming.md)

</td><td>

</td><td>

'immediately' | 'jsReady'

</td><td>

_(Optional)_ This flag controls when MainThread (Lepus) transfers control to Background after the first screen

This flag has two options:

`"immediately"`<!-- -->: Transfer immediately

`"jsReady"`<!-- -->: Transfer when background (JS Runtime) is ready

After handing over control, MainThread (Lepus) runtime can no longer respond to data updates, and data updates will be forwarded to background (JS Runtime) and processed \_\_asynchronously\_\_

</td></tr>
<tr><td>

[globalPropsMode?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.md)

</td><td>

</td><td>

'reactive' | 'event'

</td><td>

_(Optional)_ Configure the update mode of `lynx.__globalProps`<!-- -->.

This flag has two options:

`'reactive'`<!-- -->: `UpdateGlobalProps` will trigger update automatically.

`'event'`<!-- -->: `UpdateGlobalProps` will trigger global event and users need to trigger update in the event handler.

</td></tr>
<tr><td>

[optimizeBundleSize?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.optimizebundlesize.md)

</td><td>

</td><td>

boolean | \{ mainThread?: boolean; background?: boolean; }

</td><td>

_(Optional)_ Optimize bundle size by removing unused code by Minify.mainThreadOptions and Minify.backgroundOptions.

When optimizeBundleSize or optimizeBundleSize.mainThread is true, main-thread code will be optimized. When optimizeBundleSize or optimizeBundleSize.background is true, background code will be optimized.

</td></tr>
<tr><td>

[removeDescendantSelectorScope?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.removedescendantselectorscope.md)

</td><td>

</td><td>

boolean

</td><td>

_(Optional)_ removeDescendantSelectorScope is used to remove the scope of descendant selectors.

</td></tr>
<tr><td>

[shake?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.shake.md)

</td><td>

</td><td>

Partial\<[ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)<!-- -->> | undefined

</td><td>

_(Optional)_ How main-thread code will be shaken.

</td></tr>
<tr><td>

[targetSdkVersion?](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ targetSdkVersion is used to specify the minimal Lynx Engine version that a App bundle can run on.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.optimizebundlesize.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [PluginReactLynxOptions](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.md) > [optimizeBundleSize](/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.optimizebundlesize.md)

## PluginReactLynxOptions.optimizeBundleSize property

Optimize bundle size by removing unused code by Minify.mainThreadOptions and Minify.backgroundOptions.

When optimizeBundleSize or optimizeBundleSize.mainThread is true, main-thread code will be optimized. When optimizeBundleSize or optimizeBundleSize.background is true, background code will be optimized.

**Signature:**

```typescript
optimizeBundleSize?: boolean | {
        mainThread?: boolean;
        background?: boolean;
    };
```

## Default Value

`false`



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md)

## ShakeVisitorConfig interface

How main-thread code will be shaken.

**Signature:**

```typescript
export interface ShakeVisitorConfig 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[pkgName](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.pkgname.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Package names to identify runtime imports that need to be processed

</td></tr>
<tr><td>

[removeCall](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecall.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Function names whose calls should be replaced with `undefined` during transformation

</td></tr>
<tr><td>

[removeCallParams](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecallparams.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Function names whose parameters should be removed during transformation

</td></tr>
<tr><td>

[retainProp](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.retainprop.md)

</td><td>

</td><td>

Array\<string>

</td><td>

Properties that should be retained in the component class

</td></tr>
</tbody></table>



---
url: /api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecall.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/react-rsbuild-plugin](/api/rspeedy/react-rsbuild-plugin.md) > [ShakeVisitorConfig](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.md) > [removeCall](/api/rspeedy/react-rsbuild-plugin.shakevisitorconfig.removecall.md)

## ShakeVisitorConfig.removeCall property

Function names whose calls should be replaced with `undefined` during transformation

**Signature:**

```typescript
removeCall: Array<string>
```

## Remarks

Default value: `['useEffect', 'useLayoutEffect', '__runInJS', 'useLynxGlobalEventListener', 'useImperativeHandle']` The provided values will be merged with the default values instead of replacing them.

## Example

```js
import { defineConfig } from '@lynx-js/rspeedy'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginReactLynx({
      shake: {
        removeCall: ['useMyCustomEffect']
      }
    })
  ]
})
```



---
url: /api/rspeedy/rspeedy.buildcache.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BuildCache](/api/rspeedy/rspeedy.buildcache.md)

## BuildCache interface

> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Enable or configure persistent build cache.

**Signature:**

```typescript
export interface BuildCache 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[buildDependencies?](/api/rspeedy/rspeedy.buildcache.builddependencies.md)

</td><td>

</td><td>

string\[] | undefined

</td><td>

**_(BETA)_** _(Optional)_ An array of files containing build dependencies. Rspack will use the hash of each of these files to invalidate the persistent cache.

</td></tr>
<tr><td>

[cacheDigest?](/api/rspeedy/rspeedy.buildcache.cachedigest.md)

</td><td>

</td><td>

Array\<string | undefined> | undefined

</td><td>

**_(BETA)_** _(Optional)_ Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.

</td></tr>
<tr><td>

[cacheDirectory?](/api/rspeedy/rspeedy.buildcache.cachedirectory.md)

</td><td>

</td><td>

string | undefined

</td><td>

**_(BETA)_** _(Optional)_ The output directory of the cache files.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.bundlefilename.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BundleFilename](/api/rspeedy/rspeedy.bundlefilename.md)

## BundleFilename type

The name of the bundle files.

It can be a string with placeholders (`[name]`<!-- -->, `[contenthash]`<!-- -->, `[platform]`<!-- -->), or a function that returns a string based on the [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md)<!-- -->.

**Signature:**

```typescript
export type BundleFilename = string | ((context: BundleFilenameContext) => string);
```

**References:** [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md)



---
url: /api/rspeedy/rspeedy.bundlefilenamecontext.entryname.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md) > [entryName](/api/rspeedy/rspeedy.bundlefilenamecontext.entryname.md)

## BundleFilenameContext.entryName property

The name of the entry.

It is `undefined` for lazy bundles, since a lazy bundle name is resolved per async chunk (use the `[name]` placeholder in the returned string instead).

**Signature:**

```typescript
entryName?: string | undefined;
```



---
url: /api/rspeedy/rspeedy.bundlefilenamecontext.lazybundle.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md) > [lazyBundle](/api/rspeedy/rspeedy.bundlefilenamecontext.lazybundle.md)

## BundleFilenameContext.lazyBundle property

Whether the filename is being resolved for a lazy bundle (async chunk) instead of the main bundle of an entry.

This allows you to control the main bundle and the lazy bundles with a single function, without needing a dedicated `lazyBundle` field.

**Signature:**

```typescript
lazyBundle: boolean;
```



---
url: /api/rspeedy/rspeedy.bundlefilenamecontext.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md)

## BundleFilenameContext interface

The context passed to the [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md) function.

**Signature:**

```typescript
export interface BundleFilenameContext 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[entryName?](/api/rspeedy/rspeedy.bundlefilenamecontext.entryname.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The name of the entry.

It is `undefined` for lazy bundles, since a lazy bundle name is resolved per async chunk (use the `[name]` placeholder in the returned string instead).

</td></tr>
<tr><td>

[lazyBundle](/api/rspeedy/rspeedy.bundlefilenamecontext.lazybundle.md)

</td><td>

</td><td>

boolean

</td><td>

Whether the filename is being resolved for a lazy bundle (async chunk) instead of the main bundle of an entry.

This allows you to control the main bundle and the lazy bundles with a single function, without needing a dedicated `lazyBundle` field.

</td></tr>
<tr><td>

[platform](/api/rspeedy/rspeedy.bundlefilenamecontext.platform.md)

</td><td>

</td><td>

string

</td><td>

The environment (platform) name, e.g. `'lynx'` or `'web'`<!-- -->.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.bundlefilenamecontext.platform.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md) > [platform](/api/rspeedy/rspeedy.bundlefilenamecontext.platform.md)

## BundleFilenameContext.platform property

The environment (platform) name, e.g. `'lynx'` or `'web'`<!-- -->.

**Signature:**

```typescript
platform: string;
```



---
url: /api/rspeedy/rspeedy.chunksplit.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md)

## ChunkSplit interface

> Warning: This API is now obsolete.
>
> Use the top-level [Config.splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md) option instead.

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplit 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[override?](/api/rspeedy/rspeedy.chunksplit.override.md)

</td><td>

</td><td>

Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } | undefined; } ? P : never

</td><td>

_(Optional)_ Custom Rspack chunk splitting config can be specified.

</td></tr>
<tr><td>

[strategy?](/api/rspeedy/rspeedy.chunksplit.strategy.md)

</td><td>

</td><td>

'all-in-one' | 'split-by-module' | 'split-by-experience' | 'single-vendor' | undefined

</td><td>

_(Optional)_ The ChunkSplitting strategy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.chunksplitbysize.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md)

## ChunkSplitBySize interface

> Warning: This API is now obsolete.
>
> Use the top-level [Config.splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md) option instead.

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitBySize 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[maxSize?](/api/rspeedy/rspeedy.chunksplitbysize.maxsize.md)

</td><td>

</td><td>

number | undefined

</td><td>

_(Optional)_ The maximum size of a chunk, unit in bytes.

</td></tr>
<tr><td>

[minSize?](/api/rspeedy/rspeedy.chunksplitbysize.minsize.md)

</td><td>

</td><td>

number | undefined

</td><td>

_(Optional)_ The minimum size of a chunk, unit in bytes.

</td></tr>
<tr><td>

[override?](/api/rspeedy/rspeedy.chunksplitbysize.override.md)

</td><td>

</td><td>

Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } | undefined; } ? P : never

</td><td>

_(Optional)_ Custom Rspack chunk splitting config can be specified.

</td></tr>
<tr><td>

[strategy](/api/rspeedy/rspeedy.chunksplitbysize.strategy.md)

</td><td>

</td><td>

'split-by-size'

</td><td>

The ChunkSplitting strategy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.chunksplitbysize.override.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [override](/api/rspeedy/rspeedy.chunksplitbysize.override.md)

## ChunkSplitBySize.override property

Custom Rspack chunk splitting config can be specified.

**Signature:**

```typescript
override?: Rspack.Configuration extends {
        optimization?: {
            splitChunks?: infer P;
        } | undefined;
    } ? P : never;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.chunksplitbysize.strategy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md) > [strategy](/api/rspeedy/rspeedy.chunksplitbysize.strategy.md)

## ChunkSplitBySize.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy: 'split-by-size';
```

## Remarks

- `split-by-experience`<!-- -->(Rsbuild default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.



---
url: /api/rspeedy/rspeedy.chunksplitcustom.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md)

## ChunkSplitCustom interface

> Warning: This API is now obsolete.
>
> Use the top-level [Config.splitChunks](/api/rspeedy/rspeedy.config.splitchunks.md) option instead.

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

**Signature:**

```typescript
export interface ChunkSplitCustom 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[splitChunks?](/api/rspeedy/rspeedy.chunksplitcustom.splitchunks.md)

</td><td>

</td><td>

Rspack.Configuration extends \{ optimization?: \{ splitChunks?: infer P; } | undefined; } ? P : never

</td><td>

_(Optional)_ Custom Rspack chunk splitting config can be specified.

</td></tr>
<tr><td>

[strategy](/api/rspeedy/rspeedy.chunksplitcustom.strategy.md)

</td><td>

</td><td>

'custom'

</td><td>

The ChunkSplitting strategy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.chunksplitcustom.strategy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md) > [strategy](/api/rspeedy/rspeedy.chunksplitcustom.strategy.md)

## ChunkSplitCustom.strategy property

The ChunkSplitting strategy.

**Signature:**

```typescript
strategy: 'custom';
```

## Remarks

- `split-by-experience`<!-- -->(Rsbuild default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.

- `split-by-module`<!-- -->: split by NPM package granularity, each NPM package corresponds to a chunk.

- `split-by-size`<!-- -->: automatically split according to module size.

- `all-in-one`<!-- -->: bundle all codes into one chunk.

- `single-vendor`<!-- -->: bundle all NPM packages into a single chunk.

- `custom`<!-- -->: custom chunk splitting strategy.



---
url: /api/rspeedy/rspeedy.config.dev.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [dev](/api/rspeedy/rspeedy.config.dev.md)

## Config.dev property

The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

**Signature:**

```typescript
dev?: Dev | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md)

## Config interface

The `Config` is the configuration that `rspeedy` uses.

**Signature:**

```typescript
export interface Config 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[dev?](/api/rspeedy/rspeedy.config.dev.md)

</td><td>

</td><td>

[Dev](/api/rspeedy/rspeedy.dev.md) | undefined

</td><td>

_(Optional)_ The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

</td></tr>
<tr><td>

[environments?](/api/rspeedy/rspeedy.config.environments.md)

</td><td>

</td><td>

RsbuildConfig\['environments'] | undefined

</td><td>

_(Optional)_ The [Config.environments](/api/rspeedy/rspeedy.config.environments.md) option is used to set the output environment.

</td></tr>
<tr><td>

[mode?](/api/rspeedy/rspeedy.config.mode.md)

</td><td>

</td><td>

'development' | 'production' | 'none' | undefined

</td><td>

_(Optional)_ Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.

</td></tr>
<tr><td>

[output?](/api/rspeedy/rspeedy.config.output.md)

</td><td>

</td><td>

[Output](/api/rspeedy/rspeedy.output.md) | undefined

</td><td>

_(Optional)_ The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

</td></tr>
<tr><td>

[performance?](/api/rspeedy/rspeedy.config.performance.md)

</td><td>

</td><td>

[Performance](/api/rspeedy/rspeedy.performance.md) | undefined

</td><td>

_(Optional)_ The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

</td></tr>
<tr><td>

[plugins?](/api/rspeedy/rspeedy.config.plugins.md)

</td><td>

</td><td>

RsbuildPlugins | undefined

</td><td>

_(Optional)_ The `plugins` option is used to customize the build process in a variety of ways.

</td></tr>
<tr><td>

[resolve?](/api/rspeedy/rspeedy.config.resolve.md)

</td><td>

</td><td>

[Resolve](/api/rspeedy/rspeedy.resolve.md) | undefined

</td><td>

_(Optional)_ The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

</td></tr>
<tr><td>

[server?](/api/rspeedy/rspeedy.config.server.md)

</td><td>

</td><td>

[Server](/api/rspeedy/rspeedy.server.md) | undefined

</td><td>

_(Optional)_ The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

</td></tr>
<tr><td>

[source?](/api/rspeedy/rspeedy.config.source.md)

</td><td>

</td><td>

[Source](/api/rspeedy/rspeedy.source.md) | undefined

</td><td>

_(Optional)_ The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

</td></tr>
<tr><td>

[splitChunks?](/api/rspeedy/rspeedy.config.splitchunks.md)

</td><td>

</td><td>

RsbuildConfig\['splitChunks'] | undefined

</td><td>

_(Optional)_ Configure chunk splitting.

</td></tr>
<tr><td>

[tools?](/api/rspeedy/rspeedy.config.tools.md)

</td><td>

</td><td>

[Tools](/api/rspeedy/rspeedy.tools.md) | undefined

</td><td>

_(Optional)_ The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.config.output.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [output](/api/rspeedy/rspeedy.config.output.md)

## Config.output property

The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

**Signature:**

```typescript
output?: Output | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.performance.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [performance](/api/rspeedy/rspeedy.config.performance.md)

## Config.performance property

The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

**Signature:**

```typescript
performance?: Performance | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.plugins.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [plugins](/api/rspeedy/rspeedy.config.plugins.md)

## Config.plugins property

The `plugins` option is used to customize the build process in a variety of ways.

**Signature:**

```typescript
plugins?: RsbuildPlugins | undefined;
```

## Default Value

undefined

## Remarks

Rspeedy uses the plugin APIs from [Rsbuild](https://rsbuild.rs/plugins/dev/index)<!-- -->. See the corresponding document for developing a plugin.



---
url: /api/rspeedy/rspeedy.config.resolve.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [resolve](/api/rspeedy/rspeedy.config.resolve.md)

## Config.resolve property

The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

**Signature:**

```typescript
resolve?: Resolve | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.server.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [server](/api/rspeedy/rspeedy.config.server.md)

## Config.server property

The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

**Signature:**

```typescript
server?: Server | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.source.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [source](/api/rspeedy/rspeedy.config.source.md)

## Config.source property

The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

**Signature:**

```typescript
source?: Source | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.config.tools.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Config](/api/rspeedy/rspeedy.config.md) > [tools](/api/rspeedy/rspeedy.config.tools.md)

## Config.tools property

The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

**Signature:**

```typescript
tools?: Tools | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.configparams.command.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md) > [command](/api/rspeedy/rspeedy.configparams.command.md)

## ConfigParams.command property

The CLI command of Rspeedy.

**Signature:**

```typescript
command: 'build' | 'dev' | 'inspect' | 'preview' | (string & Record<never, never>);
```

## Default Value

When `loadConfig` evaluates a config function, this value is `process.argv[2] ?? 'build'`

## Remarks

Possible values:

- `'build'`

- `'dev'`

- `'inspect'`

- `'preview'`



---
url: /api/rspeedy/rspeedy.configparams.env.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md) > [env](/api/rspeedy/rspeedy.configparams.env.md)

## ConfigParams.env property

The value of `process.env['NODE_ENV']`

**Signature:**

```typescript
env: 'production' | 'development' | 'test' | (string & Record<never, never>);
```

## Default Value

When `loadConfig` evaluates a config function, this value is `process.env.NODE_ENV ?? 'production'`

## Remarks

Common values include (non-exhaustive): - `'production'`

- `'development'`

- `'test'`



---
url: /api/rspeedy/rspeedy.configparams.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConfigParams](/api/rspeedy/rspeedy.configparams.md)

## ConfigParams interface

Parameters for the function exported from `lynx.config.js`<!-- -->.

**Signature:**

```typescript
export interface ConfigParams 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[command](/api/rspeedy/rspeedy.configparams.command.md)

</td><td>

</td><td>

'build' | 'dev' | 'inspect' | 'preview' | (string & Record\<never, never>)

</td><td>

The CLI command of Rspeedy.

</td></tr>
<tr><td>

[env](/api/rspeedy/rspeedy.configparams.env.md)

</td><td>

</td><td>

'production' | 'development' | 'test' | (string & Record\<never, never>)

</td><td>

The value of `process.env['NODE_ENV']`

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.consoletype.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ConsoleType](/api/rspeedy/rspeedy.consoletype.md)

## ConsoleType type

The type of the console method.

**Signature:**

```typescript
export type ConsoleType = 'log' | 'warn' | 'error' | 'info' | 'debug' | 'profile' | 'profileEnd' | (string & Record<never, never>);
```



---
url: /api/rspeedy/rspeedy.createrspeedy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [createRspeedy](/api/rspeedy/rspeedy.createrspeedy.md)

## createRspeedy() function

The `createRspeedy` method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime.

**Signature:**

```typescript
export declare function createRspeedy(input: CreateRspeedyOptions): Promise<RspeedyInstance>;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

\{ cwd, rspeedyConfig, loadEnv, environment, callerName, }

</td><td>

(not declared)

</td><td>

</td></tr>
<tr><td>

input

</td><td>

[CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md)

</td><td>

</td></tr>
</tbody></table>

**Returns:**

Promise\<[RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)<!-- -->>

- Rspeedy instance.

## Example

```ts
import { createRspeedy } from '@lynx-js/rspeedy'

void async function () {
  const rspeedy = await createRspeedy({})
  await rspeedy.build()
}()
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.callername.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [callerName](/api/rspeedy/rspeedy.createrspeedyoptions.callername.md)

## CreateRspeedyOptions.callerName property

The name of the framework or tool that is currently invoking Rsbuild. This allows plugins to tailor their behavior based on the calling context.

**Signature:**

```typescript
callerName?: string;
```

## Default Value

'rspeedy'

## Example

Rsbuild plugins can access this value via `api.context.callerName`<!-- -->.

```js
export function myPlugin() {
  return {
    name: 'my-plugin',
    setup(api) {
      // Log the name of the tool invoking Rsbuild
      console.log(`Called by: ${api.context.callerName}`);

      // Conditionally apply plugin logic based on caller
      if (api.context.callerName === 'rspeedy') {
        api.modifyRsbuildConfig((config) => {
          // Apply rspeedy-specific config changes
          return config;
        });
      } else if (api.context.callerName === 'rslib') {
        api.modifyRsbuildConfig((config) => {
          // Apply rslib-specific config changes
          return config;
        });
      }
    }
  };
}
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.cwd.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [cwd](/api/rspeedy/rspeedy.createrspeedyoptions.cwd.md)

## CreateRspeedyOptions.cwd property

The root path of the current build.

**Signature:**

```typescript
cwd?: string;
```



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.environment.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [environment](/api/rspeedy/rspeedy.createrspeedyoptions.environment.md)

## CreateRspeedyOptions.environment property

Only build specified environments. For example, passing `['lynx']` will only build the `lynx` environment. If not specified or passing an empty array, all environments will be built.

**Signature:**

```typescript
environment?: CreateRsbuildOptions['environment'];
```

## Default Value

\[]



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [loadEnv](/api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md)

## CreateRspeedyOptions.loadEnv property

Rspeedy automatically loads the .env file by default, utilizing the \[Rsbuild API]\([https://rsbuild.rs/api/javascript-api/core\\#load-env-variables](https://rsbuild.rs/api/javascript-api/core\\#load-env-variables)). You can use the environment variables defined in the .env file within your code by accessing them via `import.meta.env.FOO` or `process.env.Foo`<!-- -->.

**Signature:**

```typescript
loadEnv?: CreateRsbuildOptions['loadEnv'];
```

## Default Value

true



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md)

## CreateRspeedyOptions interface

The options of `createRspeedy` method.

**Signature:**

```typescript
export interface CreateRspeedyOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[callerName?](/api/rspeedy/rspeedy.createrspeedyoptions.callername.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ The name of the framework or tool that is currently invoking Rsbuild. This allows plugins to tailor their behavior based on the calling context.

</td></tr>
<tr><td>

[cwd?](/api/rspeedy/rspeedy.createrspeedyoptions.cwd.md)

</td><td>

</td><td>

string

</td><td>

_(Optional)_ The root path of the current build.

</td></tr>
<tr><td>

[environment?](/api/rspeedy/rspeedy.createrspeedyoptions.environment.md)

</td><td>

</td><td>

CreateRsbuildOptions\['environment']

</td><td>

_(Optional)_ Only build specified environments. For example, passing `['lynx']` will only build the `lynx` environment. If not specified or passing an empty array, all environments will be built.

</td></tr>
<tr><td>

[loadEnv?](/api/rspeedy/rspeedy.createrspeedyoptions.loadenv.md)

</td><td>

</td><td>

CreateRsbuildOptions\['loadEnv']

</td><td>

_(Optional)_ Rspeedy automatically loads the .env file by default, utilizing the \[Rsbuild API]\([https://rsbuild.rs/api/javascript-api/core\\#load-env-variables](https://rsbuild.rs/api/javascript-api/core\\#load-env-variables)). You can use the environment variables defined in the .env file within your code by accessing them via `import.meta.env.FOO` or `process.env.Foo`<!-- -->.

</td></tr>
<tr><td>

[rspeedyConfig?](/api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md)

</td><td>

</td><td>

[Config](/api/rspeedy/rspeedy.config.md)

</td><td>

_(Optional)_ The config of Rspeedy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md) > [rspeedyConfig](/api/rspeedy/rspeedy.createrspeedyoptions.rspeedyconfig.md)

## CreateRspeedyOptions.rspeedyConfig property

The config of Rspeedy.

**Signature:**

```typescript
rspeedyConfig?: Config;
```



---
url: /api/rspeedy/rspeedy.cssextract.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtract](/api/rspeedy/rspeedy.cssextract.md)

## CssExtract interface

The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin)

**Signature:**

```typescript
export interface CssExtract 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[loaderOptions?](/api/rspeedy/rspeedy.cssextract.loaderoptions.md)

</td><td>

</td><td>

[CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md) | undefined

</td><td>

_(Optional)_

</td></tr>
<tr><td>

[pluginOptions?](/api/rspeedy/rspeedy.cssextract.pluginoptions.md)

</td><td>

</td><td>

[CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md) | undefined

</td><td>

_(Optional)_

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.cssextractrspackloaderoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md)

## CssExtractRspackLoaderOptions interface

**Signature:**

```typescript
export interface CssExtractRspackLoaderOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[esModule?](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.esmodule.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ The same as [https://github.com/webpack-contrib/mini-css-extract-plugin#esModule](https://github.com/webpack-contrib/mini-css-extract-plugin#esModule)<!-- -->. By default, `@lynx-js/css-extract-webpack-plugin` generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.cssextractrspackpluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md)

## CssExtractRspackPluginOptions interface

**Signature:**

```typescript
export interface CssExtractRspackPluginOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[ignoreOrder?](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.ignoreorder.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_

</td></tr>
<tr><td>

[pathinfo?](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.pathinfo.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.cssloader.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoader](/api/rspeedy/rspeedy.cssloader.md)

## CssLoader interface

The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

**Signature:**

```typescript
export interface CssLoader 
```

## Remarks

The default option is as follow:

```js
const defaultOptions = {
  modules: {
    auto: true,
    namedExport: false,
    exportLocalsConvention: 'camelCase',
    localIdentName: output.cssModules.localIdentName,
  },
  sourceMap: output.sourceMap,
  // importLoaders is `1` when compiling css files, and is `2` when compiling sass/less files
  importLoaders: 1 || 2,
};
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[importLoaders?](/api/rspeedy/rspeedy.cssloader.importloaders.md)

</td><td>

</td><td>

0 | 1 | 2 | undefined

</td><td>

_(Optional)_ The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@imported` resources and CSS modules imports.

</td></tr>
<tr><td>

[modules?](/api/rspeedy/rspeedy.cssloader.modules.md)

</td><td>

</td><td>

boolean | [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md) | undefined

</td><td>

_(Optional)_ The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.cssloadermodules.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md)

## CssLoaderModules interface

The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

**Signature:**

```typescript
export interface CssLoaderModules 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[auto?](/api/rspeedy/rspeedy.cssloadermodules.auto.md)

</td><td>

</td><td>

boolean | RegExp | ((filename: string) => boolean) | undefined

</td><td>

_(Optional)_ The `auto` option allows CSS modules to be automatically enabled based on their filenames.

</td></tr>
<tr><td>

[exportLocalsConvention?](/api/rspeedy/rspeedy.cssloadermodules.exportlocalsconvention.md)

</td><td>

</td><td>

[CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md) | undefined

</td><td>

_(Optional)_ The style of exported class names.

</td></tr>
<tr><td>

[localIdentName?](/api/rspeedy/rspeedy.cssloadermodules.localidentname.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Sets the format of the className generated by CSS Modules after compilation.

</td></tr>
<tr><td>

[namedExport?](/api/rspeedy/rspeedy.cssloadermodules.namedexport.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Enables/disables ES modules named export for locals.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.cssmodulelocalsconvention.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md)

## CssModuleLocalsConvention type

The style of exported class names.

**Signature:**

```typescript
export type CssModuleLocalsConvention = 'asIs' | 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly';
```

## Remarks

Given the various `exportLocalsConvention` values, the behavior is described as follows:

- `'asIs'`<!-- -->: Class names will be exported as is.

- `'camelCase'`<!-- -->: Class names will be camelized, the original class name will not to be removed from the locals

- `'camelCaseOnly'`<!-- -->: Class names will be camelized, the original class name will be removed from the locals

- `'dashes'`<!-- -->: Only dashes in class names will be camelized

- `'dashesOnly'`<!-- -->: Dashes in class names will be camelized, the original class name will be removed from the locals

See [css-loader#exportLocalsConvention](https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention) for details.



---
url: /api/rspeedy/rspeedy.cssmodules.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [CssModules](/api/rspeedy/rspeedy.cssmodules.md)

## CssModules interface

The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

**Signature:**

```typescript
export interface CssModules 
```

## Remarks

The CSS module is enabled for `*.module.css`<!-- -->, `*.module.scss` and `*.module.less`<!-- -->. Use [CssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md) to customize the filtering behavior.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[auto?](/api/rspeedy/rspeedy.cssmodules.auto.md)

</td><td>

</td><td>

boolean | RegExp | ((filename: string) => boolean) | undefined

</td><td>

_(Optional)_ The `auto` option allows CSS modules to be automatically enabled based on their filenames.

</td></tr>
<tr><td>

[exportGlobals?](/api/rspeedy/rspeedy.cssmodules.exportglobals.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Allows exporting names from global class names, so you can use them via import.

</td></tr>
<tr><td>

[exportLocalsConvention?](/api/rspeedy/rspeedy.cssmodules.exportlocalsconvention.md)

</td><td>

</td><td>

[CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md) | undefined

</td><td>

_(Optional)_ The style of exported class names.

</td></tr>
<tr><td>

[localIdentName?](/api/rspeedy/rspeedy.cssmodules.localidentname.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Sets the format of the className generated by CSS Modules after compilation.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.decorators.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Decorators](/api/rspeedy/rspeedy.decorators.md)

## Decorators interface

Used to configure the decorators syntax.

**Signature:**

```typescript
export interface Decorators 
```

## Remarks

See [Decorators.version](/api/rspeedy/rspeedy.decorators.version.md) for more information.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[version?](/api/rspeedy/rspeedy.decorators.version.md)

</td><td>

</td><td>

'legacy' | '2022-03'

</td><td>

_(Optional)_ Specify the decorator syntax version to be used.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.defineconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: Config): Config;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

config

</td><td>

[Config](/api/rspeedy/rspeedy.config.md)

</td><td>

The config of Rspeedy.

</td></tr>
</tbody></table>

**Returns:**

[Config](/api/rspeedy/rspeedy.config.md)

- The identical config as the input config.

## Example

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  // autocompletion works here!
})
```



---
url: /api/rspeedy/rspeedy.defineconfig_1.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_1.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: (params: ConfigParams) => Config): (params: ConfigParams) => Config;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

config

</td><td>

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => [Config](/api/rspeedy/rspeedy.config.md)

</td><td>

The function that returns a config of Rspeedy.

</td></tr>
</tbody></table>

**Returns:**

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => [Config](/api/rspeedy/rspeedy.config.md)

- The identical function as the input.

## Example 1

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig(() => {
  return {
    // autocompletion works here!
  }
})
```

## Example 2

Use `defineConfig` with parameters in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(({ env }) => {
  const isTest = env === 'test'
  return {
    output: {
      minify: isTest ? false : true,
    },
  }
})
```



---
url: /api/rspeedy/rspeedy.defineconfig_2.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_2.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: Promise<Config>): Promise<Config>;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

config

</td><td>

Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

</td><td>

The promise that resolves to a config of Rspeedy.

</td></tr>
</tbody></table>

**Returns:**

Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

- The identical promise as the input.

## Example

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(
  import('@lynx-js/react-rsbuild-plugin').then(({ pluginReactLynx }) => ({
    plugins: [pluginReactLynx()],
  })),
);
```



---
url: /api/rspeedy/rspeedy.defineconfig_3.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [defineConfig](/api/rspeedy/rspeedy.defineconfig_3.md)

## defineConfig() function

The `defineConfig` method is a helper function used to get TypeScript intellisense.

**Signature:**

```typescript
export declare function defineConfig(config: (params: ConfigParams) => Promise<Config>): (params: ConfigParams) => Promise<Config>;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

config

</td><td>

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

</td><td>

The function that returns a promise that resolves to a config of Rspeedy.

</td></tr>
</tbody></table>

**Returns:**

(params: [ConfigParams](/api/rspeedy/rspeedy.configparams.md)<!-- -->) => Promise\<[Config](/api/rspeedy/rspeedy.config.md)<!-- -->>

- The identical function as the input.

## Example 1

Use `defineConfig` in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig(async () => {
  const foo = await bar()
  return {
    // autocompletion works here!
  }
})
```

## Example 2

Use `defineConfig` with parameters in `lynx.config.ts`<!-- -->:

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig(async ({ env }) => {
  const foo = await bar()
  const isTest = env === 'test'
  return {
    output: {
      minify: isTest ? false : true,
    },
  }
})
```



---
url: /api/rspeedy/rspeedy.devclient.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DevClient](/api/rspeedy/rspeedy.devclient.md)

## DevClient interface

Configuration of the development client.

**Signature:**

```typescript
export interface Client 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[websocketTransport?](/api/rspeedy/rspeedy.devclient.websockettransport.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The path to websocket.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.distpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [DistPath](/api/rspeedy/rspeedy.distpath.md)

## DistPath interface

Set the directory of the dist files.

**Signature:**

```typescript
export interface DistPath extends DistPathConfig 
```

**Extends:** DistPathConfig

## Remarks

More options can be found at [Rsbuild - distPath](https://rsbuild.rs/config/output/dist-path)<!-- -->.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[intermediate?](/api/rspeedy/rspeedy.distpath.intermediate.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The output directory of the intermediate files.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.entry.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Entry](/api/rspeedy/rspeedy.entry.md)

## Entry type

The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

**Signature:**

```typescript
export type Entry = string | string[] | Record<string, string | string[] | EntryDescription>;
```

**References:** [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)

## Example 1

- Use a single entry:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: './src/pages/main/index.js',
  }
})
```

## Example 2

- Use a single entry with multiple entry modules:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: ['./src/prefetch.js', './src/pages/main/index.js'],
  }
})
```

## Example 3

- Use multiple entries(with multiple entry modules):

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: ['./src/pages/bar/index.js', './src/post.js'], // multiple entry modules is allowed
    }
  }
})
```

## Example 4

- Use multiple entries with [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)<!-- -->:

```js
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: {
        import: ['./src/prefetch.js', './src/pages/bar'],
      }
    }
  }
})
```



---
url: /api/rspeedy/rspeedy.entrydescription.import.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md) > [import](/api/rspeedy/rspeedy.entrydescription.import.md)

## EntryDescription.import property

The path to the entry module(s).

**Signature:**

```typescript
import?: string | string[] | undefined;
```

## Default Value

`'./src/index.js'`



---
url: /api/rspeedy/rspeedy.entrydescription.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)

## EntryDescription interface

The `EntryDescription` describes a entry. It is useful when the project has multiple entries with different configuration.

**Signature:**

```typescript
export interface EntryDescription 
```

## Remarks

It is similar with the [Entry Description Object](https://rspack.rs/config/entry#entry-description-object) of Rspack. But only a few properties that Lynx supports is allowed.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[import?](/api/rspeedy/rspeedy.entrydescription.import.md)

</td><td>

</td><td>

string | string\[] | undefined

</td><td>

_(Optional)_ The path to the entry module(s).

</td></tr>
<tr><td>

[publicPath?](/api/rspeedy/rspeedy.entrydescription.publicpath.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.entrydescription.publicpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [EntryDescription](/api/rspeedy/rspeedy.entrydescription.md) > [publicPath](/api/rspeedy/rspeedy.entrydescription.publicpath.md)

## EntryDescription.publicPath property

This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.

**Signature:**

```typescript
publicPath?: string | undefined;
```

## Default Value

undefined



---
url: /api/rspeedy/rspeedy.exposedapi.config.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [config](/api/rspeedy/rspeedy.exposedapi.config.md)

## ExposedAPI.config property

The user config.

**Signature:**

```typescript
config: Config;
```



---
url: /api/rspeedy/rspeedy.exposedapi.debug.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [debug](/api/rspeedy/rspeedy.exposedapi.debug.md)

## ExposedAPI.debug property

Print debug logs.

**Signature:**

```typescript
debug: (message: string | (() => string)) => void;
```



---
url: /api/rspeedy/rspeedy.exposedapi.entries.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [entries](/api/rspeedy/rspeedy.exposedapi.entries.md)

## ExposedAPI.entries property

Used for plugin qrcode get entry points from self-defined environments rather than default lynx environment.

**Signature:**

```typescript
entries?: RsbuildEntry;
```



---
url: /api/rspeedy/rspeedy.exposedapi.exit.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [exit](/api/rspeedy/rspeedy.exposedapi.exit.md)

## ExposedAPI.exit property

Exit the process.

**Signature:**

```typescript
exit: (code?: number) => Promise<void> | void;
```



---
url: /api/rspeedy/rspeedy.exposedapi.logger.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [logger](/api/rspeedy/rspeedy.exposedapi.logger.md)

## ExposedAPI.logger property

Get the Rspeedy logger.

**Signature:**

```typescript
logger: typeof logger;
```



---
url: /api/rspeedy/rspeedy.exposedapi.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md)

## ExposedAPI interface

The exposed API of Rspeedy. Can be used in Rsbuild plugin with [api.useExposed](https://rsbuild.rs/plugins/dev/core#apiuseexposed)<!-- -->.

**Signature:**

```typescript
export interface ExposedAPI 
```

## Example

```ts
import type { ExposedAPI } from '@lynx-js/rspeedy'
const RsbuildPlugin = {
  name: 'my-rsbuild-plugin',
  pre: ['lynx:rsbuild:plugin-api'],
  setup(api) {
    const rspeedyAPI = api.useExposed<ExposedAPI>(Symbol.for('rspeedy.api'))
  },
}
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[config](/api/rspeedy/rspeedy.exposedapi.config.md)

</td><td>

</td><td>

[Config](/api/rspeedy/rspeedy.config.md)

</td><td>

The user config.

</td></tr>
<tr><td>

[debug](/api/rspeedy/rspeedy.exposedapi.debug.md)

</td><td>

</td><td>

(message: string | (() => string)) => void

</td><td>

Print debug logs.

</td></tr>
<tr><td>

[entries?](/api/rspeedy/rspeedy.exposedapi.entries.md)

</td><td>

</td><td>

RsbuildEntry

</td><td>

_(Optional)_ Used for plugin qrcode get entry points from self-defined environments rather than default lynx environment.

</td></tr>
<tr><td>

[exit](/api/rspeedy/rspeedy.exposedapi.exit.md)

</td><td>

</td><td>

(code?: number) => Promise\<void> | void

</td><td>

Exit the process.

</td></tr>
<tr><td>

[logger](/api/rspeedy/rspeedy.exposedapi.logger.md)

</td><td>

</td><td>

typeof logger

</td><td>

Get the Rspeedy logger.

</td></tr>
<tr><td>

[version](/api/rspeedy/rspeedy.exposedapi.version.md)

</td><td>

</td><td>

string

</td><td>

The version of Rspeedy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.exposedapi.version.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md) > [version](/api/rspeedy/rspeedy.exposedapi.version.md)

## ExposedAPI.version property

The version of Rspeedy.

**Signature:**

```typescript
version: string;
```



---
url: /api/rspeedy/rspeedy.filename.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Filename](/api/rspeedy/rspeedy.filename.md)

## Filename interface

The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

**Signature:**

```typescript
export interface Filename 
```

## Remarks

If a string is provided, it will be used as [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md)<!-- -->.

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[assets?](/api/rspeedy/rspeedy.filename.assets.md)

</td><td>

</td><td>

Rspack.AssetModuleFilename

</td><td>

_(Optional)_ The name of other assets, except for above (image, svg, font, html, wasm...)

</td></tr>
<tr><td>

[bundle?](/api/rspeedy/rspeedy.filename.bundle.md)

</td><td>

</td><td>

[BundleFilename](/api/rspeedy/rspeedy.bundlefilename.md) | undefined

</td><td>

_(Optional)_ The name of the bundle files.

</td></tr>
<tr><td>

[css?](/api/rspeedy/rspeedy.filename.css.md)

</td><td>

</td><td>

Rspack.CssFilename | undefined

</td><td>

_(Optional)_ The name of the CSS files.

</td></tr>
<tr><td>

[font?](/api/rspeedy/rspeedy.filename.font.md)

</td><td>

</td><td>

Rspack.AssetModuleFilename | undefined

</td><td>

_(Optional)_ The name of the font files.

</td></tr>
<tr><td>

[image?](/api/rspeedy/rspeedy.filename.image.md)

</td><td>

</td><td>

Rspack.AssetModuleFilename | undefined

</td><td>

_(Optional)_ The name of non-SVG images.

</td></tr>
<tr><td>

[js?](/api/rspeedy/rspeedy.filename.js.md)

</td><td>

</td><td>

Rspack.Filename | undefined

</td><td>

_(Optional)_ The name of the JavaScript files.

</td></tr>
<tr><td>

[media?](/api/rspeedy/rspeedy.filename.media.md)

</td><td>

</td><td>

Rspack.AssetModuleFilename | undefined

</td><td>

_(Optional)_ The name of media assets, such as video.

</td></tr>
<tr><td>

[svg?](/api/rspeedy/rspeedy.filename.svg.md)

</td><td>

</td><td>

Rspack.AssetModuleFilename | undefined

</td><td>

_(Optional)_ The name of the SVG images.

</td></tr>
<tr><td>

[template?](/api/rspeedy/rspeedy.filename.template.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The name of the template files.

</td></tr>
<tr><td>

[wasm?](/api/rspeedy/rspeedy.filename.wasm.md)

</td><td>

</td><td>

Rspack.WebassemblyModuleFilename

</td><td>

_(Optional)_ The name of WebAssembly files.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.loadconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [loadConfig](/api/rspeedy/rspeedy.loadconfig.md)

## loadConfig() function

Load the build config by the config path.

**Signature:**

```typescript
export declare function loadConfig(loadConfigOptions: LoadConfigOptions): Promise<LoadConfigResult>;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

loadConfigOptions

</td><td>

[LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md)

</td><td>

the options of `loadConfig` method.

</td></tr>
</tbody></table>

**Returns:**

Promise\<[LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)<!-- -->>

Build config.

## Example

```ts
import { loadConfig } from '@lynx-js/rspeedy'

void async function () {
  const config = await loadConfig({ configPath: './lynx.config.js' })
  console.log(config);
}()
```



---
url: /api/rspeedy/rspeedy.loadconfigoptions.configpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md) > [configPath](/api/rspeedy/rspeedy.loadconfigoptions.configpath.md)

## LoadConfigOptions.configPath property

The config file path to load.

**Signature:**

```typescript
configPath?: string | undefined;
```

## Default Value

Automatically resolves `lynx.config.ts`<!-- -->, `lynx.config.js`<!-- -->, `lynx.config.mts`<!-- -->, or `lynx.config.mjs` from `cwd`



---
url: /api/rspeedy/rspeedy.loadconfigoptions.cwd.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md) > [cwd](/api/rspeedy/rspeedy.loadconfigoptions.cwd.md)

## LoadConfigOptions.cwd property

The working directory used to resolve the config path.

**Signature:**

```typescript
cwd?: string | undefined;
```

## Default Value

`process.cwd()`



---
url: /api/rspeedy/rspeedy.loadconfigoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md)

## LoadConfigOptions interface

The options of loadConfig.

**Signature:**

```typescript
export interface LoadConfigOptions 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[configPath?](/api/rspeedy/rspeedy.loadconfigoptions.configpath.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The config file path to load.

</td></tr>
<tr><td>

[cwd?](/api/rspeedy/rspeedy.loadconfigoptions.cwd.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ The working directory used to resolve the config path.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.loadconfigresult.configpath.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md) > [configPath](/api/rspeedy/rspeedy.loadconfigresult.configpath.md)

## LoadConfigResult.configPath property

The configuration path that has been loaded.

**Signature:**

```typescript
configPath: string;
```



---
url: /api/rspeedy/rspeedy.loadconfigresult.content.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md) > [content](/api/rspeedy/rspeedy.loadconfigresult.content.md)

## LoadConfigResult.content property

The configuration object that exported from the configuration file.

**Signature:**

```typescript
content: Config;
```

## Remarks

The returned object has already been validated.



---
url: /api/rspeedy/rspeedy.loadconfigresult.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)

## LoadConfigResult interface

The result of [loadConfig()](/api/rspeedy/rspeedy.loadconfig.md)<!-- -->.

**Signature:**

```typescript
export interface LoadConfigResult 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[configPath](/api/rspeedy/rspeedy.loadconfigresult.configpath.md)

</td><td>

</td><td>

string

</td><td>

The configuration path that has been loaded.

</td></tr>
<tr><td>

[content](/api/rspeedy/rspeedy.loadconfigresult.content.md)

</td><td>

</td><td>

[Config](/api/rspeedy/rspeedy.config.md)

</td><td>

The configuration object that exported from the configuration file.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md)

## rspeedy package

The document contains all the configurations of the `@lynx-js/rspeedy` package.

## Example

Use `lynx.config.ts` with  to get better TypeScript intellisense.

```ts
import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  entry: './src/index.tsx',
})
```

## Functions

<table><thead><tr><th>

Function

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[createRspeedy(\{ cwd, rspeedyConfig, loadEnv, environment, callerName, }, input)](/api/rspeedy/rspeedy.createrspeedy.md)

</td><td>

The `createRspeedy` method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime.

</td></tr>
<tr><td>

[defineConfig(config)](/api/rspeedy/rspeedy.defineconfig.md)

</td><td>

The `defineConfig` method is a helper function used to get TypeScript intellisense.

</td></tr>
<tr><td>

[defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_1.md)

</td><td>

The `defineConfig` method is a helper function used to get TypeScript intellisense.

</td></tr>
<tr><td>

[defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_2.md)

</td><td>

The `defineConfig` method is a helper function used to get TypeScript intellisense.

</td></tr>
<tr><td>

[defineConfig(config)](/api/rspeedy/rspeedy.defineconfig_3.md)

</td><td>

The `defineConfig` method is a helper function used to get TypeScript intellisense.

</td></tr>
<tr><td>

[loadConfig(loadConfigOptions)](/api/rspeedy/rspeedy.loadconfig.md)

</td><td>

Load the build config by the config path.

</td></tr>
<tr><td>

[mergeRspeedyConfig(configs)](/api/rspeedy/rspeedy.mergerspeedyconfig.md)

</td><td>

Merge multiple Rspeedy configuration objects.

</td></tr>
</tbody></table>

## Interfaces

<table><thead><tr><th>

Interface

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[BuildCache](/api/rspeedy/rspeedy.buildcache.md)

</td><td>

**_(BETA)_** Enable or configure persistent build cache.

</td></tr>
<tr><td>

[BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md)

</td><td>

The context passed to the [Filename.bundle](/api/rspeedy/rspeedy.filename.bundle.md) function.

</td></tr>
<tr><td>

[ChunkSplit](/api/rspeedy/rspeedy.chunksplit.md)

</td><td>

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

</td></tr>
<tr><td>

[ChunkSplitBySize](/api/rspeedy/rspeedy.chunksplitbysize.md)

</td><td>

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

</td></tr>
<tr><td>

[ChunkSplitCustom](/api/rspeedy/rspeedy.chunksplitcustom.md)

</td><td>

[Performance.chunkSplit](/api/rspeedy/rspeedy.performance.chunksplit.md) is used to configure the chunk splitting strategy.

</td></tr>
<tr><td>

[Config](/api/rspeedy/rspeedy.config.md)

</td><td>

The `Config` is the configuration that `rspeedy` uses.

</td></tr>
<tr><td>

[ConfigParams](/api/rspeedy/rspeedy.configparams.md)

</td><td>

Parameters for the function exported from `lynx.config.js`<!-- -->.

</td></tr>
<tr><td>

[CreateRspeedyOptions](/api/rspeedy/rspeedy.createrspeedyoptions.md)

</td><td>

The options of `createRspeedy` method.

</td></tr>
<tr><td>

[CssExtract](/api/rspeedy/rspeedy.cssextract.md)

</td><td>

The [CssExtract](/api/rspeedy/rspeedy.cssextract.md) controls the options of [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin)

</td></tr>
<tr><td>

[CssExtractRspackLoaderOptions](/api/rspeedy/rspeedy.cssextractrspackloaderoptions.md)

</td><td>

</td></tr>
<tr><td>

[CssExtractRspackPluginOptions](/api/rspeedy/rspeedy.cssextractrspackpluginoptions.md)

</td><td>

</td></tr>
<tr><td>

[CssLoader](/api/rspeedy/rspeedy.cssloader.md)

</td><td>

The [CssLoader](/api/rspeedy/rspeedy.cssloader.md) controls the options of [css-loader](https://github.com/webpack-contrib/css-loader)<!-- -->.

</td></tr>
<tr><td>

[CssLoaderModules](/api/rspeedy/rspeedy.cssloadermodules.md)

</td><td>

The [cssLoader.modules](/api/rspeedy/rspeedy.cssloadermodules.md) option enables/disables the CSS Modules specification and setup basic behavior.

</td></tr>
<tr><td>

[CssModules](/api/rspeedy/rspeedy.cssmodules.md)

</td><td>

The [CssModules](/api/rspeedy/rspeedy.cssmodules.md) option is used for the customization of CSS Modules configurations.

</td></tr>
<tr><td>

[Decorators](/api/rspeedy/rspeedy.decorators.md)

</td><td>

Used to configure the decorators syntax.

</td></tr>
<tr><td>

[Dev](/api/rspeedy/rspeedy.dev.md)

</td><td>

The [Dev](/api/rspeedy/rspeedy.dev.md) option is used to control the behavior related with development. Including: HMR, DevServer, etc.

</td></tr>
<tr><td>

[DevClient](/api/rspeedy/rspeedy.devclient.md)

</td><td>

Configuration of the development client.

</td></tr>
<tr><td>

[DistPath](/api/rspeedy/rspeedy.distpath.md)

</td><td>

Set the directory of the dist files.

</td></tr>
<tr><td>

[EntryDescription](/api/rspeedy/rspeedy.entrydescription.md)

</td><td>

The `EntryDescription` describes a entry. It is useful when the project has multiple entries with different configuration.

</td></tr>
<tr><td>

[ExposedAPI](/api/rspeedy/rspeedy.exposedapi.md)

</td><td>

The exposed API of Rspeedy. Can be used in Rsbuild plugin with [api.useExposed](https://rsbuild.rs/plugins/dev/core#apiuseexposed)<!-- -->.

</td></tr>
<tr><td>

[Filename](/api/rspeedy/rspeedy.filename.md)

</td><td>

The [Filename](/api/rspeedy/rspeedy.filename.md) determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.

</td></tr>
<tr><td>

[LoadConfigOptions](/api/rspeedy/rspeedy.loadconfigoptions.md)

</td><td>

The options of loadConfig.

</td></tr>
<tr><td>

[LoadConfigResult](/api/rspeedy/rspeedy.loadconfigresult.md)

</td><td>

The result of [loadConfig()](/api/rspeedy/rspeedy.loadconfig.md)<!-- -->.

</td></tr>
<tr><td>

[Minify](/api/rspeedy/rspeedy.minify.md)

</td><td>

The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

</td></tr>
<tr><td>

[Output](/api/rspeedy/rspeedy.output.md)

</td><td>

The [Output](/api/rspeedy/rspeedy.output.md) option is used to set how and where should the bundles and assets output.

</td></tr>
<tr><td>

[Performance](/api/rspeedy/rspeedy.performance.md)

</td><td>

The [Performance](/api/rspeedy/rspeedy.performance.md) option is used to optimize the build-time and runtime performance.

</td></tr>
<tr><td>

[Resolve](/api/rspeedy/rspeedy.resolve.md)

</td><td>

The [Resolve](/api/rspeedy/rspeedy.resolve.md) option is used to control the resolution behavior of Rspack.

</td></tr>
<tr><td>

[RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md)

</td><td>

Simplified options type for `tools.rsdoctor`<!-- -->.

Keep this type free of deeply nested/intersection utility types to ensure typia can generate validators from `Config`<!-- -->.

</td></tr>
<tr><td>

[Server](/api/rspeedy/rspeedy.server.md)

</td><td>

The [Server](/api/rspeedy/rspeedy.server.md) option changes the behavior of dev-server.

</td></tr>
<tr><td>

[Source](/api/rspeedy/rspeedy.source.md)

</td><td>

The [Source](/api/rspeedy/rspeedy.source.md) option changes the behavior of source files.

</td></tr>
<tr><td>

[SourceMap](/api/rspeedy/rspeedy.sourcemap.md)

</td><td>

The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

</td></tr>
<tr><td>

[Tools](/api/rspeedy/rspeedy.tools.md)

</td><td>

The [Tools](/api/rspeedy/rspeedy.tools.md) options changes the behavior of various building tools.

</td></tr>
<tr><td>

[TransformImport](/api/rspeedy/rspeedy.transformimport.md)

</td><td>

The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

</td></tr>
</tbody></table>

## Variables

<table><thead><tr><th>

Variable

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[rspackVersion](/api/rspeedy/rspeedy.rspackversion.md)

</td><td>

</td></tr>
<tr><td>

[version](/api/rspeedy/rspeedy.version.md)

</td><td>

</td></tr>
</tbody></table>

## Type Aliases

<table><thead><tr><th>

Type Alias

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[BundleFilename](/api/rspeedy/rspeedy.bundlefilename.md)

</td><td>

The name of the bundle files.

It can be a string with placeholders (`[name]`<!-- -->, `[contenthash]`<!-- -->, `[platform]`<!-- -->), or a function that returns a string based on the [BundleFilenameContext](/api/rspeedy/rspeedy.bundlefilenamecontext.md)<!-- -->.

</td></tr>
<tr><td>

[ConsoleType](/api/rspeedy/rspeedy.consoletype.md)

</td><td>

The type of the console method.

</td></tr>
<tr><td>

[CssModuleLocalsConvention](/api/rspeedy/rspeedy.cssmodulelocalsconvention.md)

</td><td>

The style of exported class names.

</td></tr>
<tr><td>

[Entry](/api/rspeedy/rspeedy.entry.md)

</td><td>

The [Entry](/api/rspeedy/rspeedy.entry.md) option is used to set the entry module.

</td></tr>
<tr><td>

[RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)

</td><td>

The instance of Rspeedy.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.mergerspeedyconfig.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [mergeRspeedyConfig](/api/rspeedy/rspeedy.mergerspeedyconfig.md)

## mergeRspeedyConfig() function

Merge multiple Rspeedy configuration objects.

**Signature:**

```typescript
export declare function mergeRspeedyConfig(...configs: Config[]): Config;
```

## Parameters

<table><thead><tr><th>

Parameter

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

configs

</td><td>

[Config](/api/rspeedy/rspeedy.config.md)<!-- -->\[]

</td><td>

The Rspeedy configuration objects to merge.

</td></tr>
</tbody></table>

**Returns:**

[Config](/api/rspeedy/rspeedy.config.md)

The merged Rspeedy configuration object.

## Remarks

This is actually an alias of [mergeRsbuildConfig](https://rsbuild.rs/api/javascript-api/core#mergersbuildconfig)<!-- -->.

## Example

```ts
import { mergeRspeedyConfig } from '@lynx-js/rspeedy';

const config1 = {
  dev: {
    writeToDisk: false,
  },
};
const config2 = {
  dev: {
    writeToDisk: true,
  },
};

const mergedConfig = mergeRspeedyConfig(config1, config2);

console.log(mergedConfig); // { dev: { writeToDisk: true } }
```



---
url: /api/rspeedy/rspeedy.minify.backgroundoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [backgroundOptions](/api/rspeedy/rspeedy.minify.backgroundoptions.md)

## Minify.backgroundOptions property

[Minify.backgroundOptions](/api/rspeedy/rspeedy.minify.backgroundoptions.md) is used to override [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) for background-thread bundles.

**Signature:**

```typescript
backgroundOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
```

## Default Value

undefined

## Remarks

This option is deep-merged into [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md)<!-- -->. It is mainly used together with ReactLynx dual-thread outputs so that main-thread and background-thread bundles can use different compress rules.



---
url: /api/rspeedy/rspeedy.minify.mainthreadoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md) > [mainThreadOptions](/api/rspeedy/rspeedy.minify.mainthreadoptions.md)

## Minify.mainThreadOptions property

[Minify.mainThreadOptions](/api/rspeedy/rspeedy.minify.mainthreadoptions.md) is used to override [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) for main-thread bundles.

**Signature:**

```typescript
mainThreadOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
```

## Default Value

undefined

## Remarks

This option is deep-merged into [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md)<!-- -->. It is mainly used together with ReactLynx dual-thread outputs so that main-thread and background-thread bundles can use different compress rules.

## Example

```ts
import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          compress: {
            pure_funcs: ['console.log'],
          },
        },
      },
      mainThreadOptions: {
        minimizerOptions: {
          compress: {
            pure_funcs: ['NativeModules.call', 'lynx.getJSModule'],
          },
        },
      },
    },
  },
})
```



---
url: /api/rspeedy/rspeedy.minify.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [Minify](/api/rspeedy/rspeedy.minify.md)

## Minify interface

The [Minify](/api/rspeedy/rspeedy.minify.md) configures whether to enable code minification in the production build, or to configure minimizer options.

**Signature:**

```typescript
export interface Minify 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[backgroundOptions?](/api/rspeedy/rspeedy.minify.backgroundoptions.md)

</td><td>

</td><td>

Rspack.SwcJsMinimizerRspackPluginOptions | undefined

</td><td>

_(Optional)_ [Minify.backgroundOptions](/api/rspeedy/rspeedy.minify.backgroundoptions.md) is used to override [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) for background-thread bundles.

</td></tr>
<tr><td>

[css?](/api/rspeedy/rspeedy.minify.css.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether enable the CSS minification.

</td></tr>
<tr><td>

[js?](/api/rspeedy/rspeedy.minify.js.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether enable the JavaScript minification.

</td></tr>
<tr><td>

[jsOptions?](/api/rspeedy/rspeedy.minify.jsoptions.md)

</td><td>

</td><td>

Rspack.SwcJsMinimizerRspackPluginOptions | undefined

</td><td>

_(Optional)_ [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) is used to configure SWC minification options.

</td></tr>
<tr><td>

[mainThreadOptions?](/api/rspeedy/rspeedy.minify.mainthreadoptions.md)

</td><td>

</td><td>

Rspack.SwcJsMinimizerRspackPluginOptions | undefined

</td><td>

_(Optional)_ [Minify.mainThreadOptions](/api/rspeedy/rspeedy.minify.mainthreadoptions.md) is used to override [Minify.jsOptions](/api/rspeedy/rspeedy.minify.jsoptions.md) for main-thread bundles.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.linter.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md) > [linter](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.linter.md)

## RsdoctorRspackPluginOptions.linter property

**Signature:**

```typescript
linter?: {
        rules?: Record<string, unknown>;
        level?: 'Ignore' | 'Warn' | 'Error';
        extends?: unknown[];
    };
```



---
url: /api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [RsdoctorRspackPluginOptions](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.md)

## RsdoctorRspackPluginOptions interface

Simplified options type for `tools.rsdoctor`<!-- -->.

Keep this type free of deeply nested/intersection utility types to ensure typia can generate validators from `Config`<!-- -->.

**Signature:**

```typescript
export interface RsdoctorRspackPluginOptions extends Omit<RawRsdoctorRspackPluginOptions<[]>, 'linter'> 
```

**Extends:** Omit\<RawRsdoctorRspackPluginOptions\<\[]>, 'linter'>

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[linter?](/api/rspeedy/rspeedy.rsdoctorrspackpluginoptions.linter.md)

</td><td>

</td><td>

\{ rules?: Record\<string, unknown>; level?: 'Ignore' | 'Warn' | 'Error'; extends?: unknown\[]; }

</td><td>

_(Optional)_

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.rspackversion.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [rspackVersion](/api/rspeedy/rspeedy.rspackversion.md)

## rspackVersion variable

**Signature:**

```typescript
rspackVersion: string
```



---
url: /api/rspeedy/rspeedy.rspeedyinstance.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [RspeedyInstance](/api/rspeedy/rspeedy.rspeedyinstance.md)

## RspeedyInstance type

The instance of Rspeedy.

**Signature:**

```typescript
export type RspeedyInstance = RsbuildInstance & {
    getRspeedyConfig(): Config;
};
```

**References:** [Config](/api/rspeedy/rspeedy.config.md)



---
url: /api/rspeedy/rspeedy.sourcemap.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [SourceMap](/api/rspeedy/rspeedy.sourcemap.md)

## SourceMap interface

The [SourceMap](/api/rspeedy/rspeedy.sourcemap.md) configures whether and how to generate source-map for outputs.

**Signature:**

```typescript
export interface SourceMap 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[css?](/api/rspeedy/rspeedy.sourcemap.css.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether to generate CSS source maps.

</td></tr>
<tr><td>

[js?](/api/rspeedy/rspeedy.sourcemap.js.md)

</td><td>

</td><td>

Rspack.DevTool | undefined | \`$\{Exclude\<Rspack.DevTool, false | 'eval'>}-debugids\`

</td><td>

_(Optional)_ How the source map should be generated. Setting it to `false` will disable the source map.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.transformimport.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [TransformImport](/api/rspeedy/rspeedy.transformimport.md)

## TransformImport interface

The [TransformImport](/api/rspeedy/rspeedy.transformimport.md) option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by [babel-plugin-import](https://npmjs.com/package/babel-plugin-import)<!-- -->.

**Signature:**

```typescript
export interface TransformImport 
```

## Properties

<table><thead><tr><th>

Property

</th><th>

Modifiers

</th><th>

Type

</th><th>

Description

</th></tr></thead>
<tbody><tr><td>

[camelToDashComponentName?](/api/rspeedy/rspeedy.transformimport.cameltodashcomponentname.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether to convert camelCase imports to kebab-case.

</td></tr>
<tr><td>

[customName?](/api/rspeedy/rspeedy.transformimport.customname.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Customize the transformed path.

</td></tr>
<tr><td>

[libraryDirectory?](/api/rspeedy/rspeedy.transformimport.librarydirectory.md)

</td><td>

</td><td>

string | undefined

</td><td>

_(Optional)_ Used to splice the transformed path, the splicing rule is `${libraryName}/${libraryDirectory}/${member}`<!-- -->, where member is the imported member.

</td></tr>
<tr><td>

[libraryName](/api/rspeedy/rspeedy.transformimport.libraryname.md)

</td><td>

</td><td>

string

</td><td>

The original import path that needs to be transformed.

</td></tr>
<tr><td>

[transformToDefaultImport?](/api/rspeedy/rspeedy.transformimport.transformtodefaultimport.md)

</td><td>

</td><td>

boolean | undefined

</td><td>

_(Optional)_ Whether to convert import statements to default imports.

</td></tr>
</tbody></table>



---
url: /api/rspeedy/rspeedy.version.md
---

# 

<!-- Do not edit this file. It is automatically generated by API Documenter. -->

[Home](/api/rspeedy/index.md) > [@lynx-js/rspeedy](/api/rspeedy/rspeedy.md) > [version](/api/rspeedy/rspeedy.version.md)

## version variable

**Signature:**

```typescript
version: string
```



---
url: /api/status.md
---

APIStatusLayout


---
url: /learn/gallery.md
---

Tutorial: Product Gallery[Tutorial: Product Detail](/learn/product-detail)
# Tutorial: Product Gallery

We will build a product gallery page together during this tutorial. This tutorial does not assume any existing Lynx knowledge. The techniques you'll learn in the tutorial are fundamental to building any Lynx pages and applications.

:::note

This tutorial is designed for people who prefer to learn by doing and want to quickly try making something tangible. If you prefer learning each concept step by step, start with [Describing the UI](/guide/ui/elements-components.md).

:::

## What are we building?

Let's first have a look at the result! To see the page live, download and install [LynxExplorer](/guide/start/quick-start.md#ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator) on your device, then scan the generated QR code below.

**This is an example below: gallery**

**Entry:** `src/GalleryComplete.tsx`
**Bundle:** `dist/GalleryComplete.lynx.bundle` | Web: `dist/GalleryComplete.web.bundle`

```tsx {6}
import { root } from "@lynx-js/react";
import { furnituresPictures } from "../Pictures/furnitures/furnituresPictures.jsx";
import Gallery from "./Gallery.jsx";

function GalleryComplete() {
  return <Gallery pictureData={furnituresPictures} />;
}

root.render(<GalleryComplete />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/Pictures.tar.gz) to use in your projects.

## Adding Styles

Since the focus of this tutorial is not on how to style your UI, you may just save some time and directly copy the below `index.css` file:

```css title="index.css"
.gallery-wrapper {
  height: 100vh;
  background-color: black;
}

.single-card {
  display: flex;
  align-items: center;
  justify-content: center;
}

.scrollbar {
  position: absolute;
  right: 7px;
  z-index: 1000;
  width: 4px;
  background: linear-gradient(to bottom, #ff6448, #ccddff, #3deae7);
  border-radius: 5px;
  overflow: hidden;
  box-shadow:
    0px 0px 4px 1px rgba(12, 205, 223, 0.4),
    0px 0px 16px 5px rgba(12, 205, 223, 0.5);
}

.scrollbar-effect {
  width: 100%;
  height: 80%;
}

.glow {
  background-color: #333;
  border-radius: 4px;
  background: linear-gradient(
    45deg,
    rgba(255, 255, 255, 0) 20%,
    rgba(255, 255, 255, 0.8) 50%,
    rgba(255, 255, 255, 0) 80%
  );
  animation: flow 3s linear infinite;
}

@keyframes flow {
  0% {
    transform: translateY(-100%);
  }
  100% {
    transform: translateY(100%);
  }
}

.list {
  width: 100vw;
  padding-bottom: 20px;
  padding-left: 20px;
  padding-right: 20px;
  height: calc(100% - 48px);
  list-main-axis-gap: 10px;
  list-cross-axis-gap: 10px;
}

.picture-wrapper {
  border-radius: 10px;
  overflow: hidden;
  width: 100%;
}

.like-icon {
  position: absolute;
  display: grid;
  justify-items: center;
  align-items: center;
  top: 0px;
  right: 0px;
  width: 48px;
  height: 48px;
}

.heart-love {
  width: 16px;
  height: 16px;
}

.circle {
  position: absolute;
  top: calc(50% - 8px);
  left: calc(50% - 8px);
  height: 16px;
  width: 16px;
  border: 2px solid red;
  border-radius: 50%;
  transform: scale(0);
  opacity: 1;
  animation: ripple 1s 1 ease-out;
}

.circleAfter {
  animation-delay: 0.5s;
}

@keyframes ripple {
  0% {
    transform: scale(1);
    opacity: 1;
  }
  100% {
    transform: scale(2);
    opacity: 0;
  }
}
```

and import it as a global styles:

```js
import '../index.scss';
```

This make sure your UI look great when you are following this tutorial.

:::info Styling variations in Lynx
Lynx supports a wide variaties of styling features, including global styles, CSS Modules, inline styles, Sass, CSS variables, and more! Please refer to [Rspeedy - Styling](/rspeedy/styling.md) page for how to pick your best styling configurations.
:::

## Your First Component: An Image Card

Now, let's start by creating the first image card, which will be the main part of this page.

**This is an example below: gallery**

**Entry:** `src/FirstImageCard`
**Bundle:** `dist/FirstImageCard.lynx.bundle` | Web: `dist/FirstImageCard.web.bundle`

```tsx {11}
import { furnituresPictures } from "../Pictures/furnitures/furnituresPictures.jsx";
import ImageCard from "./ImageCard.jsx";
import "../index.scss";

import { root } from "@lynx-js/react";

function FirstImageCard() {
  const MyFirstPicture = furnituresPictures[0];
  return (
    <view className="gallery-wrapper single-card">
      <ImageCard picture={MyFirstPicture} />
    </view>
  );
}

root.render(<FirstImageCard />);

```



Great, you can now see the image card displayed. Here, we use the [`<image>`](/api/elements/built-in/image.md) element to display your image. You only need to give it a width and height (or specify the aspectRatio property as shown here), and it will automatically resize to fit the specified dimensions.
This component can receive a picture property, allowing you to change the image it displays. In fact, all components can receive external inputs like this, giving you control over them.

:::details The src Attribute of Images
The Lynx `<image>` element can accept a local relative path as the `src` attribute to render an image, which is the most important attribute of the `<image>` element. All images in this page are sourced locally, and these paths need to be imported before use.

However, if your images are stored online, you can easily replace them with web image addresses by changing the value of the src attribute to the corresponding web image link.
:::

## Adding interactivity: Like an Image Card

We can add a small white heart in the upper right corner and make it the like button for the image card. Here, we implement a small component called `LikeIcon`:

**This is an example below: gallery**

**Entry:** `src/Components`
**Bundle:** `dist/LikeImageCard.lynx.bundle` | Web: `dist/LikeImageCard.web.bundle`

```tsx {7-10,13-15}
import { useState } from "@lynx-js/react";
import redHeart from "../Pictures/redHeart.png";
import whiteHeart from "../Pictures/whiteHeart.png";
import "../index.scss";

export default function LikeIcon() {
  const [isLiked, setIsLiked] = useState(false);
  const onTap = () => {
    setIsLiked(true);
  };
  return (
    <view className="like-icon" bindtap={onTap}>
      {isLiked && <view className="circle" />}
      {isLiked && <view className="circle circleAfter" />}
      <image src={isLiked ? redHeart : whiteHeart} className="heart-love" />
    </view>
  );
}

```



We want each card to know whether it has been liked, so we added isLiked, which is its internal data. It can use this internal data to save your changes.

```tsx title="LikeIcon.tsx" {2}
...
  const [isLiked, setIsLiked] = useState(false);
...
```

Then we add the bindtap event to `<image>`, so that when the user clicks the heart, it triggers this event and changes the state of `isLiked`:

```tsx title="LikeIcon.tsx" {3,7}
...
  const onTap = () => {
    setIsLiked(true);
  }
  return (
      ...
      <image bindtap={onTap}/>
  )
...
```

:::details What is "bindtap"?
If you come from a web development background, you might be more familiar with naming conventions like onclick (HTML attribute) or onClick (in the React community). Lynx follows a different convention: due to the static nature of its architecture, it uses `bind*` and `catch*`. Learn more on the [Event Handling](/guide/interaction/event-handling.md) page.
:::

Finally, we use `isLiked` to control the like effect. Because isLiked is a state, `LikeIcon` will respond to its changes, turning into a red like icon, and the `<view>` used to render the animation effect will be conditionally rendered:

```tsx title="LikeIcon.tsx"
...
  return
    ...
      {isLiked && <view className="circle" />}
      {isLiked && <view className="circle circleAfter" />}
      <image src={isLiked ? redHeart : whiteHeart} />
...
```

To give this like a better visual interaction effect, we added animations, which are all in index.css. You can also learn more about animations in the [Animation](/guide/styling/animation.md) section. Then replace it with your preferred style!

## Displaying More Images with `<list>`

To show all your beautiful images, you may need help from `<list>`. This way, you will get a scrollable page that displays a large number of similar images:

**This is an example below: gallery**

**Entry:** `src/CreateGallery`
**Bundle:** `dist/CreateGallery.lynx.bundle` | Web: `dist/CreateGallery.web.bundle`

```tsx {11,19,24}
import type { Picture } from "../Pictures/furnitures/furnituresPictures.jsx";
import "../index.scss";
import LikeImageCard from "../Components/LikeImageCard.jsx";
import { calculateEstimatedSize } from "../utils.jsx";

export const Gallery = (props: { pictureData: Picture[] }) => {
  const { pictureData } = props;

  return (
    <view className="gallery-wrapper">
      <list
        className="list"
        list-type="waterfall"
        column-count={2}
        scroll-orientation="vertical"
        custom-list-name="list-container"
      >
        {pictureData.map((picture: Picture, index: number) => (
          <list-item
            estimated-main-axis-size-px={calculateEstimatedSize(picture.width, picture.height)}
            item-key={"" + index}
            key={"" + index}
          >
            <LikeImageCard picture={picture} />
          </list-item>
        ))}
      </list>
    </view>
  );
};

export default Gallery;

```



:::details Special child elements of list
Each child component of `<list>` needs to be `<list-item>`, and you must specify a unique and non-repeating key and item-key attribute, otherwise it may not render correctly.
:::

Of course, we also provide other scrolling elements, such as `<scroll-view>`, to achieve similar effects. Here, we use a waterfall layout as the child node layout option. `<list>` also accepts other layout types, which you can refer to in [list](/api/elements/built-in/list.md).

:::info
You can refer to this [Scrolling](/guide/ui/scrolling.md) documentation to learn more about scrolling and scrolling elements.
:::

## Auto-Scrolling via Element Methods

If you want to create a desktop photo wall, you need to add an auto-scroll feature to this page. Your images will be slowly and automatically scrolled, allowing you to easily see more images:

**This is an example below: gallery**

**Entry:** `src/AddAutoScroll`
**Bundle:** `dist/AddAutoScroll.lynx.bundle` | Web: `dist/AddAutoScroll.web.bundle`

```tsx {10,12-22,27}
import "../index.scss";
import { useEffect, useRef } from "@lynx-js/react";
import type { NodesRef } from "@lynx-js/types";
import LikeImageCard from "../Components/LikeImageCard.jsx";
import type { Picture } from "../Pictures/furnitures/furnituresPictures.jsx";
import { calculateEstimatedSize } from "../utils.jsx";

export const Gallery = (props: { pictureData: Picture[] }) => {
  const { pictureData } = props;
  const galleryRef = useRef<NodesRef>(null);

  useEffect(() => {
    galleryRef.current
      ?.invoke({
        method: "autoScroll",
        params: {
          rate: "60",
          start: true,
        },
      })
      .exec();
  }, []);

  return (
    <view className="gallery-wrapper">
      <list
        ref={galleryRef}
        className="list"
        list-type="waterfall"
        column-count={2}
        scroll-orientation="vertical"
        custom-list-name="list-container"
      >
        {pictureData.map((picture: Picture, index: number) => (
          <list-item
            estimated-main-axis-size-px={calculateEstimatedSize(picture.width, picture.height)}
            item-key={"" + index}
            key={"" + index}
          >
            <LikeImageCard picture={picture} />
          </list-item>
        ))}
      </list>
    </view>
  );
};

export default Gallery;

```



We use the `useEffect` hook to call the [`autoScroll`](/api/elements/built-in/list.md#autoscroll) method.

```tsx title="Gallery.tsx"
useEffect(() => {
  listRef.current
    ?.invoke({
      method: 'autoScroll',
      params: {
        rate: '60',
        start: true,
      },
    })
    .exec();
}, []);
```

:::details What is "invoke"?
In Lynx, all native elements have a set of "methods" that can be called via their ref. Unlike on the web, this call is asynchronous, similar to message passing. You need to use invoke with the method name method and parameters param to call them.
:::

## How about a Custom Scrollbar?

Like most apps, we can add a scrollbar to this page to indicate how many images are left to be displayed. But we can do more! For example, we can replace the default progress bar of `<list>` with our preferred style:

**This is an example below: gallery**

**Entry:** `src/AddNiceScrollbar`
**Bundle:** `dist/AddNiceScrollbar.lynx.bundle` | Web: `dist/AddNiceScrollbar.web.bundle`

```tsx {14-19,37,45-46,50}
import "../index.scss";
import { useEffect, useRef } from "@lynx-js/react";
import type { ScrollEvent } from "@lynx-js/types";
import type { NodesRef } from "@lynx-js/types";
import LikeImageCard from "../Components/LikeImageCard.jsx";
import type { Picture } from "../Pictures/furnitures/furnituresPictures.jsx";
import { calculateEstimatedSize } from "../utils.jsx";
import { NiceScrollbar, type NiceScrollbarRef } from "./NiceScrollbar.jsx";

export const Gallery = (props: { pictureData: Picture[] }) => {
  const { pictureData } = props;
  const scrollbarRef = useRef<NiceScrollbarRef>(null);

  const onScroll = (event: ScrollEvent) => {
    scrollbarRef.current?.adjustScrollbar(
      event.detail.scrollTop,
      event.detail.scrollHeight,
    );
  };

  const galleryRef = useRef<NodesRef>(null);

  useEffect(() => {
    galleryRef.current
      ?.invoke({
        method: "autoScroll",
        params: {
          rate: "60",
          start: true,
        },
      })
      .exec();
  }, []);

  return (
    <view className="gallery-wrapper">
      <NiceScrollbar ref={scrollbarRef} />
      <list
        ref={galleryRef}
        className="list"
        list-type="waterfall"
        column-count={2}
        scroll-orientation="vertical"
        custom-list-name="list-container"
        bindscroll={onScroll}
        scroll-event-throttle={0}
      >
        {pictureData.map((picture: Picture, index: number) => (
          <list-item
            estimated-main-axis-size-px={calculateEstimatedSize(
              picture.width,
              picture.height,
            )}
            item-key={"" + index}
            key={"" + index}
          >
            <LikeImageCard picture={picture} />
          </list-item>
        ))}
      </list>
    </view>
  );
};

export default Gallery;

```



Similar to the `bindtap` event used to add the like functionality, we add the [`scroll`](/api/elements/built-in/list.md#scroll) event to `<list>`, which will be triggered when the `<list>` element scrolls. To make the scrollbar respond faster to scroll events, we need to set [`scroll-event-throttle`](/api/elements/built-in/list.md#scroll-event-throttle) to 0.

```tsx title="Gallery.tsx" {16}
...
const onScroll = (event: ScrollEvent) => {
  scrollbarRef.current?.adjustScrollbar(
    event.detail.scrollTop,
    event.detail.scrollHeight
  );
};
...
<list
  ref={galleryRef}
  className="list"
  list-type="waterfall"
  column-count={2}
  scroll-orientation="vertical"
  custom-list-name="list-container"
  bindscroll={onScroll}
  scroll-event-throttle={0}
>
...
```

The NiceScrollbar component provides an internal method adjustScrollbar, which we call to adjust the scrollbar's position whenever the bindscroll event is triggered.

:::info
We use many React techniques in this component, such as `forwardRef` and `useImperativeHandle` for calling the `adjustScrollbar` method. If you are not familiar with them, you can refer to the React official documentation to better understand them.
:::

```tsx title="NiceScrollbar.tsx" {14-19}
...
const adjustScrollbar = (scrollTop: number, scrollHeight: number) => {
  const listHeight = lynx.__globalProps.screenHeight - 48;
  const scrollbarHeight = listHeight * (listHeight / scrollHeight);
  const scrollbarTop = listHeight * (scrollTop / scrollHeight);
  setScrollbarHeight(scrollbarHeight);
  setScrollbarTop(scrollbarTop);
};
...
```

:::details \_\_globalProps
We use [globalProps](/api/lynx-api/lynx/lynx-global-props.md) in this method, where you can use `screenHeight` and `screenWidth` to get the screen height and width.
:::

:::details list-item's estimated-main-axis-size-px
You may have noticed this attribute [estimated-main-axis-size-px](/api/elements/built-in/list.md#estimated-main-axis-size-px). This attribute can estimate the size of elements on the main axis when they are not yet rendered in `<list>`. This is very useful when we add a scrollbar, as we need to know how long the scrollbar needs to be to cover all elements.

Of course, `<list>` also supports automatic layout. You can remove this attribute and see the effect—your scrollbar will automatically adjust its length as the elements change from preset height to actual height.

```tsx title="src/AddNiceScrollbar/Gallery.tsx" {5}
...
  <list>
    {pictureData.map((picture: Picture, index: number) => (
      <list-item
        estimated-main-axis-size-px={calculateEstimatedSize(
          picture.width,
          picture.height
        )}
        item-key={"" + index}
        key={"" + index}
      >
        <LikeImageCard picture={picture} />
      </list-item>
    ))}
  </list>
...
```

We provide a utility method to estimate the size of the image on the main axis based on the current `<list>` layout information and the image dimensions:

```tsx title="src/utils.tsx"
export const calculateEstimatedSize = (
  pictureWidth: number,
  pictureHeight: number,
) => {
  // Fixed styles of the gallery
  const galleryPadding = 20;
  const galleryMainAxisGap = 10;
  const gallerySpanCount = 2;
  const galleryWidth = lynx.__globalProps.screenWidth;
  // Calculate the width of each ImageCard and return the relative height of the it.
  const itemWidth =
    (galleryWidth - galleryPadding * 2 - galleryMainAxisGap) / gallerySpanCount;
  return (itemWidth / pictureWidth) * pictureHeight;
};
```

:::

At this point, we have a complete page! But you may have noticed that the scrollbar we added still lags a bit during scrolling, not as responsive as it could be. This is because our adjustments are still happening on the background thread, not the main thread that responds to touch scrolling.

:::details What are the background thread and main thread?
The biggest feature of Lynx is its dual-thread architecture. You can find a more detailed introduction in [JavaScript Runtime](/guide/scripting-runtime/index.md#javascript).
:::

## A More Responsive Scrollbar

To optimize the performance of the scrollbar, we need to introduce [Main Thread Script (MTS)](/react/main-thread-script.md) to [handle events on the main thread](/guide/interaction/event-handling.md#main-thread-event-processing), migrating the adjustments we made in the previous step for the scrollbar's height and position from the background thread to the main thread.

To let you see the comparison more clearly, we keep both scrollbars:

**This is an example below: gallery**

**Entry:** `src/ScrollbarCompare`
**Bundle:** `dist/ScrollbarCompare.lynx.bundle` | Web: `dist/ScrollbarCompare.web.bundle`

```tsx {2,3,9,14,17-23,47,48}
import "../index.scss";
import { useEffect, useMainThreadRef, useRef } from "@lynx-js/react";
import { MainThread, type ScrollEvent } from "@lynx-js/types";
import type { NodesRef } from "@lynx-js/types";
import LikeImageCard from "../Components/LikeImageCard.jsx";
import type { Picture } from "../Pictures/furnitures/furnituresPictures.jsx";
import { calculateEstimatedSize } from "../utils.jsx";
import { NiceScrollbar, type NiceScrollbarRef } from "./NiceScrollbar.jsx";
import { adjustScrollbarMTS, NiceScrollbarMTS } from "./NiceScrollbarMTS.jsx";

export const Gallery = (props: { pictureData: Picture[] }) => {
  const { pictureData } = props;
  const scrollbarRef = useRef<NiceScrollbarRef>(null);
  const scrollbarMTSRef = useMainThreadRef<MainThread.Element>(null);
  const galleryRef = useRef<NodesRef>(null);

  const onScrollMTS = (event: ScrollEvent) => {
    "main thread";
    adjustScrollbarMTS(
      event.detail.scrollTop,
      event.detail.scrollHeight,
      scrollbarMTSRef,
    );
  };

  const onScroll = (event: ScrollEvent) => {
    scrollbarRef.current?.adjustScrollbar(
      event.detail.scrollTop,
      event.detail.scrollHeight,
    );
  };

  useEffect(() => {
    galleryRef.current
      ?.invoke({
        method: "autoScroll",
        params: {
          rate: "60",
          start: true,
        },
      })
      .exec();
  }, []);

  return (
    <view className="gallery-wrapper">
      <NiceScrollbar ref={scrollbarRef} />
      <NiceScrollbarMTS main-thread:ref={scrollbarMTSRef} />
      <list
        ref={galleryRef}
        className="list"
        list-type="waterfall"
        column-count={2}
        scroll-orientation="vertical"
        custom-list-name="list-container"
        bindscroll={onScroll}
        main-thread:bindscroll={onScrollMTS}
        scroll-event-throttle={0}
      >
        {pictureData.map((picture: Picture, index: number) => (
          <list-item
            estimated-main-axis-size-px={calculateEstimatedSize(picture.width, picture.height)}
            item-key={"" + index}
            key={"" + index}
          >
            <LikeImageCard picture={picture} />
          </list-item>
        ))}
      </list>
    </view>
  );
};

export default Gallery;

```



Now you should be able to see that the scrollbar on the left, controlled with main thread scripting, is smoother and more responsive compared to the scrollbar on the right that we implemented earlier. If you encounter issues in other UIs where updates need to happen immediately, try this method.

We also provide another tutorial, guiding you through a deep dive into implementing a highly responsive swiper in [Tutorial: Product Detail](/learn/product-detail.md).

## Wrapping Up

We remove the redundant scrollbar used for comparison, and our Gallery is now complete! Let's take a look at the final result:

**This is an example below: gallery**

**Bundle:** `dist/GalleryComplete.lynx.bundle` | Web: `dist/GalleryComplete.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import { furnituresPictures } from "../Pictures/furnitures/furnituresPictures.jsx";
import Gallery from "./Gallery.jsx";

function GalleryComplete() {
  return <Gallery pictureData={furnituresPictures} />;
}

root.render(<GalleryComplete />);

```



Configurations! You have successfully created a product gallery page! 🎉 Throughout this tutorial, you’ve covered the basics of writing interactive UIs on the Lynx platform and some of the differences between using it on the Web.



---
url: /learn/product-detail.md
---

[Tutorial: Product Gallery](/learn/gallery)Tutorial: Product Detail
# Tutorial: Product Detail

In this tutorial, we'll implement a swiper component to teach you how to write high-performance interactive code. You'll learn:

- [Direct Node Manipulation](#direct-node-manipulation): You'll learn how to listen to events and update node styles
- [Use Main Thread Script to Reduce Latency](#use-main-thread-scripts-to-reduce-latency): You'll learn how to optimize interaction performance with main thread script
- [Communication Between Main Thread and Background Thread](#communication-between-main-thread-and-background-thread): You'll learn how to enable communication between main thread and background thread functions
- [Values Across Main Thread and Background Thread Script](#values-across-main-thread-and-background-thread-script): You'll learn about data flow when using main thread and background thread script together

## What Are We Building?

Let's have a look at what we're building! To try it out, download and install the [Lynx Explorer App](/guide/start/quick-start.md#ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator), then scan the QR code below.

**This is an example below: swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Setup for the tutorial

Check out our detailed [quick start](/guide/start/quick-start.md) doc that will guide you through creating a new Lynx project.

You may notice that the project is using TypeScript. Although Lynx and ReactLynx support both TypeScript and plain JavaScript, we recommend TypeScript for a better development experience, provided by static type checking and better editor IntelliSense.

You'll see lots of beautiful images throughout this guide. We've put together a package of sample images you can download [here](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/download/product_detail_assets.zip) to use in your projects.

## Direct Node Manipulation

Here's a product detail page example that includes a swiper and some product details. The `<Swiper>` accepts images and displays them in a row. Currently, it can't scroll - let's make it interactive.

**This is an example below: swiper**

**Entry:** `src/SwiperEmpty, src/utils/pics.ts`
**Bundle:** `dist/SwiperEmpty.lynx.bundle` | Web: `dist/SwiperEmpty.web.bundle`

```tsx {10}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} />
    </Page>
  );
}

root.render(<App />);

```



To achieve this, we need to complete two tasks:

1. Listen to touch events
2. Update scroll position

### Listen to Touch Events

Let's start by listening to touch events to calculate the current scroll progress.

When a touch starts, we record the initial touch coordinates. This allows us to calculate the distance moved (represented by `delta`) when the finger moves.

```tsx title="index.tsx" "{4-6,8-10}"
function Swiper() {
  const touchStartXRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
  }

  return (
    <view
      class="swiper-container"
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
    >
      {/* ... */}
    </view>
  );
}
```

Next, we use `currentOffsetRef` to track the swiper component's offset, adding it to `delta` to get the final offset.

```tsx title="index.tsx" "{13}"
function Swiper() {
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
  }
}
```

### Updating Scroll Position

Once we get the offset, we can update the scroll position. Add an `updateSwiperOffset` function and call it when the finger moves.

```tsx title="index.tsx" "{9}"
function Swiper() {
  function updateSwiperOffset(offset: number) {
    // Update scroll position
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;
    updateSwiperOffset(offset);
  }
}
```

Next, we use [Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to get the `swiper-container` node and use [`setNativeProps`](/api/lynx-api/nodes-ref/nodes-ref-set-native-props.md) to update the `transform` property, thereby updating the scroll position.

```tsx title="index.tsx" "{5-9,14}"
function Swiper() {
  const containerRef = useRef<NodesRef>(null);

  function updateSwiperOffset(offset: number) {
    containerRef.current
      ?.setNativeProps({
        style: {
          transform: `translateX(${offset}px)`,
        },
      })
      .exec();
  }

  return <view ref={containerRef}></view>;
}
```

**This is an example below: swiper**

**Entry:** `src/UpdateOffset, src/utils/pics.ts`
**Bundle:** `dist/UpdateOffset.lynx.bundle` | Web: `dist/UpdateOffset.web.bundle`

```tsx
import "./styles.scss";
import { useRef } from "@lynx-js/react";
import type { NodesRef, TouchEvent } from "@lynx-js/types";
import { SwiperItem } from "./SwiperItem";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const containerRef = useRef<NodesRef>(null);
  const currentOffsetRef = useRef<number>(0);
  const touchStartXRef = useRef<number>(0);
  const touchStartCurrentOffsetRef = useRef<number>(0);

  function updateSwiperOffset(offset: number) {
    currentOffsetRef.current = offset;
    containerRef.current?.setNativeProps({
      transform: `translateX(${offset}px)`,
    }).exec();
  }

  function handleTouchStart(e: TouchEvent) {
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: TouchEvent) {
    const delta = e.touches[0].clientX - touchStartXRef.current;
    const offset = touchStartCurrentOffsetRef.current + delta;

    updateSwiperOffset(offset);
  }

  function handleTouchEnd(e: TouchEvent) {
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



Now the `<Swiper>` component can scroll with finger movements!

::: details Why not use state to update progress?
You might think of using `state` to update the progress, like this:

```tsx title="Swiper.tsx"
function Swiper() {
  const [offset, setOffset] = useState(0);

  return (
    <view style={{ transform: `translateX(${offset}px)` }}>{/* ... */}</view>
  );
}
```

However, in scenarios requiring frequent updates, this approach would cause constant component re-rendering, affecting performance. A better approach is to directly manipulate nodes, as shown in the example.

You can refer to [Direct Node Manipulation](/guide/interaction/event-handling/manipulating-element.react.md) to learn more.
:::

### Simplifying Code with Hooks

The `<Swiper>` component's code is getting complex. We can use hooks to encapsulate the logic into two parts, simplifying the component code and improving maintainability:

1. Encapsulate the [touch event listening](#listening-to-touch-events) code into `useOffset`, centralizing all scroll-related logic in this hook
2. Encapsulate the [scroll position update](#updating-scroll-position) code into `useUpdateSwiperStyle`, centralizing all `<Swiper>` component style update logic in this hook

```tsx title="Swiper.tsx"
function Swiper() {
  const { updateSwiperStyle, swiperContainerRef } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view
      class="swiper-container"
      ref={swiperContainerRef}
      bindtouchstart={handleTouchStart}
      bindtouchmove={handleTouchMove}
      bindtouchend={handleTouchEnd}
    >
      {/* ... */}
    </view>
  );
}
```

Finally, the code is more concise.

**This is an example below: swiper**

**Entry:** `src/SwiperHooks, src/utils/pics.ts`
**Bundle:** `dist/SwiperHooks.lynx.bundle` | Web: `dist/SwiperHooks.web.bundle`

```tsx {13-16}
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        ref={containerRef}
        bindtouchstart={handleTouchStart}
        bindtouchmove={handleTouchMove}
        bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



## Use Main Thread Script to Reduce Latency

You may have noticed that sometimes the scrolling doesn't feel smooth. This is because touch events occur in the **main thread**, while event listener code runs in the **background thread**, causing delayed touch event responses. This phenomenon is particularly noticeable on low-end devices.

We can use [Main Thread Script](/react/main-thread-script.md) to optimize this issue. After converting to main thread script, the scrolling becomes much smoother!

**This is an example below: swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



To achieve that, we need to migrate frequently triggered code to main thread script, including:

1. Event listener code
2. Node position update code

Let's modify both `useOffset` and `useUpdateSwiperStyle`.

### `useOffset`

Add the `main thread` identifier to `handleTouchStart` and `handleTouchMove` to convert them into **main thread functions**.

```tsx title="useOffset.ts"
function useOffset() {
  const touchStartXRef = useMainThreadRef<number>(0);

  function handleTouchStart(e: TouchEvent) {
    'main thread'
    ...
  }

  function handleTouchMove(e: TouchEvent) {
    'main thread'
    ...
  }
}
```

Convert `bindtouchstart` and `bindtouchmove` to `main-thread:bindtouchstart` and `main-thread:bindtouchmove` to listen to events in main thread script.

```tsx title="index.tsx"
<view
  main-thread:bindtouchstart={handleTouchStart}
  main-thread:bindtouchmove={handleTouchMove}
>
  {/* ... */}
</view>
```

### `useUpdateSwiperStyle`

Convert `useRef` to `useMainThreadRef`.

```tsx title="useUpdateSwiperStyle.ts" "{2}"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
   'main thread'
    ...
  }

  return {
    swiperContainerRef,
  }
}
```

Pass `swiperContainerRef` to `<view>` through the `main-thread:ref` attribute to access the node in the main thread.

```tsx title="index.tsx"
<view main-thread:ref={swiperContainerRef}>{/* ... */}</view>
```

The main thread node provides many capabilities, as shown in [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md). Here we call the `setStyleProperties` method to modify the `transform` property, updating the `<Swiper>` component's position.

```tsx title="useUpdateSwiperStyle.ts"
function useUpdateSwiperStyle() {
  const swiperContainerRef = useMainThreadRef<MainThread.Element>(null);

  function updateSwiperStyle(offset: number) {
    'main thread';
    swiperContainerRef.current?.setStyleProperties({
      transform: `translateX(${offset}px)`,
    });
  }
}
```

With this, we've completed the main thread script conversion. Now high-frequency functions run in the main thread, making the interaction smoother.

**This is an example below: swiper**

**Entry:** `src/SwiperMTS, src/utils/pics.ts`
**Bundle:** `dist/SwiperMTS.lynx.bundle` | Web: `dist/SwiperMTS.web.bundle`

```tsx
import "./styles.scss";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
    </view>
  );
}

```



::: details Use Main Thread Script Sparingly
Only use main thread script when encountering response delay issues with frequently triggered events!

- Introducing main thread script increases code complexity because main thread script and background thread script run in isolated environments and need "special bridges" to communicate.

- Main thread script run high-frequency code in the main thread, increasing its burden. Overuse may cause main thread lag.

:::

## Communication Between Main Thread and Background Thread

Here's a progress indicator example that shows which page you're on when scrolling.

Currently, it only has styling but lacks progress update logic. We'll use this example to demonstrate how to enable communication between main thread and background thread:

**This is an example below: swiper**

**Entry:** `src/MTSIndicatorEmpty, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorEmpty.lynx.bundle` | Web: `dist/MTSIndicatorEmpty.web.bundle`

```tsx {33}
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



### Main Thread Calling Background Thread

The core of the progress indicator is the `<Indicator>` component, which accepts a `current` prop indicating the current page.

```tsx title="Swiper.tsx" "{7}"
function Swiper() {
  const [current, setCurrent] = useState(0);

  return (
    <view>
      {/* ... */}
      <Indicator current={current} />
    </view>
  );
}
```

Now we just need to update `current` when scrolling.

We add an `onIndexChange` callback to `useOffset` to update `current` during scrolling.

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      onIndexUpdate(index);
    }
  }
}
```

And pass `setCurrent` as the `onIndexUpdate` callback to `useOffset`.

```tsx title="Swiper.tsx" "{4}"
const [current, setCurrent] = useState(0);

const { handleTouchMove } = useOffset({
  onIndexUpdate: setCurrent,
});
```

This way, when scrolling past a page, `useOffset` will call `onIndexUpdate` to update `current`, thereby updating the progress indicator.

But wait, why is there an error?!

![Error](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/tutorial/Swiper/MTSIndicatorWrong.png)

:::info Main Thread and Background Thread Functions Need Special APIs to Call Each Other
Main thread script and background thread script run in separate runtimes. Functions in one runtime cannot directly call functions in another runtime. They need "special bridges" to communicate:

- From background to main thread: Use [`runOnMainThread`](/api/react/Function.runOnMainThread.md)
- From main thread to background: Use [`runOnBackground`](/api/react/Function.runOnBackground.md)

:::

`onIndexUpdate` is a background thread function. When called in a main thread function, we need to use `runOnBackground`

```tsx title="useOffset.ts" "{12}"
function useOffset({
  itemWidth,
  onIndexUpdate,
}) {
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    ...
    const index = Math.round(offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }
}
```

**This is an example below: swiper**

**Entry:** `src/MTSIndicatorCurrent, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicatorCurrent.lynx.bundle` | Web: `dist/MTSIndicatorCurrent.web.bundle`

```tsx
import "./styles.scss";
import { useState } from "@lynx-js/react";
import { Indicator } from "../Components/Indicator/index.jsx";
import { SwiperItem } from "./SwiperItem";
import { useOffset } from "./useOffset";
import { useUpdateSwiperStyle } from "./useUpdateSwiperStyle";

export function Swiper({
  data,
  itemWidth = SystemInfo.pixelWidth / SystemInfo.pixelRatio,
}: {
  data: string[];
  itemWidth?: number;
}) {
  const [current, setCurrent] = useState(0);

  const { containerRef, updateSwiperStyle } = useUpdateSwiperStyle();
  const { handleTouchStart, handleTouchMove, handleTouchEnd } = useOffset({
    onOffsetUpdate: updateSwiperStyle,
    onIndexUpdate: setCurrent,
    itemWidth,
  });

  return (
    <view className="swiper-wrapper">
      <view
        className="swiper-container"
        main-thread:ref={containerRef}
        main-thread:bindtouchstart={handleTouchStart}
        main-thread:bindtouchmove={handleTouchMove}
        main-thread:bindtouchend={handleTouchEnd}
      >
        {data.map((pic) => <SwiperItem pic={pic} itemWidth={itemWidth} />)}
      </view>
      <Indicator total={data.length} current={current} />
    </view>
  );
}

```



Now the progress indicator updates automatically as you scroll!

### Background Thread Calling Main Thread

A useful progress indicator should also support clicking to jump to the corresponding page. Let's add click-to-jump functionality to the `<Indicator>` component.

Add an `updateIndex` method in `useOffset` that uses `runOnMainThread` to call `updateOffset` to update the component position.

```tsx title="useOffset.ts" "{4}"
function useOffset({ itemWidth, onIndexUpdate }) {
  function updateIndex(index: number) {
    const offset = index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  return {
    updateIndex,
  };
}
```

Here's the complete code:

**This is an example below: swiper**

**Entry:** `src/MTSIndicator, src/utils/pics.ts`
**Bundle:** `dist/MTSIndicator.lynx.bundle` | Web: `dist/MTSIndicator.web.bundle`

```ts
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);

  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function updateOffset(offset: number) {
    "main thread";
    currentOffsetRef.current = offset;
    onOffsetUpdate(offset);
    const index = Math.round(-offset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



Great! Now the progress indicator supports click-to-jump functionality.

## Values Across Main Thread and Background Thread Script

In the following example, we've added a snap effect animation to the `<Swiper>` component. Currently, the snap effect animation isn't ideal, we can add some props to customize it.

**This is an example below: swiper**

**Entry:** `src/EasingDefault, src/utils`
**Bundle:** `dist/EasingDefault.lynx.bundle` | Web: `dist/EasingDefault.web.bundle`

```ts {66-73}
import { runOnBackground, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { useAnimate } from "./useAnimate";

export function useOffset({
  onOffsetUpdate,
  onIndexUpdate,
  itemWidth,
  dataLength,
}: {
  onOffsetUpdate: (offset: number) => void;
  onIndexUpdate: (index: number) => void;
  itemWidth: number;
  dataLength: number;
}) {
  const touchStartXRef = useMainThreadRef<number>(0);
  const touchStartCurrentOffsetRef = useMainThreadRef<number>(0);
  const currentOffsetRef = useMainThreadRef<number>(0);
  const currentIndexRef = useMainThreadRef<number>(0);
  const { animate, cancel: cancelAnimate } = useAnimate();
  function updateIndex(index: number) {
    const offset = -index * itemWidth;
    runOnMainThread(updateOffset)(offset);
  }

  function calcNearestPage(offset: number) {
    "main thread";
    const nearestPage = Math.round(offset / itemWidth);
    return nearestPage * itemWidth;
  }

  function updateOffset(offset: number) {
    "main thread";

    const lowerBound = 0;
    const upperBound = -(dataLength - 1) * itemWidth;

    const realOffset = Math.min(lowerBound, Math.max(upperBound, offset));
    currentOffsetRef.current = realOffset;
    onOffsetUpdate(realOffset);
    const index = Math.round(-realOffset / itemWidth);
    if (currentIndexRef.current !== index) {
      currentIndexRef.current = index;
      runOnBackground(onIndexUpdate)(index);
    }
  }

  function handleTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = e.touches[0].clientX;
    touchStartCurrentOffsetRef.current = currentOffsetRef.current;
    cancelAnimate();
  }

  function handleTouchMove(e: MainThread.TouchEvent) {
    "main thread";
    const touchMoveX = e.touches[0].clientX;
    const deltaX = touchMoveX - touchStartXRef.current;
    updateOffset(touchStartCurrentOffsetRef.current + deltaX);
  }

  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    touchStartXRef.current = 0;
    touchStartCurrentOffsetRef.current = 0;
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: (offset) => {
        "main thread";
        updateOffset(offset);
      },
    });
  }

  return {
    handleTouchStart,
    handleTouchMove,
    handleTouchEnd,
    updateIndex,
  };
}

```



We'll use this example to demonstrate value passing between main thread and background thread script.

### Main Thread Script Using Background Thread Script Values

First, we add a `duration` prop to the `<Swiper>` component to control the snap animation duration.

```tsx title="index.tsx"
<Swiper duration={300} />
```

Let's see how it works internally. When touch ends, `useOffset` calls the `animate` function to update the component position with animation effects. `animate` is a main thread function that accepts initial and target values and updates the component position according to the animation curve over the `duration` time.

```tsx title="useOffset.ts" {15-19}
function useOffset({
  duration,
}) {
  const currentOffsetRef = useMainThreadRef<number>(0);

  function updateOffset(offset: number) {
    'main thread'
    // Update Component Offset
  }

  ...
  function handleTouchEnd() {
    'main thread'
    ...
    animate({
      from: currentOffsetRef.current,
      to: calcNearestPage(currentOffsetRef.current),
      onUpdate: updateOffset,
      duration,
    })
  }
}
```

Here, both `animate` and `handleTouchEnd` are main thread functions, and they can access the background thread value `duration`.

:::info Main Thread Functions Can Use Background Thread Values
Main thread script and background thread script run in separate runtimes and are isolated from each other.

However, to simplify main thread script development, Lynx automatically passes background thread values that main thread functions **depend on** to those functions, though this process has some limitations:

- The dependent background thread values must be serializable, so functions, `Promise`s, and other non-serializable values cannot be passed.
- Value passing only occurs during component `render`. If background thread values change after `render`, main thread functions won't be aware of these updates.

:::

### Background Thread Passing Main Thread Values

Next, we add a `main-thread:easing` prop to the `<Swiper>` component to allow users to customize the animation curve.

```tsx title="index.tsx" {6}
function easeInOut(x: number) {
  'main thread';
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
}

<Swiper main-thread:easing={easeInOut} />;
```

Inside the component, the main thread function `easeInOut` is passed to the background thread hook `useOffset`

```tsx title="Swiper.tsx" {2,6}
function Swiper({
  'main-thread:easing': MTEasing,
}) {
  ...
  const { handleTouchStart, ... } = useOffset({
    MTEasing,
  });
}
```

And in `useOffset`, it's passed to the main thread function `animate`.

```tsx title="useOffset.ts" {3,11}
function useOffset({
  duration,
  MTEasing,
}) {
  ...
  function handleTouchEnd(e: MainThread.TouchEvent) {
    "main thread";
    // ...
    animate({
      duration,
      easing: MTEasing,
    });
  }
}
```

:::info Main Thread Values Can Be Passed by Background Thread But Not Used
Main thread values, such as `MainThreadRef` and main thread functions, cannot be directly used by the background thread.

However, they can be passed by the background thread, such as being passed as `props` to components or as function parameters to other hooks or functions, and ultimately used in the main thread.
:::

:::details Add main-thread: Prefix for Props That Need Main Thread Functions
You may have noticed that when passing main thread functions or `MainThreadRef` as attributes, they need the `main-thread:` prefix, like `main-thread:ref` and `main-thread:bindtouchstart`.

By convention, when a prop expects a main thread function, it should have the `main-thread:` prefix, like `main-thread:easing`. We recommend following this convention for custom components too. This helps component users understand that the property requires a main thread function.

However, because variable names containing colons `:` are illegal in JavaScript, you need to rename these props when using them inside components.

```tsx title="Swiper.tsx"
function Swiper({ 'main-thread:easing': MTEasing }) {}
```

:::

Finally, we have a swiper with customizable animation curves.

**This is an example below: swiper**

**Entry:** `src/Swiper, src/utils`
**Bundle:** `dist/Swiper.lynx.bundle` | Web: `dist/Swiper.web.bundle`

```tsx {15}
import { root } from "@lynx-js/react";
import "./styles.scss";
import { Page } from "../Components/Page";
import { picsArr } from "../utils/pics";
import { Swiper } from "./Swiper";

const easing = (x: number) => {
  "main thread";
  return x < 0.5 ? 2 * x * x : 1 - Math.pow(-2 * x + 2, 2) / 2;
};

export default function App() {
  return (
    <Page>
      <Swiper data={picsArr} main-thread:easing={easing} duration={300} />
    </Page>
  );
}

root.render(<App />);

```



## Summary

In this tutorial, we started with a simple `<Swiper>` component, gradually optimized its performance, and finally implemented a swiper with customizable animation curves.

We learned about:

- Using direct node manipulation to optimize performance
- Leveraging main thread script to enhance interaction experience
- Implementing communication between main thread and background thread
- Understanding value passing between main thread and background thread script



---
url: /blog/lynx-3-8.md
---

# Lynx 3.8: WebAssembly on Android, Adaptive Layout, and More

[← All Posts](/next/blog/)May 31, 2026![Mitchell Yue](https://github.com/mitchilling.png)Mitchell YueInfrastructure Lead @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Lynx 3.8 is now officially released!

As outlined in our [2026 roadmap](/blog/lynx-open-source-roadmap-2026.md), Lynx 3.8 kicks off our new monthly release cadence. Moving to monthly means each release will be smaller and more focused. For 3.8, that's **WebAssembly** on Android, `<frame>` auto-sizing, line-aware text fitting, HarmonyOS SessionStorage, `LynxEngine` reuse, and DevTool protocol updates.

Before diving into 3.8, don't miss our recent [lynx-ui](/blog/lynx-ui.md) announcement, where we introduced ready-to-use components for building cross-platform Lynx interfaces.

## WebAssembly on Android

This release introduces initial [WebAssembly](/guide/scripting-runtime/webassembly.md) support on Android via the PrimJS runtime. Lynx apps can now load and execute WebAssembly modules on the background thread, making it possible to move computation-heavy logic into WebAssembly when JavaScript isn't fast enough.

The current implementation focuses on common constructor-based flows:

```js
const module = new WebAssembly.Module(wasmBytes);
const instance = new WebAssembly.Instance(module, imports);

const result = instance.exports.add(1, 2);
```

The complete example below shows the same flow in a Lynx page:

**This is an example below: webassembly**

**Entry:** `src`
**Bundle:** `dist/main.lynx.bundle`

```tsx
import { useCallback, useState } from "@lynx-js/react";

import { addWithWasm } from "./addWasm.js";

import "./App.css";

export function App() {
  const [result, setResult] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);

  const calculate = useCallback(() => {
    "background-only";
    setError(null);

    try {
      setResult(addWithWasm(1, 2));
    } catch (err) {
      setResult(null);
      setError(err instanceof Error ? err.message : "Failed to run WebAssembly");
    }
  }, []);

  return (
    <page>
      <view className="App">
        <view className="Panel">
          <text className="Eyebrow">WebAssembly on Lynx</text>
          <text className="Title">1 + 2</text>
          <text className="Formula">Calculated by a Wasm add function</text>

          <view className="Button" bindtap={calculate}>
            <text className="ButtonText">Run add(1, 2)</text>
          </view>

          <view className="ResultBox">
            <text className="ResultLabel">Result</text>
            <text className="ResultValue">
              {error ?? (result == null ? "Tap to calculate" : String(result))}
            </text>
          </view>
        </view>
      </view>
    </page>
  );
}

```



The current implementation covers `WebAssembly.Module` and `WebAssembly.Instance` fully, plus common-case usage of `WebAssembly.Memory`, `WebAssembly.Table`, and `WebAssembly.Global`.

## Adaptive Layout, Text, and Platform Behavior

This release improves how Lynx content adapts to its host container, fits text into constrained layouts, and closes platform-specific behavior gaps.

### `<frame>` Auto-sizing and Load Metrics

[`<frame>`](/api/elements/built-in/frame.md) can now size itself based on the embedded Lynx page's content with the new `auto-width` and `auto-height` attributes, reducing the need for host-side dimension calculation.

```tsx
<frame src={url} auto-width auto-height />
```

It also improves startup and observability with preset layouts, better `data` and `global-props` passing, intrinsic size reporting through `layoutchange`, and `<frame>` load metrics on Android and iOS.

### Line-aware Auto Font Sizing

The new [`-x-auto-font-size-line-ranges`](/api/css/properties/-x-auto-font-size-line-ranges.md) CSS property lets developers define different font-size search ranges based on the actual number of rendered lines. Use it with `-x-auto-font-size: true`:

```css
.title {
  -x-auto-font-size: true;
  -x-auto-font-size-line-ranges:
    line-range(1, 18px, 22px), line-range(2, 16px, 18px),
    line-range(3 to infinity, 14px);
}
```

This is useful for titles, cards, and feed layouts where one-line, two-line, and multi-line text need different fitting behavior.

**This is an example below: css-api**

**Entry:** `src/-x-auto-font-size-line-ranges`
**Bundle:** `dist/-x-auto-font-size-line-ranges.lynx.bundle`

```scss {20-23}
.page {
  margin: 24px;
  flex-direction: column;
  row-gap: 12px;
  background-color: #f8fafc;
}

.card {
  width: 210px;
  padding: 16px;
  border-radius: 12px;
  background-color: #ffffff;
}

.title {
  width: 180px;
  font-size: 15px;
  color: #1f2937;
  -x-auto-font-size: true;
  -x-auto-font-size-line-ranges:
    line-range(1, 18px, 22px),
    line-range(2, 16px, 18px),
    line-range(3 to infinity, 14px);
}

```



### Desktop Exposure

macOS and Windows now support [`enable-exposure-ui-clip`](/api/elements/built-in/view.md#enable-exposure-ui-clip), giving developers more control over exposure calculations in complex layouts.

## Native Integration

### Lynx Engine Reuse in LynxViewGroup

On Android, `LynxViewGroup` can now cache and reuse a `LynxEngine` across `LynxView` instances created from the same group. This is useful when an application repeatedly creates views from the same template bundle, such as in multi-page or embedded-view scenarios.

We've seen many apps where users leave and re-enter the same Lynx page. In these cases, caching the `LynxEngine` avoids the cost of repeatedly destroying and recreating it, and can reuse work the engine has already done, like the constructed UI tree, so re-entering the page renders faster.

Applications don't need to manage `LynxEngine` directly. Create a group with caching enabled, attach it to each `LynxViewBuilder`, and release it when no longer needed:

```java
ILynxViewGroup group = new LynxViewGroupBuilder()
    .setContext(context)
    .setTemplateBundle(templateBundle)
    .setGlobalProps(globalProps)
    .setEnableCacheEngine(true) // Enable caching.
    .build();

LynxView first = new LynxViewBuilder()
    .setLynxViewGroup(group)
    .build(context);

// Later, another LynxView created from the same group can reuse the cached engine.
LynxView second = new LynxViewBuilder()
    .setLynxViewGroup(group)
    .build(context);

group.release();
```

### Resource Loading Callback

`LynxViewClientV2` adds an `onResourceLoaded` callback so clients can observe resource loading from native code. This gives host applications a single hook for resource timing, success/failure status, and other diagnostics.

### SessionStorage on HarmonyOS

HarmonyOS now supports the SessionStorage API for cross-page data sharing. Front-end code can use the existing [`lynx.setSessionStorageItem`](/api/lynx-api/lynx/lynx-set-session-storage.md), [`lynx.getSessionStorageItem`](/api/lynx-api/lynx/lynx-get-session-storage.md), [`lynx.subscribeSessionStorage`](/api/lynx-api/lynx/lynx-subscribe-session-storage.md), and [`lynx.unsubscribeSessionStorage`](/api/lynx-api/lynx/lynx-unsubscribe-session-storage.md) APIs to share session-scoped state across pages.

## DevTool Protocol and Debugging

DevTool protocol and debugging improvements include:

- MTS debugging now works with pre-executed and pre-decoded `MTSRuntime` instances.
- CDP support adds `DOM.describeNode`.
- `DOM.getDocument` now supports the `depth` parameter.
- DevTool can query `PerformanceEntry` data through the CDP Performance domain.

## Upgrade Guide

To upgrade to Lynx 3.8, follow the [integration guide](https://lynxjs.org/3.8/guide/start/integrate-with-existing-apps.html) and update your Lynx dependency versions accordingly.

## Thank You

Lynx 3.8 is the first step in our monthly release cadence: smaller releases, clearer upgrade paths, and faster feedback loops.

Thanks to everyone building with Lynx, trying new releases early, filing issues, and helping the project improve in the open. See you in the next monthly release.



---
url: /blog/lynx-ui.md
---

# Announcing lynx-ui

[← All Posts](/next/blog/)May 22, 2026![Zhou Fang](https://github.com/fzx2666-fz.png)Zhou FangEngineering @ Lynx![Ryan Wang](https://github.com/f0rdream.png)Ryan WangEngineering @ Lynx![Adrian Luo](https://github.com/AdrianLCA.png)Adrian LuoEngineering @ Lynx![MoonfaceX](https://github.com/MoonfaceX.png)MoonfaceXComponent Lead @ Lynx![Guangyu Du](https://github.com/Dugyu.png)Guangyu DuDesign Engineering @ Lynx![Xuan Huang](https://github.com/huxpro.png)Xuan HuangArchitect @ LynxCopy Markdown
[lynx-ui](https://github.com/lynx-family/lynx-ui) has been quietly open-sourced since we gave an early preview at [React Advanced London](https://reactadvanced.com/) last December. After months of polishing components, building the documentation site, and adding examples, today we are excited to announce it as generally available.

[data-image-wall="image-wall-r0"]{--image-wall-cols:4;--image-wall-gap:8px;--image-wall-aspect-ratio:1;}
@media (min-width:768px){[data-image-wall="image-wall-r0"]{--image-wall-cols:8;--image-wall-gap:8px;--image-wall-aspect-ratio:1;}}
lynx-ui components at a glance

## Native Foundations, Web Velocity

[Built-in elements](/guide/ui/elements-components.md#built-in-elements) and [XElement](/guide/ui/elements-components.md#xelement) give Lynx the low-level capabilities that matter: fast scrolling, precise gestures, and [native rendering](/guide/ui/elements-components.md#behind-the-elements-native-rendering). But products are not built from atoms alone. That is where [components](/guide/ui/elements-components.md#components-composition-of-elements) belong. At Lynx, native provides the foundation; the web-inspired frontend stack provides the extension layer for composition, state, styling, and product-specific behavior.

lynx-ui delivers on this layering principle: **preserve native user experience, deliver the velocity of the web.**

**This is an example below: lynx-ui-scroll-view**

**Bundle:** `dist/ScrollViewBasic.lynx.bundle`

```tsx {17-23}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import { ScrollView } from '@lynx-js/lynx-ui'

import { CircleLetterCard } from './CircleLetterCard'
import './index.css'

const LETTERS = ['L', 'Y', 'N', 'X', 'U', 'I', 'L', 'Y', 'N', 'X', 'J', 'S']

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <ScrollView scrollOrientation='horizontal' className='scroll-view'>
        <view className='scroll-view-content'>
          {LETTERS.map((letter, i) => (
            <CircleLetterCard letter={letter} key={`circle-${i}`} />
          ))}
        </view>
      </ScrollView>
    </view>
  )
}

root.render(<App />)

export default App

```



lynx-ui's [<code>ScrollView</code>](/lynx-ui/components/scroll-view.md) is built
on top of the native [<code>\<scroll-view></code>
](/api/elements/built-in/scroll-view.md) primitive

## Composable Primitives

Encapsulation can become a trap. lynx-ui does not treat components as black boxes with endlessly growing prop surfaces. Instead, it is an [unstyled](/lynx-ui/styling-theming.md) component library where each component is a **primitive** that handles behavior and state, but ships with no visual design. A primitive is composed of **parts** that you render and style independently.

[`Popover`](/lynx-ui/components/popover.md) shows the idea. It is not a single opaque component, but a composition of parts with separate responsibilities: `PopoverRoot` owns state, `PopoverTrigger` defines intent, `PopoverPositioner` handles placement, and `PopoverContent` stays structurally independent.

**This is an example below: lynx-ui-popover**

**Bundle:** `dist/PopoverBasic.lynx.bundle` | Web: `dist/PopoverBasic.web.bundle`

```tsx {20-38}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        defaultShow={true}
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
          <PopoverPositioner
            placement='bottom'
            placementOffset={12}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              <OptionsMenu />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



Composition is all you need.

Because primitives are unstyled, the same composable model creates a foundation for design systems. You can define your own themes through the [styling and theming](/lynx-ui/styling-theming.md) system, or follow the [shadcn/ui](https://ui.shadcn.com/) pattern to compose themed wrappers on top of the primitives.

### LUNA

[LUNA](/lynx-ui/luna-themes-tokens.md) is a reference design language we built on top of that foundation.

It grows from Lynx's signature gradient, adapting the brand expression into a softer palette for UI: warm pinks and rose tones moving into lavender and aqua. In LUNA, gradients act as first-class visual materials for expressing form and movement, giving components a sense of changing mediums. That sensitivity also carries into token names: LUNA describes how surfaces are felt, not where they are placed. `ambient` dissolves into the background, `faint` sits near the threshold of perception, `veil` and `film` create soft translucent layers.


L.U.N.A Studio

## Programmable Interaction

Components built around continuous input need two things at once: highly customizable behavior and low-latency response. A swipe, drag, or snap is judged frame by frame. If the visual response trails behind the gesture, the component may still work, but it no longer feels native.

Lynx's [dual-thread model](/blog/lynx-unlock-native-for-more.md#use-the-main-thread-responsibly-for-interactivity) defaults JavaScript to the background thread, keeping the main thread free for rendering. But [Main-Thread Script](/react/main-thread-script.md) can move interaction logic onto the main thread when it matters, making per-frame behavior fully programmable without crossing a thread boundary. [`Swiper`](/lynx-ui/components/swiper.md) shows the idea directly: drag input feeds transform updates frame by frame, so the card follows the gesture instead of catching up to it later.

**This is an example below: lynx-ui-swiper**

**Bundle:** `dist/SwiperCustomTinder.lynx.bundle` | Web: `dist/SwiperCustomTinder.web.bundle`

```tsx {22-36}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'

import { Card } from './Card'

import './styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
const ITEM_WIDTH = 220
const ITEM_HEIGHT = 330

const customAnimation = (value: number) => {
  'main thread'
  const translateX = interpolate(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolate(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolate(value, [-1, 0], [-15, 0], 'clamp')
  const scale = interpolate(value, [0, 1], [1, 0.95], 'extend')
  const opacity = interpolate(value, [-1, -0.8, 0, 1], [0, 0.9, 1, 1], 'clamp')

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
  }
}

const customAnimationFirstScreen = (value: number, _index: number) => {
  const translateX = interpolateJS(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolateJS(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolateJS(value, [-1, 0], [-15, 0], 'clamp')
  const zIndex = interpolateJS(
    value,
    itemArr.map((_, index) => index),
    itemArr.map((_, index) => (itemArr.length - index) * 10),
    'extend',
  )

  const scale = interpolateJS(
    value,
    [0, 1, 0],
    [1, 0.95, 1],
    'extend',
  )
  const opacity = interpolateJS(
    value,
    [-1, -0.8, 0, 1],
    [0, 0.9, 1, 1],
    'clamp',
  )

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
    zIndex: zIndex,
  }
}

function SwiperEntry() {
  return (
    <view className='demo-container lunaris-dark'>
      <Swiper
        data={itemArr}
        itemWidth={ITEM_WIDTH}
        itemHeight={ITEM_HEIGHT}
        containerWidth={ITEM_WIDTH}
        duration={500}
        initialIndex={0}
        mode='custom'
        main-thread:customAnimation={customAnimation}
        customAnimationFirstScreen={customAnimationFirstScreen}
        style={{
          overflow: 'visible',
        }}
      >
        {({ index }) => (
          <SwiperItem>
            <view
              class='block-view'
              style={{
                width: '100%',
                height: '100%',
                display: 'flex',
                justifyContent: 'center',
                alignItems: 'center',
              }}
            >
              <Card index={index} />
            </view>
          </SwiperItem>
        )}
      </Swiper>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



A <code>'main thread'</code> function passed to{' '}
<code>main-thread:customAnimation</code> runs per-frame logic on the main
thread

With native foundations and programmable interaction in place, motion becomes practical, not just decorative.

### Motion

[Motion](https://motion.dev/) is one of the most popular animation libraries in the Web community, supporting both spring-based and bezier-based transitions. Thanks to the programmability that [Main-Thread Script](/react/main-thread-script.md) brings, we adapted Motion for Lynx as [`@lynx-js/motion`](/lynx-ui/motion.md), a thin layer that reuses Motion's source directly, and ship an experimental version together with lynx-ui. If you know Motion on the web, you already know how to use it in Lynx.

[`Sheet`](/lynx-ui/components/sheet.md) shows why that matters. Drag, resistance, release, and settling need to read as one continuous behavior. With [Main-Thread Script](/react/main-thread-script.md) keeping interaction close to rendering and Motion defining how the surface moves, the sheet feels held, not just played back.

**This is an example below: lynx-ui-sheet**

**Bundle:** `dist/SheetBasic.lynx.bundle`

```tsx {30-43}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'
import './index.css'

const snapPoints = ['50%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Basic Sheet</text>
      <TriggerButton
        onClick={() => sheetRef.current?.open()}
        text='Open Sheet'
      />
      <SheetRoot
        ref={sheetRef}
        snapPoints={snapPoints}
        initialSnap={0}
        onOpen={() => console.log('Sheet opened')}
        onClose={() => console.log('Sheet closed')}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>Basic Sheet</text>
              <text className='info-text'>
                Simple uncontrolled sheet. Drag or tap backdrop to dismiss.
              </text>
              <ActionButton
                onClick={() => sheetRef.current?.close()}
                text='Close'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



<code>Sheet</code> uses <code>@lynx-js/motion</code> under the hood for
spring-driven drag and settle transitions

## Try it today

lynx-ui is available on iOS, Android, and HarmonyOS today, with partial Web and Desktop support on the horizon. Read the [introduction](/lynx-ui/index.md) to get oriented, or jump straight to the [quick start](/lynx-ui/introduction.md#quick-start) to install [`@lynx-js/lynx-ui-*`](https://www.npmjs.com/package/@lynx-js/lynx-ui).

To see the components in action, grab [Lynx Explorer](/guide/start/quick-start.md#prepare-lynx-explorer), scan the QR codes in the [component demos](/lynx-ui/components/button.md), and see them running right away. Or bring it into your own Lynx app and try it in a real product flow.

We want lynx-ui to grow from the way real apps are built. If it feels great, gets in your way, or leaves something missing, let us know in the [lynx-family/lynx-ui repository](https://github.com/lynx-family/lynx-ui). Help shape what comes next.



---
url: /blog/lynx-3-7.md
---

# Lynx 3.7: Desktop Support, SVG, Skills, and ReactLynx Updates

[← All Posts](/next/blog/)April 16, 2026![icecreamx10](https://github.com/icecreamx10.png)icecreamx10Multiplatform Lead @ Lynx![MoonfaceX](https://github.com/MoonfaceX.png)MoonfaceXComponent Lead @ Lynx![upupming](https://github.com/upupming.png)upupmingEngineering @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Lynx 3.7 is now officially released!

This release brings official desktop platform support for **macOS** and **Windows**, introduces the new **SVG** element, introduces new **Agent Skills** for better observability, and updates **ReactLynx** with simpler External Bundle presets and cross-thread shared modules.


## Desktop Support: macOS and Windows

We [previously planned](/blog/lynx-open-source-roadmap-2025.md) to open source desktop support in Lynx 3.5, and [later decided](/blog/lynx-3-5.md#one-more-thing-desktop-support-preview) to go further and open source the full desktop stack. With Lynx 3.7, that vision is now a reality.

Lynx officially supports **macOS** and **Windows** as first-class platforms. You can now build and render Lynx views inside native desktop applications, using the same front-end stack and tooling you already use for mobile and web.
We also plan to open source Lynxtron soon, an Electron-like desktop application framework that uses Lynx as its UI renderer. Stay tuned!

**This is an example below: desktop**

**Entry:** `src/mouse-cursor`
**Bundle:** `dist/mouse-cursor.lynx.bundle` | Web: `dist/mouse-cursor.web.bundle`

```tsx
import { useResponsiveScale } from "../useResponsiveScale";
import desktopFrame from "./assets/desktop-frame.png";
import lynxLogo from "./assets/lynx-logo.png";
import { useDesktopDrag } from "./useDesktopDrag";
import "./App.css";

export function App() {
  const { handleLayoutChange, scale } = useResponsiveScale({
    baseWidth: 980,
    baseHeight: 420,
    minScale: 0.56,
  });
  const {
    desktopHot,
    docked,
    dragging,
    logoCardStyle,
    cancelDrag,
    finishDrag,
    handleDesktopLayout,
    handleLogoDown,
    handleMove,
    handleStageLayout,
  } = useDesktopDrag();
  const desktopFrameClassName = `DesktopFrame ${desktopHot ? "DesktopFrame--hot" : ""} ${
    docked ? "DesktopFrame--occupied" : ""
  }`;
  const logoCardClassName = `LogoCard ${dragging ? "LogoCard--dragging" : ""} ${docked ? "LogoCard--docked" : ""}`;
  const posterStyle = {
    gap: `${18 * scale}px`,
    paddingTop: `${28 * scale}px`,
    paddingBottom: `${24 * scale}px`,
  };
  const headerStyle = {
    gap: `${8 * scale}px`,
    maxWidth: `${760 * scale}px`,
  };
  const titleStyle = {
    fontSize: `${44 * scale}px`,
  };

  return (
    <page
      className="Page"
      bindmousemove={handleMove}
      bindmouseup={finishDrag}
      bindmouseleave={cancelDrag}
      bindlayoutchange={handleLayoutChange}
    >
      <view className="PageBackdrop">
        <view className="PageOrb" />
        <view className="BackdropGlow BackdropGlow--a" />
        <view className="BackdropGlow BackdropGlow--b" />
        <view className="BackdropGlow BackdropGlow--accent" />
      </view>
      <view className="Poster" style={posterStyle}>
        <view className="Header" style={headerStyle}>
          <text className="Title" style={titleStyle}>Bringing Lynx to desktop</text>
        </view>

        <view className="Stage" bindlayoutchange={handleStageLayout}>
          <view className={desktopFrameClassName} bindlayoutchange={handleDesktopLayout}>
            <image src={desktopFrame} className="DesktopFrameImage" />
          </view>

          <view
            className={logoCardClassName}
            style={logoCardStyle}
            bindmousedown={handleLogoDown}
            draggable={false}
          >
            <image src={lynxLogo} className="LogoImage" draggable={false} />
          </view>
        </view>
      </view>
    </page>
  );
}

```



### CSS and Element Coverage on Desktop

The rendering core, which includes the CSS engine, is reused across platforms, so CSS coverage is naturally near-complete. The desktop UI is powered by [**Lynx's own rendering engine**](https://github.com/lynx-family/lynx/tree/develop/clay) rather than native platform widgets, which means primitive elements need to be reimplemented for this custom backend, and coverage is still growing.

**CSS: 97% property coverage.** 311 out of 319 supported Lynx CSS properties are now available on desktop, including:

- **Layout**: Flexbox, Grid, Linear Layout, the full box model, positioning, and relative positioning.
- **Styling**: typography, borders, shadows, gradients, masks, filters, and [CSS custom properties](/api/css/properties/css-variable.md).
- **Animation**: `animation`, `transition`, `@keyframes`, and the full transform stack.

**Elements: 73% attribute coverage.** 179 out of 246 element attributes are already available on desktop, with identical support on macOS and Windows. Most built-in elements work directly on desktop today.

In practice, most Lynx pages built for mobile can already render on desktop with minimal or no front-end changes.

Each API page includes a compatibility overview and a detailed compatibility table. For a cross-API view, the [API Status Dashboard](https://lynxjs.org/api/status) now includes **macOS** and **Windows** columns.

### Desktop-Specific Capabilities

#### [Mouse Events](/api/lynx-api/event/mouse-event.md)

```tsx
<view
  onMouseDown={(e) =>
    console.log(`Button ${e.button} at (${e.clientX}, ${e.clientY})`)
  }
  onMouseMove={(e) => handleHover(e)}
  onMouseLeave={() => resetState()}
/>
```

#### [Keyboard Events](/api/lynx-api/event/key-event.md)

```tsx
<input
  onKeyDown={(e) => console.log(`Key down: ${e.key}`)}
  onKeyUp={(e) => console.log(`Key up: ${e.key}`)}
/>
```

#### [Wheel Events](/api/lynx-api/event/wheel-event.md)

```tsx
<view onWheel={(e) => console.log(`Wheel delta: ${e.deltaX}, ${e.deltaY}`)} />
```

#### [CSS `cursor`](/api/css/properties/cursor.md)

```tsx
<view style={{ cursor: 'pointer' }}>
  <text>Hover me</text>
</view>
```

### Getting Started

For platform-specific integration details, see [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md), which now includes desktop guides alongside Android, iOS, HarmonyOS, and Web.
A playground app built with Lynxtron will also provide a more direct way to fetch and run Lynx examples on desktop.

## `<svg>`: Scalable Vector Graphics

[`<svg>`](/api/elements/built-in/svg.md) is now available as a standalone Lynx element in 3.7, bringing native vector rendering across platforms for icons, charts, and other resolution-independent graphics.

The `<svg>` element supports inline vector content:

**This is an example below: svg**

**Bundle:** `dist/base.lynx.bundle`

```tsx {35}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";

const logoContent = `<svg width="320" height="320" viewBox="0 0 320 320" fill="none" xmlns="http://www.w3.org/2000/svg">
<defs>
  <linearGradient id="panelFill" x1="28" y1="28" x2="292" y2="292" gradientUnits="userSpaceOnUse">
    <stop offset="0%" stop-color="#26292D" stop-opacity="0.72"/>
    <stop offset="55%" stop-color="#4B4F56" stop-opacity="0.62"/>
    <stop offset="100%" stop-color="#8B9098" stop-opacity="0.52"/>
  </linearGradient>
</defs>
<rect x="28" y="28" width="264" height="264" rx="40" fill="url(#panelFill)"/>
<rect x="28.5" y="28.5" width="263" height="263" rx="39.5" stroke="#FFFFFF" stroke-opacity="0.08"/>
<g transform="translate(100 100) scale(6)" opacity="0.98">
  <path fill-rule="evenodd" clip-rule="evenodd" d="M5.19683 4.42475L2.58326 6.22507C2.29923 6.42072 2.10258 6.71472 2.0335 7.04698L1.77798 8.27604C1.76443 8.34121 1.73438 8.40204 1.69058 8.45301L0.504615 10.0077C0.344941 10.1935 0.348791 10.6871 0.786137 11.0031C0.953848 11.1493 1.17807 11.477 1.43312 11.8497L1.43312 11.8497C1.97313 12.639 2.65131 13.6302 3.22376 13.5272C4.03382 13.2426 5.02541 13.1516 5.78673 13.5272C7.2667 14.8049 6.90331 15.983 6.38234 17.672C6.17271 18.3516 5.93755 19.114 5.78673 19.9988C6.49755 17.4117 8.09592 14.4069 10.9781 13.3874C10.4588 12.9632 9.39906 12.5691 8.46129 12.4742C8.46129 12.4742 11.3423 10.0077 14.8957 8.87434C12.4151 2.97197 8.32052 0.151295 8.32052 0.151295C8.11187 -0.10677 7.69054 -0.0221092 7.6036 0.295351C7.53376 1.22845 7.41798 1.86295 7.22685 2.46105L5.78673 0.799291C5.6363 0.61794 5.33557 0.722655 5.33707 0.955861C5.5809 2.31136 5.54668 3.07222 5.19683 4.42475ZM6.21052 4.30085L6.21912 4.3003C6.23794 4.29909 6.25646 4.29664 6.27456 4.29302L6.21052 4.30085ZM8.15541 1.25793C9.1423 2.96321 9.58937 3.932 9.74102 5.73998C8.6912 5.14364 8.23382 4.99187 7.46183 4.99565C7.91215 3.62621 8.04976 2.8016 8.15541 1.25793Z" fill="white"/>
  <path d="M14.4988 13.9228C10.479 14.8427 8.19556 16.2278 6.44922 19.9994C9.58406 14.7399 19.0737 15.6805 19.0737 15.6805C18.8964 14.8214 17.0097 13.183 15.7688 12.1782C15.7688 12.1782 16.7699 10.9474 18.983 10.3244C18.983 10.3244 14.728 10.5709 12.2508 11.9084C13.0533 12.3319 14.0812 13.0467 14.4988 13.9228Z" fill="white"/>
</g>
</svg>`;

const App = () => {
  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        justifyContent: "center",
        alignItems: "center",
        backgroundColor: "#0f0f10",
        padding: "32px",
      }}
    >
      <svg content={logoContent} style={{ width: "320px", height: "320px" }} />
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



You can also load external SVG assets directly:

```tsx
<svg
  style={{ width: '100px', height: '100px' }}
  src="https://example.com/icon.svg"
/>
```

To maximize performance, `<svg>` offloads SVG parsing to a dedicated background thread and renders the entire graphic as a single native view rather than creating individual element nodes. This keeps the main thread lightweight in both parsing time and node count, making it ideal for static display of icons, illustrations, and charts. It supports [17 commonly used SVG tags and over 40 attributes](/api/elements/built-in/svg.md), with consistent rendering behavior across Android, iOS, HarmonyOS, macOS, Windows, and Web.

## Agent Skills

As part of the [Lynx for AI](/ai.md) initiative, six [agent skills](https://github.com/lynx-community/skills) are now open-sourced. Install any skill with:

```bash
npx skills add lynx-community/skills -s <skill-name>
```

| Skill                         | What it does                                                                                 |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| **reactlynx-best-practices**  | Static analysis, auto-fix, and best-practice rules for writing dual-threaded ReactLynx code. |
| **lynx-devtool**              | Inspect DOM, console output, and runtime state of a running Lynx app via CLI.                |
| **lynx-typescript**           | Guidance on TypeScript setup, typing, and event handling in Lynx projects.                   |
| **trace-analysis**            | Analyze `.ptrace` files to identify rendering bottlenecks and performance regressions.       |
| **trace-record**              | Capture Lynx performance traces with system trace and JS profiling support.                  |
| **lynx-debug-info-remapping** | Remap minified main-thread error positions back to original source locations.                |

Together with [Lynx DevTool MCP](/ai/lynx-devtool-mcp.md), coding agents can now inspect running pages, verify interactions, and debug their own changes with tighter feedback loops.

## ReactLynx

### External Bundle Presets

[External Bundle](/rspeedy/external-bundle.md) lets you build a Lynx bundle once and load it from multiple Lynx apps at runtime. Use it when you want to share ReactLynx components or common business bundles across apps. Unlike [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit.md) which splits code within a single app, External Bundle is designed for cross-application reuse.

Lynx 3.7 adds built-in presets via [`defineExternalBundleRslibConfig`](/api/rspeedy/lynx-bundle-rslib-config.md) to simplify setup:

```ts
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineExternalBundleRslibConfig({
  id: 'comp-lib',
  source: {
    entry: {
      './App.js': './external-bundle/CompLib.tsx',
    },
  },
  plugins: [pluginReactLynx()],
  output: {
    externalsPresets: {
      reactlynx: true,
    },
  },
});
```

Then load that bundle in the host app:

**This is an example below: external-bundle**

**Bundle:** `dist/index.lynx.bundle`

```js
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { pluginExternalBundle } from "@lynx-js/external-bundle-rsbuild-plugin";
import { pluginQRCode } from "@lynx-js/qrcode-rsbuild-plugin";
import { pluginReactLynx } from "@lynx-js/react-rsbuild-plugin";
import { defineConfig } from "@lynx-js/rspeedy";

export default defineConfig({
  source: {
    entry: {
      index: "./src/index",
    },
  },
  output: {
    filename: "[name].[platform].bundle",
    assetPrefix: "https://unpkg.com/@lynx-example/external-bundle@latest/dist",
  },
  plugins: [
    pluginReactLynx(),
    pluginQRCode(),
    pluginExternalBundle({
      externalBundleRoot: "dist-external-bundle",
      externalsPresets: {
        reactlynx: true,
      },
      externals: {
        "lodash-es": {
          bundlePath: "lodash-es.lynx.bundle",
          background: { sectionPath: "lodash-es" },
          mainThread: { sectionPath: "lodash-es__main-thread" },
          async: false,
          timeout: 10000,
        },
        "./components": {
          bundlePath: "comp.lynx.bundle",
          background: { sectionPath: "component" },
          mainThread: { sectionPath: "component__main-thread" },
          async: true,
          timeout: 5000,
        },
      },
      timeout: 10000,
    }),
  ],
});

```



### Cross-Thread Shared Modules

By default, main thread functions cannot directly call plain functions that lack the [`'main thread'` directive](/react/main-thread-script.md), making code reuse difficult. [Shared modules](/react/main-thread-script.md#cross-thread-shared-modules) solve this by letting you explicitly declare modules as shareable between threads.

Add `with { runtime: 'shared' }` after an import statement, and the exported functions, classes, and objects in that module become directly callable from main thread functions:

**This is an example below: main-thread**

**Entry:** `src/shared-module`
**Bundle:** `dist/shared-module.lynx.bundle` | Web: `dist/shared-module.web.bundle`

```tsx
import { runOnBackground, useMainThreadRef, useMemo, useState } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { getColorCount, getNextColor } from "./color-utils.js" with { runtime: "shared" };

export function App() {
  // --- Background Thread state ---
  const [count, setCount] = useState(0);
  const currentColor = useMemo(() => getNextColor(count), [count]);

  function incrementCount() {
    setCount((prev) => prev + 1);
  }

  // --- Main Thread function ---
  const boxRef = useMainThreadRef<MainThread.Element & { __colorIdx?: number }>(null);

  const onTap = () => {
    "main thread";
    // Use shared function directly on the Main Thread to get color
    const idx = boxRef.current?.__colorIdx ?? 0;
    const nextIdx = idx + 1;
    const color = getNextColor(nextIdx);

    boxRef.current?.setStyleProperty("background-color", color);
    if (boxRef.current) boxRef.current.__colorIdx = nextIdx;

    // Also update BG state so the text reflects the change
    runOnBackground(incrementCount)();
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        backgroundColor: "white",
      }}
    >
      <view
        main-thread:ref={boxRef}
        main-thread:bindtap={onTap}
        style={{
          width: "200px",
          height: "200px",
          backgroundColor: currentColor,
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          justifyContent: "center",
          borderRadius: "16px",
        }}
      >
        <text style={{ fontSize: "16px", color: "white", fontWeight: "bold" }}>
          Tap to cycle
        </text>
        <text style={{ fontSize: "14px", color: "white", marginTop: "8px" }}>
          Color {(count % getColorCount()) + 1}/{getColorCount()}
        </text>
      </view>
    </view>
  );
}

```



## Upgrade Guide

To upgrade to Lynx 3.7, follow the [integration guide](https://lynxjs.org/3.7/guide/start/integrate-with-existing-apps.html) and update your Lynx dependency versions accordingly.



---
url: /blog/lynx-open-source-roadmap-2026.md
---

# Lynx Roadmap 2026

[← All Posts](/next/blog/)April 13, 2026![Shouqun Liu](https://github.com/lynx-family.png)Shouqun LiuEngineering Manager @ LynxCopy Markdown
[Last year](/blog/lynx-unlock-native-for-more.md), we open-sourced the Lynx framework under TikTok's sponsorship. Since then, we've received valuable feedback from developers and the broader community. We also shared our [2025 roadmap](/blog/lynx-open-source-roadmap-2025.md), focusing on maintaining a consistent release cadence, expanding multi-platform support, and opening more core capabilities.

With the continuous releases from v3.2 to v3.6, Lynx has delivered several important improvements:

- Full support for the Web and [OpenHarmony](/blog/lynx-harmony.md).
- Expanded [lynx-ui](https://github.com/lynx-family/lynx-ui) coverage and improved native API stability.
- A growing ecosystem of community projects such as [miso-lynx](https://github.com/haskell-miso/miso-lynx), [Vue Lynx](https://vue.lynxjs.org/), and more.

At the same time, we recognize that building a great developer framework is a long-term effort, especially in the rapidly evolving AI era. Today, we're excited to share the Lynx open-source roadmap for 2026.

## 1. Faster and More Predictable Release Cadence

Over the past year, Lynx followed a bi-monthly release cycle. With the upcoming v3.7 release wrapping up this cycle, we will move to a monthly release cadence starting in mid-2026.

| Stable Version | 3.8     | 3.9     | 4.0     | 4.1     | 4.2     | 4.3     | 4.4     | 4.5     |
| -------------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- |
| Release Plan   | 2026/05 | 2026/06 | 2026/07 | 2026/08 | 2026/09 | 2026/10 | 2026/11 | 2026/12 |

During development and releases, we will continue improving:

- Release notes and upgrade guides.
- Stability guarantees for core APIs.
- Long-term maintainability across versions.

## 2. Embracing AI

AI is fundamentally reshaping how software is built. We believe that building in the open is essential for a framework to keep pace with AI and become truly AI-native.

This year, we will focus on delivering more stable and well-structured APIs, along with high-quality, LLM-friendly documentation in the [lynx-website](https://github.com/lynx-family/lynx-website), [Agent Skills](https://github.com/lynx-community/skills), tooling, and examples.

We will also explore generative UI with Lynx, as we see this as a key direction for cross-platform frameworks in the AI era. Our goal is to make Lynx one of the most AI-ready cross-platform frameworks.

## 3. Committed Multi-Platform, Including Desktop

Multi-platform support remains a core mission, not only in rendering, but also across capabilities, APIs, and the overall developer experience.

We now have official support for Android, iOS, the Web, and [OpenHarmony](/blog/lynx-harmony.md). We also have an open-source rendering engine, [Clay](https://github.com/lynx-family/lynx/tree/develop/clay), for desktop platforms including macOS and Windows.

This year, we'll continue to improve the production readiness of desktop platforms and deepen integration with industry ecosystems, including Lynxtron (coming soon), which brings Lynx and Electron together for desktop development.

## 4. Production-Ready Infrastructure

Following the open-source release, we received extensive feedback from developers who want ready-made solutions for building cross-platform applications with Lynx quickly.

To address these needs, TikTok has open-sourced [Sparkling](https://github.com/tiktok/Sparkling), which provides application scaffolding and native navigation to help developers get started quickly. We will keep adding more native capabilities, including device APIs.

At the framework level, we will deliver more production-ready UI components through [lynx-ui](https://github.com/lynx-family/lynx-ui), expand animation and CSS capabilities to enable higher-quality UI experiences, and continue to invest in critical features such as Main Thread Scripting and runtime performance improvements across all supported platforms.

On the tooling side, we will release more profiling and diagnostics tools, and enhance [Lynx DevTool](/guide/start/integrate-lynx-devtool.md) to provide a one-stop development and debugging experience.

## 5. Stronger Community Engagement

Cross-platform frameworks represent a long-term, evolving area driven by the open-source community. Lynx itself has been deeply inspired by this ecosystem.

The Lynx toolchain is built on top of [Rspack](https://rspack.rs/), and we already collaborate closely with the Rspack community to deliver high-performance [Rspeedy](/rspeedy/index.md) toolchains. This partnership with the web tooling ecosystem provides a strong foundation for broader engagement.

Looking ahead, we will deepen engagement with the wider web community, including projects such as React, Vue.js, and Motion, and continue improving MiniApps support to make it a fully production-ready solution.

***

**We are hiring!** We welcome you to join us on the Lynx journey. [Click here to explore opportunities](https://joinbytedance.com/search?keyword=Cross+Platform).



---
url: /blog/lynx-3-6.md
---

# Lynx 3.6: Lynx for AI, reactlynx-use, CSS for Design Engineering

[← All Posts](/next/blog/)January 30, 2026![Leron Liu](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![Guangyu Du](https://github.com/Dugyu.png)Guangyu DuDesign Engineering @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Lynx 3.6 is now officially released!

This release introduces Lynx for AI to enhance AI-native development capabilities, introduces `reactlynx-use` for improved developer experience, and enhances CSS capabilities for design expressiveness.

On the native side, Lynx 3.6 improves platform integration with standalone `BackgroundRuntime` and asynchronous `TemplateBundle` creation on HarmonyOS, along with Auto Layout support for LynxView on iOS.

Let's take a closer look at what's new in Lynx 3.6.

## Lynx for AI: `AGENTS.md` and MCPs

AI assistants are quickly becoming part of everyday development. With Lynx 3.6, we’re introducing **Lynx for AI**—a new section on our website at [/ai](/ai.md) to help coding agents understand Lynx, follow best practices, and help you ship.

In this release, we’re shipping [`AGENTS.md`](/ai/agentsmd.md) and two MCP servers as the first building blocks for agent-friendly Lynx projects (Skills coming soon!).

### Lynx Docs MCP

[Lynx Docs MCP](/ai/lynx-docs-mcp.md) connects your coding agent (Gemini, Claude, Cursor, Copilot, etc.) to Lynx documentation via MCP, using [llms.txt](https://lynxjs.org/llms.txt) plus carefully designed prompts so the agent can retrieve the right docs and act on them.

### Lynx DevTool MCP

[Lynx DevTool MCP](/ai/lynx-devtool-mcp.md) helps coding agents connect to devices and inspect/control Lynx pages like DevTools: read elements/console/source code, perform interactions such as clicks and drags, and capture screenshots for multimodal analysis.

## `reactlynx-use`: Hooks for ReactLynx

[`reactlynx-use`](https://lynx-community.github.io/reactlynx-use) is a hooks toolkit for ReactLynx projects.

It combines two sets of hooks: community-proven utilities that follow standard React patterns (such as `useEffectOnce`, `useDebounce`, etc.), built upon the excellent foundation provided by [react-use](https://github.com/streamich/react-use), and Lynx-specific hooks that expose Lynx capabilities and its dual-thread model through a React-friendly API.

Notable Lynx-specific hooks include:

- **useVelocity**: Track the velocity and direction of tap events on the main thread.
- **useTapLock**: Constrain main-thread tap interactions to a specific direction or range.
- **useMainThreadImperativeHandle**: A main-thread counterpart of `useImperativeHandle`.
- **useEventListener**: A flexible event subscription hook supporting `exposure`, `disexposure`, and more.

This keeps everyday logic in familiar hooks, while making it straightforward to tap into Lynx’s main-thread input model and runtime events when you need to.

![reactlynx-use](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/reactlynx-use.jpeg)

## CSS for Design Engineering

From Lynx 3.6 onward, CSS takes on a more explicit role in design engineering and design systems.
As a medium for expressing design intent, CSS describes how decisions are scoped and composed, and how visual structure and perception are formed in the interface.

This release focuses on improving CSS expressiveness through **CSS variables**, **gradients**, and **filters**.

For each capability, we’ve also prepared a polished demo that you can render and interact with on the web.

### Inline CSS Variables for Computable Styling

As of Lynx 3.6, [CSS variables](/api/css/properties/css-variable.md) can be defined and referenced inline. This allows them to be applied directly at component boundaries (where JS-defined parameters are handed off to CSS), without relying on ancestor class switches (such as `theme-light` / `theme-dark`) or imperative JS `setProperty` calls.

It becomes essential when a component's style is user-selected or computed at runtime, since such continuous values cannot be represented by a finite set of predefined classes and would otherwise require imperative style updates.

```tsx
style={{
  '--x': pointer.x,  // normalized parameter from JS
  backgroundColor: 'var(--dot-accent-color)', //defer resolution to component CSS
}}
```

Inline CSS variables provide a direct path for passing design parameters from JS into CSS's inheritance and computation model, so that design intent can be dynamically expressed and resolved while preserving component-level scoping and the declarative styling model.

**This is an example below: design-guide**

**Entry:** `src/force_field`
**Bundle:** `dist/force_field.lynx.bundle` | Web: `dist/force_field.web.bundle`

```tsx
import type { DotFieldProps, DotProps } from "./field.types.js";
import "./field.css";

/**
 * Dot consumes normalized, unitless params.
 * Positioning and sizing are resolved via field-scoped CSS vars.
 */
function Dot({ x = 0, y = 0, s = 1, color, useAccent }: DotProps) {
  return (
    <view
      className="dot"
      /**
       * Inline CSS variables:
       * route accent color to a field-scoped CSS token
       * (`--dot-accent-color`), rather than computing it in JS
       */
      style={`--x:${x}; --y:${y}; --s:${s}; background-color:${useAccent ? "var(--dot-accent-color)" : color}`}
    />
  );
}

/**
 * DotField defines the styling boundary for a dot-based field.
 * Default field-level tokens (e.g. `--field-size`, `--dot-size`) live in CSS;
 * JS only injects token overrides when provided.
 */
function DotField({
  fieldSize,
  dotSize,
  dotColor,
  dotAccentColor,
  style,
  children,
  ...rest // Interaction Handlers
}: DotFieldProps) {
  const styleParts: string[] = [];

  // Token overrides: only write when the caller provides a value.
  if (fieldSize != null) styleParts.push(`--field-size:${fieldSize}px`);
  if (dotSize != null) styleParts.push(`--dot-size:${dotSize}px`);
  if (dotColor) styleParts.push(`--dot-color:${dotColor}`);
  if (dotAccentColor) styleParts.push(`--dot-accent-color:${dotAccentColor}`);

  const mergedStyle = style
    ? `${styleParts.join("; ")}; ${style}`
    : styleParts.join("; ");

  return (
    <view
      style={mergedStyle}
      className="dot-field"
      {...rest}
    >
      {children}
    </view>
  );
}

export { Dot, DotField };

```



### Nested CSS Variables for Token Layering

With Lynx 3.6, [CSS variables](/api/css/properties/css-variable.md) can be defined in terms of other variables, allowing [design tokens](https://m3.material.io/foundations/design-tokens/overview) to be layered and resolved compositionally.

Design tokens capture high-level design decisions, such as colors, typography, spacing, shadows, and glows. Nested CSS variables enable these tokens to flow down into component-level variables and concrete visual styles.

```css
/* Resolve and compose shadow tokens via nested CSS variables. */
.card {
  --blur: 12px;
  --ambient-shadow: 0 0 var(--blur) var(--color);
  box-shadow: var(--ambient-shadow), var(--rim-shadow);
}
```

This is especially important for composite declarations like `box-shadow`. A single `box-shadow` may contain multiple shadow layers, each combining several interacting dimensions such as offset, blur, spread, and color.
With nested CSS variables, shadow layers can now be derived, combined, and adjusted from design tokens, while keeping their structure explicit and traceable in CSS.

**This is an example below: design-guide**

**Entry:** `src/soft_glow`
**Bundle:** `dist/soft_glow.lynx.bundle` | Web: `dist/soft_glow.web.bundle`

```css
/* Semantic shadow tokens are progressively resolved into
 * ambient and rim shadows through nested CSS variables,
 * allowing visual intensity to be adjusted without changing structure.
 */
.card {
  --primary: 254, 105, 161;
  --secondary: 255, 115, 133;
  --accent: 169, 152, 191;

  --color: rgba(var(--secondary), 0.65);
  --rim-color: rgba(var(--primary), 0.9);

  --blur: 3px;
  --spread: 0;
  --rim-blur: 2px;
  --rim-spread: -1px;

  --ambient-shadow: 0 0 var(--blur) var(--spread) var(--color);
  --rim-shadow: 0 0 var(--rim-blur) var(--rim-spread) var(--rim-color);
  border-radius: 24px;
  box-shadow:
    var(--ambient-shadow),
    var(--rim-shadow);
  width: 84px;
  height: 84px;
  background: linear-gradient(
    rgb(var(--accent)),
    rgb(var(--primary))
  );
}

/* Elevation levels adjust shadow parameters
 * while preserving the same compositional structure.
 */
.ele-1 {
  --blur: 3px;
  --spread: 0;
  --rim-blur: 2px;
  --rim-spread: -1px;
}

.ele-2 {
  --blur: 10px;
  --spread: -1px;
  --rim-blur: 6px;
  --rim-spread: -2px;
}

.ele-3 {
  --blur: 24px;
  --spread: -3px;
  --rim-blur: 12px;
  --rim-spread: -4px;
}

.ele-4 {
  --blur: 44px;
  --spread: -5px;
  --rim-blur: 24px;
  --rim-spread: -8px;
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: #0d0d0d;
  gap: 36px;
}

.canvas {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  gap: 24px;
}

```



### Conic Gradients as Design Primitives

Lynx 3.6 adds support for the [`conic-gradient()`](/api/css/data-type/gradient.md) CSS image function. You can use it in CSS properties that accept `<image>` values, such as in `background-image` and `mask-image`, to create continuous angular color transitions directly in CSS.

```css
.bg {
  background-image: conic-gradient(from 30deg, #ff7385, #fe69a1, #00d0f1);
}
```

Conic gradients are a natural fit for angular or cyclic representations, including color wheels and hue pickers. In practice, they’re a lightweight design primitive you can compose into interactive controls and visual tools.

**This is an example below: design-guide**

**Entry:** `src/color_wheels`
**Bundle:** `dist/color_wheels.lynx.bundle` | Web: `dist/color_wheels.web.bundle`

```css
.gradient-disc {
  background-image: conic-gradient(#ff7385, #fe69a1, #a998bf, #00d0f1);
}

.gradient-ring {
  background-image: conic-gradient(#ff7385, #fe69a1, #a998bf, #00d0f1, #ff7385);
}

.gradient-offset {
  background-image: conic-gradient(
    from 36deg at 33% 67%,
    #ff7385,
    #fe69a1,
    #00d0f1
  );
}

.wheel {
  width: 120px;
  height: 120px;
  border-radius: 9999px;
  display: flex;
  justify-content: center;
  align-items: center;

  position: relative;
}

.wheel-hole {
  width: 96px;
  height: 96px;
  border-radius: 9999px;
  background-color: #0d0d0d;
}

.wheel-picker {
  position: absolute;

  width: 16px;
  height: 16px;
  border-radius: 9999px;

  background-color: #ffffff;

  box-shadow:
    0 0 0 2px rgba(255, 255, 255, 0.25),
    0 4px 12px rgba(0, 0, 0, 0.4);

  top: 50%;
  left: 50%;

  /* 
   * Step 1: move picker's center onto the wheel center
   * Step 2: rotate to angle
   * Step 3: translate outwards by radius
   */
  transform: rotate(30deg) translateX(46px);
  transform-origin: 0 0;
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: #0d0d0d;
  gap: 24px;
}

```



### CSS Filters for Shape Formation

Lynx 3.6 extends CSS filter support with `contrast`, `brightness`, and `saturate`.

With these additions, the CSS [`filter`](/api/css/properties/filter.md) property becomes a composable tool for shape formation.
The newly supported `contrast` filter, when combined with the existing `blur` capability, amplifies overlapping regions and allows soft shapes to merge into coherent forms.

Visual structures such as merging, perceptual grouping, and fluid boundaries can be constructed directly in CSS, without relying on bitmap assets or custom rendering pipelines.

**This is an example below: design-guide**

**Entry:** `src/gooey_effect`
**Bundle:** `dist/gooey_effect.lynx.bundle` | Web: `dist/gooey_effect.web.bundle`

```css
/*
 * Gooey Effect (blur + contrast)
 *
 * Visual output depends on each platform’s graphics pipeline:
 * - Web renders a precise, crisp Gaussian blur.
 * - iOS appears softer and more diffused.
 * - Android may exhibit minor geometric artifacts on small surfaces
 *   (e.g. a diamond-shaped silhouette) due to blur and downsampling.
 *
 * Blur is applied at the container level to reduce per-element artifacts.
 */

.stage {
  filter: contrast(5);
  /* Background color must be explicit for contrast-based thresholding */
  background-color: black;
  width: 100%;
  height: 200px;
}

.dots-container {
  /* Apply blur at the group level to reduce per-element blur artifacts on some platforms */
  filter: blur(12px);
  width: 100%;
  height: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
  gap: 4px;
}

.dot {
  /* Keep dots crisp; container-level blur produces the gooey merge */
  width: 54px;
  height: 54px;
  border-radius: 999px;
  background: white;
  animation: blob 2200ms ease-in-out infinite;
}

/* Stagger phases without nth-child */
.g1 {
  animation-delay: 0ms;
}
.g2 {
  animation-delay: -350ms;
}
.g3 {
  animation-delay: -700ms;
}
.g4 {
  animation-delay: -1050ms;
}

@keyframes blob {
  0% {
    transform: translateX(-18px) translateY(0px) scale(1.00);
  }
  25% {
    transform: translateX(7.5px) translateY(-4.5px) scale(1.06);
  }
  50% {
    transform: translateX(21px) translateY(0px) scale(1.00);
  }
  75% {
    transform: translateX(4.5px) translateY(4.5px) scale(0.98);
  }
  100% {
    transform: translateX(-18px) translateY(0px) scale(1.00);
  }
}

/* =========================
 * Layout
 * ========================= */

.design-container {
  min-width: 300px;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  background-color: black;
  gap: 40px;

  padding-left: 0;
  padding-right: 0;
}

```



## Native APIs

### Standalone BackgroundRuntime on HarmonyOS

HarmonyOS now supports standalone [BackgroundRuntime](/api/lynx-native-api/lynx-background-runtime.md), aligning more closely with existing Android and iOS capabilities.

With standalone BackgroundRuntime, developers can run JavaScript tasks independently of rendering, or pre-create background runtimes to reduce LynxView initialization latency.

### Asynchronous TemplateBundle Creation on HarmonyOS

On Android and iOS, [`TemplateBundle.fromTemplate`](/api/lynx-native-api/template-bundle/from-template.md) can be called from any thread. On HarmonyOS, however, ArkTS logic must run on the application's main thread.

To reduce main-thread I/O blocking, Lynx 3.6 introduces asynchronous APIs for creating `TemplateBundle` instances on HarmonyOS:

- [`TemplateBundle.fromTemplateAsync`](/api/lynx-native-api/template-bundle/from-template-async.md)
- [`TemplateBundle.fromTemplateAsyncWithOption`](/api/lynx-native-api/template-bundle/from-template-async-with-option.md)

### AutoLayout Support for LynxView on iOS

On iOS, LynxView now supports Auto Layout via [`[LynxView enableAutoLayout]`](/api/lynx-native-api/lynx-view/enable-auto-layout.md).

When enabled, LynxView can derive layout parameters directly from client-side Auto Layout constraints, eliminating the need to configure layout values manually.

## Upgrade Guide

To upgrade to Lynx 3.6, follow the [integration guide](https://lynxjs.org/3.6/guide/start/integrate-with-existing-apps.html) and update your Lynx dependency versions accordingly.



---
url: /blog/lynx-3-5.md
---

# Lynx 3.5: Main Thread Script, React Compiler, HarmonyOS Improvements

[← All Posts](/next/blog/)November 10, 2025![Leron Liu](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![Xuan Huang](https://github.com/huxpro.png)Xuan HuangArchitect @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Lynx 3.5 is now officially released!

Following our stable bi-monthly release cadence, Lynx 3.5 brings several key improvements. This release adds experimental support for React Compiler, enhances main thread scripts with `stopPropagation` for better event bubbling control, enables immediate interactivity after first-frame rendering, and improves cross-thread communication. We've also expanded HarmonyOS platform support and introduced new features like the `pointer-events` CSS property.

Let's dive in and see what's new!

## React Compiler Experimental
[React Compiler](https://react.dev/learn/react-compiler) optimizes components at compile time, so you don't need to manually add `useMemo`, `useCallback`, or `memo`. You can now use React Compiler in ReactLynx to optimize your app's performance.

[Learn how to enable React Compiler in ReactLynx](/react/react-compiler.md).

## Main Thread Script

### Event Stop Propagation Web Friendly

When an event fires, it [propagates](https://lynxjs.org/3.5/guide/interaction/event-handling/event-propagation) through event bubbling, allowing different parts of your UI to handle it. Previously, Lynx only supported static event bubbling interception via [`catch`-type event handler attributes](https://lynxjs.org/3.5/guide/interaction/event-handling/event-propagation#event-interception), which lacked the flexibility of web standards. With Lynx 3.5, main thread scripts now support [`event.stopPropagation()`](https://lynxjs.org/3.5/api/lynx-api/event/event.html#stoppropagation), giving you runtime control over event bubbling that matches what you'd expect on the web.

```tsx {3}
function handleInnerTap(e: MainThread.TouchEvent) {
  'main thread';
  e.stopPropagation(); // ✋ stop event bubbling
  flash('inner');
}
```

**This is an example below: event**

**Entry:** `src/event_stop_propagation`
**Bundle:** `dist/event_stop_propagation.lynx.bundle` | Web: `dist/event_stop_propagation.web.bundle`

```tsx {34}
import { root, runOnBackground, useState } from "@lynx-js/react";
import "./index.css";
import type { MainThread } from "@lynx-js/types";

export default function App() {
  const [active, setActive] = useState({ outer: false, middle: false, inner: false });

  // Utility to flash a box when it's clicked
  const flashBT = (key: "outer" | "middle" | "inner") => {
    setActive((prev) => ({ ...prev, [key]: true }));
    setTimeout(() => setActive((prev) => ({ ...prev, [key]: false })), 200);
  };

  // Utility to flash a box when it's clicked
  const flash = (
    key: "outer" | "middle" | "inner",
  ) => {
    "main thread";
    runOnBackground(flashBT)(key);
  };

  function handleOuterTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("outer");
  }

  function handleMiddleTap(e: MainThread.TouchEvent) {
    "main thread";
    flash("middle");
  }

  function handleInnerTap(e: MainThread.TouchEvent) {
    "main thread";
    e.stopPropagation(); // ✋ stop event bubbling
    flash("inner");
  }

  return (
    <view
      main-thread:bindtap={handleOuterTap}
      className={`box outer ${active.outer ? "active" : ""}`}
    >
      <text>Outer {active.outer ? "(active)" : "(inactive)"}</text>
      <view
        main-thread:bindtap={handleMiddleTap}
        className={`box middle ${active.middle ? "active" : ""}`}
      >
        <text>Middle {active.middle ? "(active)" : "(inactive)"}</text>
        <view
          main-thread:bindtap={handleInnerTap}
          className={`box inner ${active.inner ? "active" : ""}`}
        >
          <text>Inner (click me, stops propagation) {active.inner ? "(active)" : "(inactive)"}</text>
        </view>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Immediate Interactivity After [First-Frame](https://lynxjs.org/3.5/guide/interaction/ifr.html)

Previously, main thread events had to wait for the background thread to complete [hydration](https://lynxjs.org/3.5/guide/react/lifecycle.html) before responding, creating a frustrating delay where the page looked ready but wasn't interactive, similar to the [uncanny valley effect commonly seen in server-side rendering](https://web.dev/articles/rendering-on-the-web#rehydration).

To eliminate this delay, we optimized the hydration process so that main thread events can respond immediately after the first frame is rendered. After the background thread hydrates, it correctly takes over the state from the main thread and replays [`runOnBackground`](https://lynxjs.org/3.5/api/react/Function.runOnBackground.html) calls, ensuring proper synchronization between threads while achieving immediate interactivity as soon as the first frame is visible.

```tsx {3,6}
function App() {
  const gotoUser = () => {
    'main thread';
    // go to second page
  };
  return (
    <view main-thread:bindtap={gotoUser}>
      <text>goto user</text>
    </view>
  );
}
```

### Cross-Thread Function Calls Now Return Values

Lynx provides [`runOnMainThread`](https://lynxjs.org/3.5/api/react/Function.runOnMainThread#function-runonmainthread) and [`runOnBackground`](https://lynxjs.org/3.5/api/react/Function.runOnBackground.html) for cross-thread function calls. In Lynx 3.5, both APIs now support async return values, making cross-thread communication more flexible and intuitive.

```tsx {13,14}
import { runOnMainThread, useMainThreadRef } from '@lynx-js/react';

function App() {
  const countRef = useMainThreadRef(0);

  const addCount = (value) => {
    'main thread';
    countRef.current += value;
    return countRef.current;
  };

  const increaseMainThreadCount = async () => {
    // await for return value from main thread
    const result = await runOnMainThread(addCount)(1);
    console.log(result);
  };
}
```

## Built-in Animations for `<list>` Updates

The `<list>` element now includes default [update animations](https://lynxjs.org/3.5/api/elements/built-in/list.html#update-animation) out of the box. When you add, remove, or update list items, smooth transitions are applied automatically—no extra code needed.

```tsx
<list update-animation="default"></list>
```

| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_delete.gif) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_update.gif) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_insert.gif) |
| Delete | Update | Insert |


## CSS Property: `pointer-events`
 Web Friendly

Lynx 3.5 adds support for the [`pointer-events`](https://lynxjs.org/3.5/api/css/properties/pointer-events.html) CSS property, giving you control over whether an element can receive touch events.

```css
pointer-events: auto;  // Default value. The element can be the target of touch events.
pointer-events: none;  // The element cannot be the target of touch events.
```

**This is an example below: css-api**

**Entry:** `src/pointer-events`
**Bundle:** `dist/pointer-events.lynx.bundle`

```tsx
import { root, useState } from "@lynx-js/react";
import type { TouchEvent } from "@lynx-js/types";
import "./index.scss";

const PointerEvents = () => {
  const [bgColor, setBgColor] = useState("white");
  const [isShow, setIsShow] = useState(false);

  function handleControlTap(e: TouchEvent) {
    "background-only";
    setIsShow(isShow => !isShow);
  }

  function handleContentTap(e: TouchEvent) {
    "background-only";
    const rndCol = `rgb(${Math.floor(Math.random() * 256)}, ${Math.floor(Math.random() * 256)}, ${
      Math.floor(Math.random() * 256)
    })`;
    setBgColor(rndCol);
  }

  return (
    <view className="container">
      <view className="control" bindtap={handleControlTap}>
        <text style={{ fontSize: "18px" }}>show or close popup</text>
      </view>
      {isShow
        && (
          <view className="popup" style={{ pointerEvents: "none" }}>
            <view className="mask">
              <view
                className="content"
                style={{ backgroundColor: bgColor, pointerEvents: "auto" }}
                bindtap={handleContentTap}
              />
            </view>
          </view>
        )}
    </view>
  );
};

root.render(<PointerEvents />);

```



## HarmonyOS Improvements

### Fetch API

Lynx provides a [Fetch API](https://lynxjs.org/3.5/api/lynx-api/global/fetch) that follows web standards, so it works just like you'd expect. With Lynx 3.5, Fetch API support extends to HarmonyOS, making cross-platform development even easier.

### accessibilityAnnounce

Lynx 3.5 adds [`accessibilityAnnounce()`](https://lynxjs.org/3.5/api/lynx-api/lynx/lynx-accessibility-announce.html) support on HarmonyOS, bringing it in line with Android and iOS. This method lets screen readers announce specific text, helping visually impaired users understand interface changes and action results.

```jsx
lynx.accessibilityAnnounce(
  {
    content: 'hello lynx',
  },
  (res) => {
    console.log('result: ' + JSON.stringify(res));
  },
);
```

### requestResourcePrefetch

The [`requestResourcePrefetch`](https://lynxjs.org/3.5/api/lynx-api/lynx/lynx-request-resource-prefetch.html) API is now available on HarmonyOS, matching Android and iOS support. Use it to prefetch CDN resources like images, videos, and audio files for faster loading.

```js
lynx.requestResourcePrefetch?.(
  {
    data: [
      {
        uri: 'https://demo.org/test.jpg',
        type: 'image',
        params: { priority: 'high', cacheTarget: 'disk' },
      },
    ],
  },
  (res) => {
    console.log(
      'prefetch status of each resource:',
      JSON.stringify(res.details),
    );
  },
);
```

## Upgrade Guide

To upgrade to Lynx 3.5, follow the [integration guide](https://lynxjs.org/3.5/guide/start/integrate-with-existing-apps.html) and update your Lynx dependency versions.

## One More Thing: Desktop Support Preview

We [previously planned](/blog/lynx-open-source-roadmap-2025.md) for Lynx 3.5 to introduce desktop support. At the time, our plan was to open source our custom rendering pipeline and low-level integration APIs for desktop. Since then, we've decided to go further and open source the full desktop stack to give you a more battery-included experience. As a result, we would have to adjust our timeline to early 2026.

To get a preview of where we are heading, and how our approach both learns from and differs from prior arts like
[Electron](https://www.electronjs.org/) and [Qt](https://www.qt.io/), check out the talk **"Bringing Lynx to Desktop and Beyond"** from our Multi-Platform Lead [ZhiXuan Wang](https://x.com/adservc1) at [Ubuntu Summit 2025](https://ubuntu.com/summit):




---
url: /blog/lynx-harmony.md
---

# Announcing Lynx for HarmonyOS

[← All Posts](/next/blog/)September 25, 2025![Qiang Bai](https://github.com/rel-q.png)Qiang BaiSoftware Engineer![Wentao Shi](https://github.com/toretto-wt.png)Wentao ShiRendering Lead @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
![lynx-harmony-background](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/lynx-harmony-background1.png)

As introduced in the [open-sourcing blog](/blog/lynx-unlock-native-for-more.md), Lynx's vision continues to be unlocking native for more platforms and more users. With HarmonyOS now adding new platform and device diversity to the market, we want to enable Lynx developers to reach these users with the same ease they already enjoy on Android, iOS, and Web with Lynx.

Today, we are happy to share that **Lynx now provides public beta support for HarmonyOS**, delivering feature parity in [CSS](/guide/ui/styling.md), [Elements](/api/elements/built-in/view.md), and [APIs](/api/index.md) — along with the same level of native performance and user experience.

## Consistent Rendering for HarmonyOS

In [Tutorial: Product Gallery](/learn/gallery.md) we built a complex page using Lynx. Let's see how Lynx performs on Android vs HarmonyOS. As shown below, it achieves pixel-perfect alignment. This allows Lynx developers to **write once, run everywhere** - one codebase for Android, iOS, Web, and HarmonyOS apps, improving efficiency and maintainability.

Running Lynx on HarmonyOSRunning Lynx on Android
The high consistency of Lynx's CSS and native elements across Android, iOS, and HarmonyOS is attributed to our architectural decision: **Lynx's rendering pipeline is shared and consistent across multiple platforms**. On HarmonyOS, we implement the same set of CSS, animations, and custom component by swapping the paint layer to issue instructions to [ArkUI](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview).

![lynx-harmony-background](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/lynx-harmony-imp.png)

## Native Lynx for HarmonyOS

### Native Painting with ArkUI

Lynx on Harmony uses [ArkUI components](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview) for painting. Lynx with OpenHarmony explored two approaches: [ArkTS](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-ui-development-overview) and [C API](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ndk-build-ui-overview).

![lynx-harmony-ui](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/lynx-harmony-ui.png)

We finally chose C API to directly map Lynx [platform-ui-tree](https://lynxjs.org/guide/spec.html#platform-ui-tree) to HarmonyOS native UI, combining Lynx performance with ArkTS ecosystem benefits.

- **Native UI Rendering**: Using [ArkUI's](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview) [C API](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ndk-build-ui-overview) to convert [element-tree](https://lynxjs.org/guide/spec.html#element-tree) operations directly to native UI calls, eliminating data conversion overhead for better performance in complex UI updates.

- **Custom Native Element**: By utilizing HarmonyOS's [`BuilderNode`](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-user-defined-arktsnode-buildernode) and [`Builder`](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builder) capabilities, developers can dynamically construct ArkTS subtrees and seamlessly embed them into the ArkUI node tree created by Lynx, achieving highly customized component implementations.

### Native Interactions

Lynx designed a complete event system that captures and responds to gestures and events in complex interactions.

Gesture Support
Custom Gesture Control in Hybrid Scenarios
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/base-event.gif) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/complex-event.gif) |


- **Custom HitTest**: Accurately find the nodes responding to events on the Lynx platform-ui-tree, ensuring precise interactions.
- **Gesture Support**: Integrates HarmonyOS gesture like [`tap`](https://lynxjs.org/api/lynx-api/event/touch-event#tap) and [`longpress`](https://lynxjs.org/api/lynx-api/event/touch-event#longpress), ensuring native-like gesture experience on Lynx.
- **Custom Gesture Control in Embedded Scenarios**: Offers a comprehensive set of event APIs, including [`user-interaction-enabled`](https://lynxjs.org/api/elements/built-in/view.html#user-interaction-enabled) and [`block-native-event`](https://lynxjs.org/api/elements/built-in/view.html#block-native-event), empowering Lynx developers to manage event propagation and handling logic for efficient processing of nested scrolling scenarios with native pages.

### Native Extensions

- **Native Element Customization**: Lynx provides rich [built-in elements](https://lynxjs.org/api/elements/built-in/view.html) and supports integration of custom HarmonyOS native elements (via ArkTS), enabling developers to extend UI capabilities for highly customized interfaces while preserving native performance. More details: [Custom Element](/guide/custom-native-component.md#platform=harmony).
- **Native Modules**: Lynx enables developers to call HarmonyOS native APIs from JavaScript, supporting both system services and custom native modules. More detail: [Native Modules](/guide/use-native-modules.md#platform=harmony)。

## Create Your First Lynx on HarmonyOS

Lynx's official website offers [development documentation](/guide/start/integrate-with-existing-apps.md?platform=harmony) and [demo code](https://github.com/lynx-family/integrating-lynx-demo-projects/tree/main/harmony/HarmonyEmptyProject) for developers to get started quickly and efficiently.

1. **Use the Pre-built Lynx Explorer**: For the easiest development setup, follow the [Quick Start](/guide/start/quick-start.md) to install the Lynx Explorer hap package and begin Lynx development.

2. **Local Build of Lynx Explorer**: Developers interested in exploring the Lynx on HarmonyOS source code can also attempt local builds by following the guide [Building Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony).

3. **Integrate with Existing Apps on HarmonyOS**: For developers with existing HarmonyOS application projects seeking to integrate Lynx, the official website provides [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md?platform=harmony).

Welcome to the Lynx community. Let's build outstanding native experiences with Lynx on HarmonyOS!



---
url: /blog/lynx-3-4.md
---

# Lynx 3.4: HarmonyOS Support, Trace and Recorder, Text Input Elements

[← All Posts](/next/blog/)September 3, 2025![Leron Liu](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Lynx 3.4 is now officially released!

In line with the [technical roadmap](/blog/lynx-open-source-roadmap-2025.md) announced earlier this year, we've kept a steady bimonthly release rhythm. We skipped a blog for Lynx 3.3 since it had few user-facing features, but that release set the stage for a packed 3.4 releases, bringing new platform support for HarmonyOS, enabling Windows development, launching new developer tools _Trace_ and _Recorder_, open-sourcing the highly-requested `<input>` and `<textarea>` elements, even more flexible animations, variable fonts, and more!

## New Platform Support

### HarmonyOS Support Public Beta

Lynx now officially supports the [HarmonyOS](https://www.harmonyos.com/en/) platform. Developers can integrate Lynx into their HarmonyOS applications by following our [Integration Guide](/guide/start/integrate-with-existing-apps.md?platform=harmony).
Additionally, we will soon be publishing a dedicated blog that takes a closer look at Lynx on HarmonyOS. Stay tuned.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/background.png)

### Support for Windows Development

- The build tool [Rspeedy](/rspeedy.md) now supports the Windows, enabling developers to develop and build Lynx projects on Windows PCs;

- Developers can successfully compile the Android Lynx Engine and [LynxExplorer](/guide/start/quick-start.md#prepare-lynx-explorer) application in a Windows environment;

Support for the Windows version of Devtool desktop is currently in development and will be released soon.

## New Developer Tools

Lynx 3.4 introduces two developer tools dedicated to improving the developer experience and debugging efficiency.

### Trace

[Trace](/guide/devtool/trace.md) delivers comprehensive, end-to-end insight into your Lynx app’s rendering pipeline. From parsing and construction to layout and rendering, Trace captures and visualizes every stage of your page’s lifecycle. What was once a “black box” is now a transparent, interactive map of your app’s inner workings. Developers can finally observe, understand, and optimize performance at the deepest levels, making it easier than ever to identify bottlenecks and fine-tune for maximum efficiency.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-tool-overview-latest2.png)

### Recorder

[Recorder](/guide/devtool/recorder.md) is your time machine for Lynx apps. It logs every aspect of your app’s runtime behavior—from external resource loading and native module calls (with results), to the complete stream of user interactions. These sessions can be exported and replayed with pixel-perfect accuracy in LynxExplorer, transforming elusive, hard-to-reproduce bugs and tricky asynchronous issues into solvable problems. With Recorder, debugging is as easy as pressing “play,” offering clarity and confidence even in the most complex scenarios.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recorder-concept.png)

## Text Input Elements

In a recent UI capability survey conducted within the Lynx community, `<input>`/`<textarea>` elements emerged as the most highly anticipated core features, garnering over 50% of the vote.

Lynx 3.4 delivers two core text input elements.
We will continue to improve core elements. Developers are welcome to continue voting in the [discussion](https://github.com/lynx-family/lynx/discussions/673) to help shape Lynx's future.

### Single-line [`<input>`](/api/elements/built-in/input.md) Element

**This is an example below: input**

**Bundle:** `dist/autoHeight.lynx.bundle`

```tsx {13-20}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "10px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#12345678", borderRadius: "10px" }}>
        <input
          style={{ width: "100%", color: "blue", fontSize: "30px" }}
          placeholder="search"
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>
      <scroll-view
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "100%",
        }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <text style={{ fontSize: "20px", color: "gray", padding: "10px" }}>
              {`item-${index}${inputContent ? `-${inputContent}` : ""}`}
            </text>
          );
        })}
      </scroll-view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### Multi-line [`<textarea>`](/api/elements/built-in/textarea.md) element

**This is an example below: textarea**

**Bundle:** `dist/base.lynx.bundle` | Web: `dist/base.web.bundle`

```tsx {13-21}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";

const App = () => {
  const [inputContent, setInputContent] = useState("");

  return (
    <view style={{ linearOrientation: "vertical", width: "100%", height: "100%", padding: "20px" }}>
      <view style={{ width: "100%", padding: "10px", backgroundColor: "#87654321", borderRadius: "10px" }}>
        <textarea
          style={{ width: "100%", color: "blue", fontSize: "50px" }}
          placeholder="Title"
          maxlines={2}
          bindinput={(res: any) => {
            console.log(res.detail.value);
            setInputContent(res.detail.value);
          }}
        />
      </view>

      <view
        style={{
          width: "100%",
          padding: "10px",
          marginTop: "20px",
          backgroundColor: "#12345678",
          borderRadius: "10px",
        }}
      >
        {
          <textarea
            style={{ width: "100%", height: "300px", fontSize: "30px" }}
            placeholder="Content"
            bindinput={(res: any) => {
              console.log(res.detail.value);
              setInputContent(res.detail.value);
            }}
          />
        }
      </view>
    </view>
  );
};

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## List Recycle Optimization

Lynx 3.4 optimizes the recycling strategy of the `<list>` element to improve rendering performance.

### Recycle `<list>` Sticky Item

When a `<list-item>` is scrolled out of the `<list>` viewport, the original recycling mechanism would cache the item for reuse. Prior to Lynx 3.4, `<list-item>` elements with the sticky attribute were not recycled. In long lists making heavy use of the sticky feature, this could lead to high memory usage. Lynx 3.4 optimizes this strategy; sticky items are now also recycled after scrolling out of the viewport.
If this change adversely affects your existing scenarios, you can temporarily disable this optimization by setting [`experimental-recycle-sticky-item={false}`](/api/elements/built-in/list.md#experimental-recycle-sticky-item). If you encounter any issues, please provide feedback via an issue.

 
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/not-recycle-sticky-1.gif) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recycle-sticky-1.gif) |
 
| sticky 
`<list-item>`
 in Lynx 3.3 | sticky 
`<list-item>`
 in Lynx 3.4 |
 


### Prevent `<list-item>` from Being Recycled

When a `<list-item>` contains complex components, recycling and re-updating the node incurs significant CPU overhead. Developers can now set `recyclable={false}` to [prevent specific `<list-item>` from being recycled](/api/elements/built-in/list.md#not-recycle-list-item). Once disabled, the item will not be recycled when it slides out of the viewport and won't require re-rendering when it reappears, making it suitable for scenarios demanding rendering performance.

**This is an example below: list**

**Entry:** `src/recyclable`
**Bundle:** `dist/recyclable.lynx.bundle` | Web: `dist/recyclable.web.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import "./index.scss";

const ListContainer = () => {
  return (
    <list
      className="list-container"
      scroll-orientation="vertical"
      list-type="flow"
      span-count={2}
    >
      <list-item
        item-key="list-item-over-flow"
        key="list-item-over-flow"
        style={{
          overflow: "visible",
          height: "40px",
          width: "100%",
        }}
        full-span={true}
        recyclable={false}
      >
        <view
          style={{
            height: "600px",
            backgroundImage: "linear-gradient(to bottom, rgba(255, 255, 0, 0.5), rgb(255, 255, 255, 0))",
          }}
        >
          <text style={{ fontSize: "15px" }}>
            {`The list item with overflow background color and recyclable: false`}
          </text>
        </view>
      </list-item>
      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index + 1}`}
            key={`list-item-${index + 1}`}
            style={{
              height: "160px",
            }}
          >
            <view
              style={{
                border: "1px solid black",
                height: "100%",
              }}
            >
              <text style={{ height: "100%", fontSize: "20px" }}>{`list-item-${index + 1}`}</text>
            </view>
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## More Flexible Animations

### `Element.animate()`

The [`MainThread.Element`](/api/lynx-api/main-thread/main-thread-element.md) now features an animate() method for finely controlling CSS animations on the MTS (Main Thread Scripting), including operations like play, pause, and seeking, enabling more flexible interactive animations.

**This is an example below: animation**

**Entry:** `src/animate_mt`
**Bundle:** `dist/animate_mt.lynx.bundle` | Web: `dist/animate_mt.web.bundle`

```tsx
import { root, useMainThreadRef } from "@lynx-js/react";
import { MainThread } from "@lynx-js/types";

import "./index.scss";

const AnimateAnimationExample = () => {
  return (
    <view style={{ width: "100%", height: "100%" }}>
      <text style={{ textAlign: "center", fontSize: "30px" }}>
        Click To Start Animation
      </text>
      <view
        className="box"
        flatten={false}
        main-thread:bindtap={(event) => {
          "main thread";
          const ani = event.currentTarget.animate(
            [
              {
                transform: "translate(0%, 0%) rotate(0deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(200px, 0%) rotate(90deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(200px, 100%) rotate(180deg)",
                "animation-timing-function": "linear",
              },
              {
                transform: "translate(0%, 100%) rotate(270deg)",
                "animation-timing-function": "cubic-bezier(.91,.03,.94,.11)",
              },
              {
                transform: "translate(0%, 0%) rotate(360deg)",
              },
            ],
            {
              name: "animation-1",
              duration: 5000,
              iterations: Infinity,
              easing: "linear",
            },
          );
        }}
      >
      </view>
    </view>
  );
};
root.render(<AnimateAnimationExample />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



### CSS Variables Triggering Transition

Transition animations can now be triggered by changes in CSS variables, enhancing the flexibility and maintainability of transition animations. In multi-theme designs, developers can associate animation parameters with theme variables. Switching themes only requires modifying the variable values without changing selector logic to complete the theme transition.

**This is an example below: animation**

**Entry:** `src/transition_variable`
**Bundle:** `dist/transition_variable.lynx.bundle` | Web: `dist/transition_variable.web.bundle`

```scss
.button_scene_bright {
  --bg-color: #f2f2f2;
  --color: #000000;
}

.button_scene_dark {
  --bg-color: #343a46;
  --color: #ffffff;
}

.button {
  background-color: var(--bg-color);
  transition: all 0.3s;
  width: 142px;
  height: 48px;
  border-radius: 25px;
  align-items: center;
  justify-content: center;
}

.txt {
  color: var(--color);
  transition: all 0.3s;
  font-size: 16px;
  font-weight: 700;
}

.container {
  width: 100%;
  height: 100%;
  align-items: center;
  justify-content: center;
}

```



## Variable Fonts

Lynx 3.4 adds support for variable fonts. Developers can now perform finer adjustments to font styles using underlying CSS properties like font-variation-settings and font-optical-sizing.
Read the [MDN](https://developer.mozilla.org/zh-CN/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) and [web.dev](https://web.dev/articles/variable-fonts) guides to learn more about variable fonts technology.

**This is an example below: text**

**Entry:** `src/variable_font`
**Bundle:** `dist/variable_font.lynx.bundle` | Web: `dist/variable_font.web.bundle`

```tsx
import { root } from "@lynx-js/react";
import "./index.scss";

const VariableFont = () => {
  const fontSamples = [
    {
      title: "Normal",
      description: "Default font style",
      className: "",
    },
    {
      title: "Variable Weight (wght)",
      description: "font-variation-settings: 'wght' 750",
      className: "font-variation-settings",
    },
    {
      title: "Old-style Figures (onum)",
      description: "font-feature-settings: 'onum'",
      className: "font-feature-settings",
    },
    {
      title: "Combined Usage",
      description: "Applying both 'wght' and 'onum' features",
      className: "font-feature-settings font-variation-settings",
    },
  ];

  return (
    <view
      style={{ padding: "16px", display: "flex", flexDirection: "column", gap: "16px", backgroundColor: "#f4f4f4" }}
    >
      {fontSamples.map((sample, index) => (
        <view key={index} style={{ backgroundColor: "white", padding: "16px", borderRadius: "8px" }}>
          <text style={{ fontSize: "18px", fontWeight: "bold", color: "#333" }}>
            {sample.title}
          </text>
          <text style={{ fontSize: "14px", color: "#666", marginTop: "4px", marginBottom: "12px" }}>
            {sample.description}
          </text>
          <text className={`variable-font-normal ${sample.className}`} style={{ fontSize: "32px" }}>
            1234567890
          </text>
        </view>
      ))}
    </view>
  );
};

root.render(<VariableFont />);

```



## Upgrade Guide

Refer to the official guide on [Integrating Lynx into Existing Apps](/zh/guide/start/integrate-with-existing-apps.md), update the Lynx and LynxService dependency versions to complete the upgrade to Lynx 3.4.



---
url: /blog/lynx-3-2.md
---

# What's new in Lynx 3.2

[← All Posts](/next/blog/)May 14, 2025![Wentao Shi](https://github.com/toretto-wt.png)Wentao ShiRendering Lead @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
![lynx-in-3-2](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-3-2.png)

Today, I'm pleased to share that Lynx 3.2, the first version of Lynx since we [open-sourced](/blog/lynx-unlock-native-for-more.md) it in March 2025, is now stable!

Lynx 3.2 delivers updates across its framework, engine, and tools, including the [ReactLynx testing tools](#reactlynx-testing-library), [`llms.txt` support](#websitellmstxt-support), [new Grid Layout features](#css-grid-layoutminmaxmax-contentfit-content), improvements to [`<list>`](#improvements-tolist) and [`<text>`](#text-can-be-customized-to-select-across-multiple-elements), and more, to bring you more familiar development experience and more capabilities. With over [296 commits](https://github.com/lynx-family/lynx/releases/) from 61 contributors (including some first-time contributors). Let’s explore what’s new!

## ReactLynx Testing Library

[Testing Library](https://testing-library.com/) is a popular way in the JavaScript community to test UI components, and we've adapted it for Lynx. We now introduce a new package [`@lynx-js/react/testing-library/`](/api/reactlynx-testing-library/index.md) to provide testing abstractions such as [`render`](/api/reactlynx-testing-library/Function.render.md). It can also be used with the official [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) to assert the presence and behavior of elements using matchers such as [`toBeInTheDocument`](https://github.com/testing-library/jest-dom?tab=readme-ov-file#tobeinthedocument).

```js
import '@testing-library/jest-dom';
import { expect, it } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

it('renders', () => {
  const Wrapper = ({ children }) => (
    <view data-testid="wrapper">{children}</view>
  );
  const Comp = () => (
    <view data-testid="inner" style="background-color: yellow;" />
  );
  const { container, getByTestId } = render(<Comp />, { wrapper: Wrapper });

  expect(getByTestId('wrapper')).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <view data-testid="wrapper">
      <view data-testid="inner" style="background-color: yellow;"/>
    </view>
  `);
});
```

[Learn more about how to use ReactLynx Testing Library here.](/react/reactlynx-testing-library.md)

## Website: `llms.txt` Support

By upgrading to [Rspress v2](https://v2.rspress.dev/) and taking advantage of the new [LLM plugin](https://x.com/rspack_dev/status/1917844832149725695), the Lynx website is now fully equipped with [https://lynxjs.org/llms.txt](https://lynxjs.org/llms.txt) and [https://lynxjs.org/llms-full.txt](https://lynxjs.org/llms-full.txt) to help with AI understanding and improve your experience vibe-coding with Lynx. For every page you can get the original markdown by replacing the .html extension with .md.

[Learn more about what is `llms.txt`](https://llmstxt.org/).

## CSS Grid Layout: `minmax()`
, `max-content`
, `fit-content`
 Web-friendly

Lynx 3.2 adds three CSS functions `minmax()`, `max-content`, and `fit-content`, to help you better controll grid sizes in the [CSS Grid Layout](/guide/ui/layout/grid-layout.md). You can use them in `grid-template-columns`, `grid-template-rows`, `grid-auto-columns`, and `grid-auto-rows`.

Let's take a look at an example of building a three-column grid with `grid-template-columns: 20% max-content minmax(50px, max-content)`:

- First column: Takes up 20% of the container width
- Second column: Sizes itself to fit its content using `max-content`
- Third column: Uses `minmax(50px, max-content)` to have a minimum width of 50px but can grow to fit content

**This is an example below: css**

**Entry:** `src/grid_layout`
**Bundle:** `dist/grid_layout.lynx.bundle` | Web: `dist/grid_layout.web.bundle`

```tsx {24}
import { root } from "@lynx-js/react";
import { useCallback, useEffect, useState } from "@lynx-js/react";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

import "./index.scss";
const GridComponent = () => {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="Container">
        <view className="GridContainer" style={{ gridTemplateColumns: "20% max-content minmax(50px, max-content)" }}>
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title" style={{ alignSelf: "center" }}>No Wrap</text>
          <text className="Subtitle">min-width:50px, will fit the container</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic" }}>{" src/index.tsx "}</text>
            to see updates!
          </text>
        </view>
      </view>
    </page>
  );
};
root.render(<GridComponent />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Improvements to `<list>`

### Scroll Snapping with `item-snap`

The [**scroll snapping**](/api/elements/built-in/list.md#item-snap) feature has graduated to a stable feature in Lynx 3.2. It provides smooth and easy to use pagination across all platforms, enabling developers to create feeds or carousels with precise scrolling interactions.

**This is an example below: list**

**Entry:** `src/horizontal-snap`
```tsx {26}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { HorizontalView } from "./horizontalView.jsx";
import { VerticalView } from "./verticalView.jsx";

const ListContainer = () => {
  return (
    <view
      style={{
        width: "100%",
        height: "100vh",
        display: "linear",
      }}
    >
      <list
        scroll-orientation="horizontal"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "20vh",
        }}
        item-snap={{ factor: 0, offset: -20 }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <HorizontalView index={index} />
            </list-item>
          );
        })}
      </list>
      <list
        scroll-orientation="vertical"
        list-type="single"
        span-count={1}
        style={{
          width: "100%",
          height: "80vh",
        }}
        item-snap={{ factor: 0, offset: 0 }}
      >
        {Array.from({ length: 50 }).map((item, index) => {
          return (
            <list-item
              item-key={`list-item-${index}`}
              key={`list-item-${index}`}
            >
              <VerticalView index={index} />
            </list-item>
          );
        })}
      </list>
    </view>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



[Learn more about implementing Pagination with `item-snap`.](/api/elements/built-in/list.md#pagination-withitem-snap)

### `z-index`
 Support in `<list-item>`
 Web-friendly

Lynx 3.2 supports [**z-index**](/zh/api/css/properties/z-index.md) on `<list-item>`, allowing for more flexible adjustment of the view hierarchy of list items.

**This is an example below: list**

**Entry:** `src/zIndex`
**Bundle:** `dist/zIndex.lynx.bundle` | Web: `dist/zIndex.web.bundle`

```tsx {23}
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import { ItemView } from "./baseView.jsx";

const ListContainer = () => {
  return (
    <list
      scroll-orientation="vertical"
      list-type="single"
      span-count={1}
      preload-buffer-count={1} // add buffer
      style={{
        width: "100%",
        height: "100vh",
        listMainAxisGap: "5px",
        padding: "10px",
        zIndex: "0",
      }}
    >
      <list-item item-key={`list-item-over-flow`} key={`list-item-list-item-over-flow`} style={{ zIndex: "1" }}>
        <view style={{ width: "100%", height: "20px", backgroundColor: "red" }}>
          <text
            style={{
              fontSize: "16px",
              paddingLeft: "6px",
              paddingTop: "6px",
              height: "40px",
              overflow: "visible",
              background: "blue",
            }}
          >
            {`overflowView:z-index:1`}
          </text>
        </view>
      </list-item>

      {Array.from({ length: 50 }).map((item, index) => {
        return (
          <list-item
            item-key={`list-item-${index}`}
            key={`list-item-${index}`}
          >
            <ItemView index={index} />
          </list-item>
        );
      })}
    </list>
  );
};

root.render(<ListContainer />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## `<text>`
 Can Be Customized to Select Across Multiple Elements Web-friendly

In long article scenarios, with the newly added [`custom-text-selection`](/api/elements/built-in/text.md#custom-text-selection) attribute, you can now [implement customized logic](/api/elements/built-in/text.md#crosstext-selection-and-copying) to select and copy text across text elements, making the text selection experience more similar to the Web.

**This is an example below: text**

**Entry:** `src/cross_text_selection`
**Bundle:** `dist/cross_text_selection.lynx.bundle` | Web: `dist/cross_text_selection.web.bundle`

```tsx {31}
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useEffect } from "@lynx-js/react";
import type { CommonEvent, SelectorQuery, TouchEvent } from "@lynx-js/types";

import "./index.scss";

/**
 * Metadata for each <text> node: position, dimensions, and selection bounds.
 */
interface TextNodeInfo {
  id: string; // Unique identifier for the DOM node
  left: number; // X-coordinate of node's left edge
  top: number; // Y-coordinate of node's top edge
  width: number; // Width of the node's bounding box
  height: number; // Height of the node's bounding box
  startX: number; // Selected region's start X
  startY: number; // Selected region's start Y
  endX: number; // Selected region's end X
  endY: number; // Selected region's end Y
}

// Global storage for node info and selection handlers
let textsInfo: TextNodeInfo[] = [];
let handlers: Array<{ x: number; y: number; radius: number; startX: number; startY: number }> = [];
let startPosition = { x: 0, y: 0 }; // Initial touch point for selection
let isSelecting = false; // Flag: currently dragging a selection handle

const CrossTextSelection = () => {
  // useEffect hook to run code when the component mounts and unmounts
  useEffect(() => {
    console.log("component did mount");
    getTextNodeRect();
    return () => {
      console.log("component will unmount");
    };
  }, []);

  // Handle long press event to start text selection
  const handleLongPress = (e: CommonEvent) => {
    isSelecting = true;
    startPosition.x = e.detail.x;
    startPosition.y = e.detail.y;
    setSelection(e.detail.x, e.detail.y, e.detail.x, e.detail.y);
  };

  // Handle touch start event to check if the touch is on a handler
  const handleTouchStart = (e: TouchEvent) => {
    if (handlers.length === 0) {
      return;
    }
    const { x, y } = e.detail;
    for (const [index, handler] of handlers.entries()) {
      if (Math.pow(handler.x - x, 2) + Math.pow(handler.y - y, 2) < Math.pow(handler.radius, 2)) {
        isSelecting = true;
        const another = handlers[(index + 1) % 2];
        startPosition = { x: another.startX, y: another.startY };
        break;
      }
    }
  };

  // Handle touch move event to update the selection area
  const handleTouchMove = (e: TouchEvent) => {
    if (isSelecting) {
      setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
    }
  };

  // Handle touch end event to finalize the selection
  const handleTouchEnd = (e: TouchEvent) => {
    if (isSelecting) {
      setSelection(startPosition.x, startPosition.y, e.detail.x, e.detail.y);
    }
    isSelecting = false;
  };

  // Handle tap event to clear the selection
  const handleTap = () => {
    if (handlers.length === 0) {
      return;
    }
    setSelection(-1, -1, -1, -1);
  };

  // Asynchronous function to get the bounding rectangles of text nodes
  async function getTextNodeRect() {
    let resArray = await new Promise<SelectorQuery[]>((resolve) => {
      lynx.createSelectorQuery()
        .selectAll("#container text")
        .fields(
          {
            query: true,
            id: true,
          },
          (result) => resolve(result.map(({ query }) => query)),
        )
        .exec();
    });

    Promise.all(
      resArray.map((selectorQuery) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve, reject) => {
          selectorQuery.selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: resolve,
              fail: reject,
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = values.map(({ top, left, width, height, id }) => ({
        id,
        left,
        top,
        width,
        height,
        startX: -1,
        startY: 0,
        endX: width,
        endY: height,
      }));
    });
  }

  // Function to execute text selection on a specific node
  function execSelection(
    node: TextNodeInfo,
    startX: number,
    startY: number,
    endX: number,
    endY: number,
    showStartHandle = true,
    showEndHandle = true,
  ) {
    lynx
      .createSelectorQuery()
      .select(`#${node.id}`)
      .invoke({
        method: "setTextSelection",
        params: {
          startX,
          startY,
          endX,
          endY,
          showStartHandle,
          showEndHandle,
        },
        success(res) {
          if (!res) {
            return;
          }
          const boxes = res.boxes || [];
          const hs = res.handles || [];
          if (Array.isArray(boxes) && boxes.length > 0) {
            node.startX = boxes[0].left;
            node.startY = boxes[0].top + boxes[0].height / 2;
            node.endX = boxes[boxes.length - 1].left + boxes[boxes.length - 1].width;
            node.endY = boxes[boxes.length - 1].top + boxes[boxes.length - 1].height / 2;
          } else {
            node.startX =
              node.startY =
              node.endX =
              node.endY =
                -1;
          }
          showStartHandle && (handlers[0] = { ...hs[0], startX: node.startX, startY: node.startY });
          showEndHandle && (handlers[1] = { ...hs[1], startX: node.endX, startY: node.endY });
        },
      })
      .exec();
    if (startX === -1) {
      node.startX = -1;
      handlers = [];
    }
  }

  // Function to set the text selection based on the start and end coordinates
  function setSelection(x1: number, y1: number, x2: number, y2: number) {
    const [[startX, startY], [endX, endY]] = [
      [x1, y1],
      [x2, y2],
    ].sort((a, b) => {
      if (a[1] === b[1]) {
        return a[0] - b[0];
      }
      return a[1] - b[1];
    });
    const clear: TextNodeInfo[] = [];
    const update: TextNodeInfo[] = [];
    for (const node of textsInfo) {
      if (
        (startY < node.top && node.top + node.height < endY)
        || (node.left <= startX && startX <= node.left + node.width && node.top <= startY
          && startY <= node.top + node.height)
        || (node.left <= endX && endX <= node.left + node.width && node.top <= endY && endY <= node.top + node.height)
      ) {
        update.push(node);
      } else if (node.startX !== -1) {
        clear.push(node);
      }
    }
    if (clear.length > 0 || update.length > 0) {
      for (const node of clear) {
        execSelection(node, -1, -1, -1, -1, false, false);
      }
      const start = update[0];
      const end = update[update.length - 1];
      if (update.length === 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          Math.min(start.width, endX - start.left),
          Math.min(start.height, endY - start.top),
          true,
          true,
        );
      } else if (update.length > 1) {
        execSelection(
          start,
          Math.max(0, startX - start.left),
          Math.max(0, startY - start.top),
          start.width,
          start.height,
          true,
          false,
        );
        for (let i = 1; i < update.length - 1; i++) {
          execSelection(update[i], 0, 0, update[i].width, update[i].height, false, false);
        }
        execSelection(
          end,
          0,
          0,
          Math.min(end.width, endX - end.left),
          Math.min(end.height, endY - end.top),
          false,
          true,
        );
      }
      return true;
    }
    return false;
  }

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view
          id="container"
          style={{ width: "90vw" }}
          className="Container"
          bindlongpress={handleLongPress}
          bindtouchstart={handleTouchStart}
          bindtouchmove={handleTouchMove}
          bindtouchend={handleTouchEnd}
          bindtap={handleTap}
        >
          <text id="0" text-selection={true} custom-text-selection={true} flatten={false} className="Title">
            This is title
          </text>
          <view className="SplitLine" />
          <text id="1" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            1.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="2" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            2.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
          <view className="SplitLine" />
          <text id="3" className="NormalText" text-selection={true} custom-text-selection={true} flatten={false}>
            3.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit,
            dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo.
            Cras eu elementum dui.
          </text>
        </view>
      </view>
    </page>
  );
};

export default CrossTextSelection;

root.render(<CrossTextSelection />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Microtasks Web-friendly

Before Lynx 3.2, Lynx did not support micro-task. The behavior of the following code is inconsistent with that in web browsers. In Lynx 3.2, `Promise` based on microtasks is implemented, and a new API [`lynx.queueMicrotask`](/api/lynx-api/lynx/lynx-queue-microtask.md) is delivered.

```js
setTimeout(() => {
  console.log('this is a timeout, will exec after');
}, 0);

Promise.resolve().then((value) => {
  console.log('this is a Promise, will exec before');
});
```

| Results in Lynx before 3.2                                                                                               | Results in Chrome                                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-test-result.png) | ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/chrome-test-result.png) |

## More `console`
 APIs Web-friendly

Lynx 3.2 further implements most of the [W3C-compliant](https://developer.mozilla.org/en-US/docs/Web/API/console) `console` APIs to provide a more comprehensive debugging experience. See the [API Reference](/api/lynx-api/global/console/assert.md) for more details.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-console.gif)
## Rspeedy: Rslib and Rspack 1.3

Rspeedy [v0.9.0](https://github.com/lynx-family/lynx-stack/discussions/482) is now available, featuring significant improvements in size and performance. In v0.9.0, Rspeedy bundles with [Rslib](https://lib.rsbuild.dev/), reducing installation size by 50%. The upgrade to [Rspack](https://rspack.rs/) [1.3](https://rspack.rs/blog/announcing-1-3) delivers enhanced code splitting, optimized bundle size, and improved memory efficiency. Additional enhancements include new CLI flags and configurations. For more details, refer to the complete full CHANGELOG [`@lynx-js/rspeedy v0.9.0`](https://github.com/lynx-family/lynx-stack/blob/main/packages/rspeedy/core/CHANGELOG.md#090).

To upgrade, run the following command in your Rspeedy project:

```js
npx upgrade-rspeedy@latest
```

## DevTool: Screen Mirroring with Resolution Control

DevTool's screen mirroring feature, located in the left panel, now includes resolution switching capabilities. Users can toggle between High Definition (HD) and Standard Definition (SD) modes. The SD mode is particularly useful for reducing bandwidth consumption during unstable device connections, ensuring smoother screen mirroring performance.

Download the latest DevTool Desktop Application from the [DevTool Release](https://github.com/lynx-family/lynx-devtool/releases/tag/v0.0.2) page to get started.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/devtoolsopt.gif)
## Upgrade to Lynx 3.2

### Android

Please refer to the [integrate-with-existing-apps](/guide/start/integrate-with-existing-apps.md?platform=ios) and update your Lynx and LynxService dependencies.

In your project's `build.gradle` or `build.gradle.kts` file, update the Lynx version as follows:


**build.gradle**

```groovy title=build.gradle {3-6}
dependencies {
    // lynx dependencies
    implementation "org.lynxsdk.lynx:lynx:3.2.0"
    implementation "org.lynxsdk.lynx:lynx-jssdk:3.2.0"
    implementation "org.lynxsdk.lynx:lynx-trace:3.2.0"
    implementation "org.lynxsdk.lynx:primjs:2.12.0"
}
```


**build.gradle.kts**

```groovy title=build.gradle.kts {3-6}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-jssdk:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-trace:3.2.0")
    implementation("org.lynxsdk.lynx:primjs:2.12.0")
}
```


In your project's `build.gradle` or `build.gradle.kts` file, update the LynxService version:


**build.gradle**

```groovy title=build.gradle {8-24}
dependencies {
    // lynx dependencies
    implementation "org.lynxsdk.lynx:lynx:3.2.0"
    implementation "org.lynxsdk.lynx:lynx-jssdk:3.2.0"
    implementation "org.lynxsdk.lynx:lynx-trace:3.2.0"
    implementation "org.lynxsdk.lynx:primjs:2.12.0"

    // integrating image-service
    implementation "org.lynxsdk.lynx:lynx-service-image:3.2.0"

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation "com.facebook.fresco:fresco:2.3.0"
    implementation "com.facebook.fresco:animated-gif:2.3.0"
    implementation "com.facebook.fresco:animated-webp:2.3.0"
    implementation "com.facebook.fresco:webpsupport:2.3.0"
    implementation "com.facebook.fresco:animated-base:2.3.0"

    // integrating log-service
    implementation "org.lynxsdk.lynx:lynx-service-log:3.2.0"

    // integrating http-service
    implementation "org.lynxsdk.lynx:lynx-service-http:3.2.0"

    implementation "com.squareup.okhttp3:okhttp:4.9.0"

}
```


**build.gradle.kts**

```groovy title=build.gradle.kts {8-24}
dependencies {
    // lynx dependencies
    implementation("org.lynxsdk.lynx:lynx:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-jssdk:3.2.0")
    implementation("org.lynxsdk.lynx:lynx-trace:3.2.0")
    implementation("org.lynxsdk.lynx:primjs:2.12.0")

    // integrating image-service
    implementation("org.lynxsdk.lynx:lynx-service-image:3.2.0-")

    // image-service dependencies, if not added, images cannot be loaded; if the host APP needs to use other image libraries, you can customize the image-service and remove this dependency
    implementation("com.facebook.fresco:fresco:2.3.0")
    implementation("com.facebook.fresco:animated-gif:2.3.0")
    implementation("com.facebook.fresco:animated-webp:2.3.0")
    implementation("com.facebook.fresco:webpsupport:2.3.0")
    implementation("com.facebook.fresco:animated-base:2.3.0")

    // integrating log-service
    implementation("org.lynxsdk.lynx:lynx-service-log:3.2.0")

    // integrating http-service
    implementation("org.lynxsdk.lynx:lynx-service-http:3.2.0")

    implementation("com.squareup.okhttp3:okhttp:4.9.0")
}
```


### iOS

In your project's `Podfile` file, update the Lynx version as follows:

```ruby title="Podfile" {1,6-8,10}
source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
pod 'Lynx', '3.2.0', :subspecs => [
'Framework',
]

pod 'PrimJS', '2.12.0', :subspecs => ['quickjs', 'napi']
end
```

In your project's `Podfile` file, update the LynxService version as follows:

```ruby title="Podfile" {8-13,15-17}
source 'https://cdn.cocoapods.org/'
platform :ios, '10.0'
target 'YourTarget' do
  pod 'Lynx', '3.2.0', :subspecs => [
    'Framework',
  ]
  pod 'PrimJS', '2.12.0', :subspecs => ['quickjs', 'napi']
  # integrate image-service, log-service, and http-service
  pod 'LynxService', '3.2.0', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'

end
```

## Final Words

Thanks to Lynx community for making this release possible! As a newly open-source project, we're thrilled about our future and we can’t wait to see the use of Lynx in your apps.

In the future, we will gradually introduce more feature support as our [roadmap](/blog/lynx-open-source-roadmap-2025.md). We'll add new components like `<Input>` and adapt to more platforms such as HarmonyOS and PC.

Please check the [release notes and changelog](https://github.com/lynx-family/lynx/releases/tag/3.2.0), and let’s embark on a new adventure!

***

_Thanks to [Xuan Huang](https://x.com/huxpro), [Ray Zhang](https://x.com/zoolsher), and [Shouqun Liu](https://x.com/liushouqun) for their contributions in creating this blog post._



---
url: /blog/lynx-open-source-roadmap-2025.md
---

# Lynx Roadmap 2025

[← All Posts](/next/blog/)March 19, 2025![Shouqun Liu](https://github.com/lynx-family.png)Shouqun LiuEngineering Manager @ LynxCopy Markdown
[Two weeks ago](/blog/lynx-unlock-native-for-more.md), we launched Lynx as an open-source project and have since gathered valuable insights and feedback from the community. Thank you for engaging with Lynx, even as we take our first steps as a new member of the open-source cross-platform ecosystem. Today, I'm pleased to share the 2025 roadmap of Lynx.

Our core principles in developing the Lynx technology family and building the Lynx tech ecosystem are:

- **Fast and stable releases**: Ensuring rapid version updates while maintaining a stable API with minimal breaking changes.
- **Versatile cross-platform**: Empowering developers with efficient, high-performance solutions across major platforms.
- **Strong community support**: Engaging with developers through [GitHub](https://github.com/orgs/lynx-family), [Discord](https://discord.com/invite/mXk7jqdDXk), StackOverflow, etc.

## Release Schedule

We believe that consistent version releases are crucial for a developer framework to ensure features and refinements reach users effectively. In 2025, we plan to publish 5 stable releases.

| **Stable Release Version** | 3.2     | 3.3     | 3.4     | 3.5     | 3.6     |
| -------------------------- | ------- | ------- | ------- | ------- | ------- |
| **Planned Release Date**   | 2025/04 | 2025/06 | 2025/08 | 2025/10 | 2025/12 |

## Documentation

High-quality documentation and examples are essential for a great developer experience. Our team is committed to publishing and maintaining accurate, up-to-date documentation on our website ([https://lynxjs.org](https://lynxjs.org)).
Additionally, the website's repository is open-sourced ([https://github.com/lynx-family/lynx-website](https://github.com/lynx-family/lynx-website)) and will be maintained transparently. We highly welcome any feedback or contributions to our documentation.

## Multiple Platforms

We are providing a cross-platform framework for building apps across a wide range of platforms. This includes mobile platforms like Android, iOS, and the Web, all of which we have already open-sourced. Additionally, Lynx supports desktop environments such as Windows and macOS, as well as emerging platforms like OpenHarmony. With coverage across those major platforms, we have a clear plan to continue open-sourcing our framework this year.

- Support for Android, iOS, and the Web are already open sourced. We will continue enhancing cross-platform consistency and performance on these platforms to provide developers with better solutions for building mobile applications.
- OpenHarmony: We plan to open source Lynx OpenHarmony support on version 3.4.
- macOS and Windows: We also plan to release Lynx macOS and Windows support to open source on version 3.5.

## More Capabilities & UI Elements

We have received multiple requests for additional APIs and components, as well as feedback on integrating Lynx into various products. To empower developers in building fully fledged applications with Lynx, in addition to the already open-sourced core engine and front-end stack, we plan to open-source more peripherals this year, including:

- Additional UI elements and components, such as input, view pagers, swiper, and SVG support.
- Support for [Canvas](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) and advanced animations, such as [Lottie](https://airbnb.io/lottie/), along with our open-source implementations.
- App-level capabilities, including native navigation and APIs for features like notifications, location, and more.

## Tooling

We also received a lot of feedback about the toolchain's compatibility on Windows and Linux platforms. Moving forward, we'll ensure toolchain support across major development platforms, including macOS, Windows, and Linux.

For developer tools, we will continue improving the capability and stability of DevTools. Later this year, we plan to introduce performance profilers to help developers diagnose and resolve possible performance issues.

## Community

As a family of technologies designed to empower developers, we believe a strong community ecosystem is essential to its success. That's why we have open-sourced our technologies, and will continue building and enhancing the community.

- To advance our vision of democratizing cross-platform technologies, we aim to collaborate with the community to further enhance the [Element PAPI](/guide/spec.md#element-papi), making it more framework-agnostic and better suited to support more frameworks on Lynx engine.
- We are dedicated to actively discussing, responding to, and addressing developers' feedback across all major community platforms, including Discord, GitHub, and StackOverflow.

***

After open-sourcing Lynx, our team has been overwhelmed by the enthusiasm of the community. We've received a wealth of feedback on improving the framework, which has greatly motivated each of us. In the future, we look forward to collaborating with the community and continuously releasing updates to support developers.



---
url: /blog/lynx-unlock-native-for-more.md
---

# Lynx: Unlock Native for More

[← All Posts](/next/blog/)March 5, 2025![Xuan Huang](https://github.com/huxpro.png)Xuan HuangArchitect @ Lynx![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.orgCopy Markdown
Today, we're excited to introduce **Lynx**, a _family_ of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase. Designed for diverse use cases and rich interactivity, Lynx delivers vibrant and engaging UIs for large-scale apps like TikTok, featuring a speedy, versatile rendering engine, performance-driven dual-threaded UI programming, modern Rust-based tooling, and more!

We deeply appreciate all the prior arts that have shaped the field of cross-platform development, and aspire to contribute to this movement by **open sourcing** Lynx today, inviting more developers to build applications with more freedom and productivity.

## Ship Native at Scale and Velocity

For the generation of digital natives, mobile phones—and the apps on them—are their first digital experiences. For these app-centric users, a non-native experience isn't just inconvenient; it's a red flag. A blank screen, a 0.1s lag in a "like" animation, or an unfamiliar UI pattern can make an interface feel "cheap" or untrustworthy. We believe that native primitives and responsiveness aren't just nice-to-haves—**_native is a necessity_**.

Despite the rapid growth of the app economy, delivering such experiences at _scale_ and _velocity_ remains to be a challenge. The growing diversity of form factors and platforms forces developers to rebuild the same experiences multiple times, leading to wasted effort, siloed teams, and delayed time-to-market. We believe that by enabling developers to build once and reach more platforms, _we can deliver joys **for more users, faster**_.

TikTok, known and loved as a mobile-first platform, continuously brings innovative and engaging experiences to diverse and dynamic users around the world. To meet these demands, it gradually adopted Lynx and has increasingly bet on it. Today, Lynx powers an extremely wide spectrum of surfaces—from the lightweight, high-frequency **Search** panel to full-fledged [TikTok Studio](https://support.tiktok.com/en/using-tiktok/creating-videos/tiktok-studio) app; from complex e-commerce storefronts like **Shop** that demand reliability and trust, to highly engaging experiences like **LIVE**, as well as powering high-profile events and cultural moments such as [Disney100 on TikTok](https://newsroom.tiktok.com/en-us/disney-100) and [The Met Gala on TikTok](https://newsroom.tiktok.com/en-us/tiktok-goes-to-the-met-gala).

![lynx-in-tiktok](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-in-tiktok.jpg)

TikTok's extensive use of Lynx

We believe _scale_ and _velocity_ mean more than just applying a feature, bug fix, or optimization across all platforms to improve cost efficiency. It also means the _versatility_ to adapt the same shared technological foundation to a broad spectrum of scenarios—without the need to build new teams or reinvent the wheel for every unique use case.

## Inspire and Enrich the Web community

The web platform was historically created for [documents](https://www.w3.org/People/Berners-Lee/WorldWideWeb.html) and then [gradually](https://extensiblewebmanifesto.org/#signatories) [evolved](https://infrequently.org/2015/06/progressive-apps-escaping-tabs-without-losing-our-soul/) into a development platform. Yet, it continues to [face constraints](https://infrequently.org/2020/06/platform-adjacency-theory/) that slow down its ability to adapt and innovate quickly. Therefore, shaping the web technologies for cross-platform development has become a defining norm in the industry. Since 2008, PhoneGap (later [Cordova](https://cordova.apache.org/)) [strived to keep the Web as cross-platform solution](https://web.archive.org/web/20161210233245/http://phonegap.com/blog/2012/05/09/phonegap-beliefs-goals-and-philosophy/) by augmenting Webview with native capabilities. In 2015, [React Native pioneered bridging native UI with web technologies](https://reactnative.dev/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile), enabling declarative UI with React.js on mobile. That same year, [Flutter](https://developers.googleblog.com/en/flutter-10-googles-portable-ui-toolkit/), with its web heritage, adopted a similar declarative UI model and introduced a new approach using a custom rendering engine.

Lynx followed a similar spirit—you can think of it as an **_"alternative Web tailored for app development_"**. It aims to honor the assets of web technologies while taking an opinionated approach, supporting web-like APIs and adding constraints and extensions with clear intent.

To illustrate this balance, let me share two examples: one where we choose to follow the web and another where we intentionally make a difference.

### Craft Designs with Markups and CSS as Usual

At its core, UI technologies exist to deliver exceptional product design. Lynx embraces the familiarity of web development, allowing developers to write markup and CSS just as they would for the web. Lynx natively supports [CSS animations and transitions](/guide/styling/animation.md), [CSS selectors and variables for theming](/guide/styling/custom-theming.md), and modern CSS visual effects like [gradients](/guide/styling/appearance.md#gradient), [clipping, and masking](/guide/styling/appearance.md#clipping-and-masking)—all designed to unlock the creativity of the web community to achieve trending _design engineering_.

**This is an example below: css**

**Entry:** `src/mask_image_circle_gradient`
**Bundle:** `dist/mask_image_circle_gradient.lynx.bundle` | Web: `dist/mask_image_circle_gradient.web.bundle`

```tsx {14}
import { root } from "@lynx-js/react";

function App() {
  return (
    <view
      style={{
        marginTop: "50%",
        transform: "translate(-50%, -50%)",
        marginLeft: "50%",
        width: "150px",
        height: "150px",
      }}
    >
      <view
        style={{
          flexDirection: "column",
          background: "radial-gradient(circle at top left, rgb(255,53,26), rgb(0,235,235))",
          width: "100%",
          height: "100%",
          maskImage: "radial-gradient(circle 75px, black 75%, transparent)",
          position: "absolute",
        }}
      >
        <text
          style={{
            fontSize: "32px",
            fontWeight: "bold",
            alignSelf: "center",
            color: "white",
            marginTop: "50%",
            transform: "translateY(-50%)",
          }}
        >
          LYNX
        </text>
      </view>
    </view>
  );
}

root.render(<App />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



Using <code>mask-image</code> to create a circle area with fading edge

### Use the Main Thread Responsibly for Interactivity

One of Lynx's most notable architectural decisions is its **statically-enforced division** of user scripting into two distinct runtimes: a _[main-thread](/guide/spec.md#main-thread-or-lynx-main-thread) runtime_, powered by [**PrimJS**](https://github.com/lynx-family/primjs), a custom JavaScript engine specifically optimized for Lynx, dedicated to privileged, synchronous UI tasks like initial launch and high-priority event handling, and a _[background](/guide/spec.md#background-thread-aka-off-main-thread) runtime_ as the default for user code, ensuring the main thread remains low workload and _non-blocking_. This enables two killer features of Lynx:

1. [_Instant First-Frame Rendering (IFR)_](/guide/interaction/ifr.md): Backed by [usability research](https://www.nngroup.com/articles/response-times-3-important-limits/), if rendering is fast enough—and Lynx is—no special intermediate feedback is needed. By briefly blocking the main thread until the first frame is fully rendered, Lynx eliminates blank screens, creating a perceived instant experience.

2. [_Main-Thread Scripting (MTS)_](/react/main-thread-script.md): A small, statically scheduled piece of code, privileged to run on the main thread, handles high-priority events and gestures—making it ideal for implementing silky-smooth, highly responsive interfaces that feels native.

IFRMTS
Do you notice how instant the _IFR_ feels and how snappy the _MTS_ is?
Let's **slow them down by 4x** so we can take a closer look!

IFR (0.25x)MTS (0.25x)
Internally, we've seen surfaces migrating from Web to Lynx often achieve a **2–4× reduction in launch times** across the board. Our in-house benchmarks also show that Lynx consistently launches faster on Android while remaining competitive with similar technologies on iOS.

## Open Sourcing Lynx

Lynx was originally developed by an engineering team of ByteDance, which continue to drive its development. As a significant user of Lynx, TikTok recognizes the innovation and potential of Lynx and has been making extensive use of it in a series of TikTok applications. TikTok will facilitate the open-source release of Lynx, offering support in several areas, including funding, technical enhancement, community promotion, and ecosystem growth.

### Democratize Cross-Platform Technologies

For years, cross-platform development for web developers has been defined by the patterns and solutions established by a few dominant players. While we celebrate their remarkable contribution, there is a growing demand for greater diversity in approaches. Lynx seeks to change that by not open-sourcing a single fixed solution, but a **_meta-infrastructure_** that enables teams and businesses facing similar scale and velocity challenges to build their own cross-platform solutions.

We are open-sourcing [**ReactLynx**](/react/index.md) ("React on Lynx") as Lynx's initial frontend framework flavor, enabling componentized, declarative UI on Lynx. _However, Lynx isn't limited to React_. In fact, other frameworks already represent roughly half of Lynx's overall usage, demonstrating its neutrality in hosting different flavors. As modern apps grow increasingly complex, with dozens or even hundreds of developers collaborating on a single app, Lynx ships with [**Rspeedy**](/rspeedy/index.md), a toolchain based on the popular Rust-based bundler [Rspack](https://rspack.rs/), to enable fast builds and pave the way for a multi-framework [micro-frontend](https://en.wikipedia.org/wiki/Micro_frontend) future via [Module Federation](https://module-federation.io/). We are eager to work with the open-source JavaScript framework community to bring even greater diversity to cross-platform development.

Not only is [the core engine](https://github.com/lynx-family/lynx) of Lynx framework-agnostic, but it's also agnostic to host platforms and rendering backends. Drawing inspiration from a spectrum of projects like [Chromium](https://www.chromium.org/chromium-projects/), [Flutter](https://github.com/flutter), and [React Native](https://github.com/facebook/react-native), it's designed to adapt to new platform primitives, and it's flexible enough to switch to a _custom renderer_, enabling pixel-perfect, consistent rendering across any platforms with a graphics interface. With [**Lynx for Web**](https://github.com/lynx-family/lynx-stack/tree/main/packages/web-platform), Lynx can even run natively within web browsers. Together, they give Lynx ultimate flexibilities in how it can expand to even more platforms, such as Desktop, TV, or IoT devices.

### This Is Not the End, But a New Beginning

Lynx is _production-ready_ and already powers an incredible number of businesses. What we are open-sourcing today is the exact version we use in production, which is why it starts at version 3.x. It even includes legacy code and APIs we intend to deprecate, but we believe in opening source what we actually rely on. In fact, **we are moving all development to** **GitHub**, making it open and transparent to the community.

This release marks only the beginning. What we are open sourcing today is _not_ everything. Many peripherals that we're proud of—including additional UI components, advanced built-in graphics capabilities, the custom renderer, and other frameworks—are yet to come.

More importantly, this is the beginning of the journey because, as a relatively young team in the open-source space, we know we have much to learn about working, collaborating, and growing with the community. But we are glad we took this step, because we believe open source is the right path forward—**to foster collaboration, push the boundaries of what's possible in cross-platform development, and give back to the community that has given us so much**. We invite you to join us on this exciting journey and welcome your feedback and contributions.

_What will you build with Lynx?_

![lynx-unlock-native-for-more](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-unlock-native-for-more.png)



---
url: /blog/index.md
---

# Blog

Release notes and official announcements from the Lynx team. Follow [@lynxjs_org](https://x.com/lynxjs_org) to stay up to date.

[May 31, 2026Lynx 3.8: WebAssembly on Android, Adaptive Layout, and MoreLynx 3.8 starts the monthly release cadence with WebAssembly on Android, adaptive layout and text fitting, HarmonyOS SessionStorage, LynxEngine reuse, and DevTool protocol support.

![](https://github.com/mitchilling.png)![](https://github.com/lynx-family.png)Mitchell Yue, The Lynx Team](/next/blog/lynx-3-8)[May 22, 2026Announcing lynx-uiAnnouncing lynx-ui, a set of ready-to-use components that preserve native user experience while delivering the velocity of the web. With LUNA design language, Motion integration, and support for iOS, Android, and HarmonyOS.

![](https://github.com/fzx2666-fz.png)![](https://github.com/f0rdream.png)![](https://github.com/AdrianLCA.png)![](https://github.com/MoonfaceX.png)![](https://github.com/Dugyu.png)![](https://github.com/huxpro.png)Zhou Fang, Ryan Wang, Adrian Luo, MoonfaceX, Guangyu Du, Xuan Huang](/next/blog/lynx-ui)[April 16, 2026Lynx 3.7: Desktop Support, SVG, Skills, and ReactLynx UpdatesLynx 3.7 is now officially released! This release brings official desktop platform support for macOS and Windows, introduces the new SVG element, introduces new agent skills for better observability, and updates ReactLynx with simpler External Bundle presets and shared runtime modules.

![](https://github.com/icecreamx10.png)![](https://github.com/MoonfaceX.png)![](https://github.com/upupming.png)![](https://github.com/lynx-family.png)icecreamx10, MoonfaceX, upupming, The Lynx Team](/next/blog/lynx-3-7)[April 13, 2026Lynx Roadmap 2026Lynx is moving to a faster release cadence in 2026, investing in AI-ready docs and tooling, improving desktop readiness, strengthening production infrastructure, and deepening collaboration with the open-source community.

![](https://github.com/lynx-family.png)Shouqun Liu](/next/blog/lynx-open-source-roadmap-2026)[January 30, 2026Lynx 3.6: Lynx for AI, reactlynx-use, CSS for Design EngineeringLynx 3.6 is now officially released! This release introduces Lynx for AI to enhance AI-native development capabilities, introduces reactlynx-use for improved developer experience, and enhances CSS capabilities for design expressiveness. On the native side, Lynx 3.6 improves platform integration with standalone BackgroundRuntime and asynchronous TemplateBundle creation on HarmonyOS, along with Auto Layout support for LynxView on iOS.

![](https://github.com/loongliu.png)![](https://github.com/Dugyu.png)![](https://github.com/lynx-family.png)Leron Liu, Guangyu Du, The Lynx Team](/next/blog/lynx-3-6)[November 10, 2025Lynx 3.5: Main Thread Script, React Compiler, HarmonyOS Improvements

![](https://github.com/loongliu.png)![](https://github.com/huxpro.png)![](https://github.com/lynx-family.png)Leron Liu, Xuan Huang, The Lynx Team](/next/blog/lynx-3-5)[September 25, 2025Announcing Lynx for HarmonyOSToday, we are happy to share that Lynx now provides public beta support for HarmonyOS, delivering feature parity in CSS, Elements, and APIs — along with the same level of native performance and user experience.

![](https://github.com/rel-q.png)![](https://github.com/toretto-wt.png)![](https://github.com/lynx-family.png)Qiang Bai, Wentao Shi, The Lynx Team](/next/blog/lynx-harmony)[September 3, 2025Lynx 3.4: HarmonyOS Support, Trace and Recorder, Text Input Elements

![](https://github.com/loongliu.png)![](https://github.com/lynx-family.png)Leron Liu, The Lynx Team](/next/blog/lynx-3-4)[May 14, 2025What's new in Lynx 3.2

![](https://github.com/toretto-wt.png)![](https://github.com/lynx-family.png)Wentao Shi, The Lynx Team](/next/blog/lynx-3-2)[March 19, 2025Lynx Roadmap 2025Two weeks ago, we launched Lynx as an open-source project and have since gathered valuable insights and feedback from the community. Thank you for engaging with Lynx, even as we take our first steps as a new member of the open-source cross-platform ecosystem. Today, I'm pleased to share the 2025 roadmap of Lynx.

![](https://github.com/lynx-family.png)Shouqun Liu](/next/blog/lynx-open-source-roadmap-2025)[March 5, 2025Lynx: Unlock Native for MoreToday, we're excited to introduce Lynx, a family of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase...

![](https://github.com/huxpro.png)![](https://github.com/lynx-family.png)Xuan Huang, The Lynx Team](/next/blog/lynx-unlock-native-for-more)


---
url: /api-desktop-spec-cleanup.md
---

# Native API Desktop Documentation Cleanup Ledger

This document records Native API alignment issues between compat desktop support and MDX Desktop-specific documentation. Do not remove entries while cleaning; mark resolved entries in place so the cleanup history remains reviewable.

## Cleanup Rules

- Source code reference: `https://github.com/lynx-family/lynx/tree/develop/platform/embedder/public`.
- The source code reference is useful when verifying API ownership, but it is not the primary scan criterion for this ledger.
- Primary check: compat data says whether Desktop is supported; the corresponding MDX page should have Desktop-specific documentation when Desktop is supported.
- Scope is Native API only: `docs/{en,zh}/api/lynx-native-api` and `packages/lynx-compat-data/lynx-native-api`.
- Out of scope: `css/*`, `elements/*`, `lynx-api/*`, `lynx-devtool-native-api/*`, framework/tooling/testing/engine/error docs.
- Desktop compat platforms: `clay_macos` and `clay_windows`.
- Desktop support rule: `version_added` is not `false`, `null`, or absent for at least one desktop platform.
- Desktop MDX supplement rule: the corresponding MDX contains Desktop-specific content such as `### Desktop (C++)`, `<Tab label="Desktop C++">`, `Desktop-only`, or Desktop public API wording.
- When an item is cleaned, change the line from `- [ ] ...` to `- [x] ~~...~~` and append a short note if useful, for example `-- added Desktop section`, `-- corrected desktop support`, or `-- not Native API`.
- Keep the original scan entry text readable inside the strikethrough; do not delete completed entries.

## Case Examples

These examples show the shape of each cleanup case. The real cleanup checklist starts in the sections below.

### Compat Desktop Supported But MDX Desktop Docs Missing

Example item:

```md
- [ ] feature: `lynx-native-api.lynx-view.add-lynx-view-client` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/add-lynx-view-client.json` | query: `lynx-native-api/lynx-view/add-lynx-view-client` | desktop: clay_macos=3.7, clay_windows=3.7 | mdx_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx, docs/zh/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx | desc: register lifecycle observer for lynxView
```

Example after cleanup:

```md
- [x] ~~feature: `lynx-native-api.lynx-view.add-lynx-view-client` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/add-lynx-view-client.json` | query: `lynx-native-api/lynx-view/add-lynx-view-client` | desktop: clay_macos=3.7, clay_windows=3.7 | mdx_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx, docs/zh/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx | desc: register lifecycle observer for lynxView~~ -- added Desktop section
```

### Compat Desktop Supported But Only Some MDX Locales Have Desktop Docs

No items were found in this scan. If one appears in a later scan, it should look like this:

```md
- [ ] feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=3.7, clay_windows=3.7 | mdx_desktop: en=yes, zh=no | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=20, docs/zh/api/lynx-native-api/example.mdx
```

Example after cleanup:

```md
- [x] ~~feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=3.7, clay_windows=3.7 | mdx_desktop: en=yes, zh=no | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=20, docs/zh/api/lynx-native-api/example.mdx~~ -- added zh Desktop section
```

### MDX Desktop Docs Present But Compat Has No Desktop Support

No items were found in this scan. If one appears in a later scan, it should look like this:

```md
- [ ] feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=false, clay_windows=false | mdx_desktop: en=yes, zh=yes | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=30, docs/zh/api/lynx-native-api/example.mdx desktop_line=30
```

Example after cleanup:

```md
- [x] ~~feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=false, clay_windows=false | mdx_desktop: en=yes, zh=yes | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=30, docs/zh/api/lynx-native-api/example.mdx desktop_line=30~~ -- corrected desktop support or removed Desktop docs
```

### MDX Desktop Docs Present But Compat Desktop Support Is Partial

No items were found in this scan. If one appears in a later scan, it should look like this:

```md
- [ ] feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=3.7, clay_windows=false | mdx_desktop: en=yes, zh=yes | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=30, docs/zh/api/lynx-native-api/example.mdx desktop_line=30
```

Example after cleanup:

```md
- [x] ~~feature: `lynx-native-api.example` | compat: `packages/lynx-compat-data/lynx-native-api/example.json` | query: `lynx-native-api/example` | desktop: clay_macos=3.7, clay_windows=false | mdx_desktop: en=yes, zh=yes | docs: docs/en/api/lynx-native-api/example.mdx desktop_line=30, docs/zh/api/lynx-native-api/example.mdx desktop_line=30~~ -- corrected desktop platform support
```

## Scan Scope

- Scan report source: `/tmp/lynx-native-api-desktop-doc-alignment-report.json`
- Ledger generated at: `2026-04-21T06:09:35.488Z`
- Docs roots: `docs/en/api/lynx-native-api`, `docs/zh/api/lynx-native-api`
- Compat root: `packages/lynx-compat-data/lynx-native-api`
- Code source reference: `https://github.com/lynx-family/lynx/tree/develop/platform/embedder/public`
- Desktop platforms: `clay_macos`, `clay_windows`

## Scan Summary

| Metric                                                          | Count |
| --------------------------------------------------------------- | ----: |
| Unique Native API doc queries                                   |    86 |
| Compat entries for doc queries                                  |    86 |
| Missing compat entries                                          |     0 |
| Compat desktop supported but no MDX Desktop docs                |     5 |
| Compat desktop supported but some locale MDX lacks Desktop docs |     0 |
| MDX Desktop docs present but no compat desktop support          |     0 |
| MDX Desktop docs present but compat desktop support is partial  |     0 |
| Compat desktop supported and MDX has Desktop docs               |    26 |

## Cleanup Verification

After applying the cleanup, the same Native API alignment scan reports:

| Metric                                                          | Count |
| --------------------------------------------------------------- | ----: |
| Compat desktop supported but no MDX Desktop docs                |     0 |
| Compat desktop supported but some locale MDX lacks Desktop docs |     0 |
| MDX Desktop docs present but no compat desktop support          |     0 |
| MDX Desktop docs present but compat desktop support is partial  |     0 |

## Group Counts

### Compat Desktop Supported But No MDX Desktop Docs By Module

| Group                       | Count |
| --------------------------- | ----: |
| `lynx-native-api/lynx-view` |     4 |
| `lynx-native-api`           |     1 |

### Compat Desktop Supported But Some Locale MDX Lacks Desktop Docs By Module

| Group  | Count |
| ------ | ----: |
| _none_ |     0 |

### MDX Desktop Docs Present But No Compat Desktop Support By Module

| Group  | Count |
| ------ | ----: |
| _none_ |     0 |

### MDX Desktop Docs Present But Partial Compat Desktop Support By Module

| Group  | Count |
| ------ | ----: |
| _none_ |     0 |

## Compat Desktop Supported But No MDX Desktop Docs

Native API items where at least one desktop platform is supported in compat data, but none of the corresponding MDX pages has a Desktop-specific documentation supplement.

- [x] ~~feature: `lynx-native-api.lynx-view.add-lynx-view-client` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/add-lynx-view-client.json` | query: `lynx-native-api/lynx-view/add-lynx-view-client` | desktop: clay\_macos=3.7, clay\_windows=3.7 | mdx\_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx, docs/zh/api/lynx-native-api/lynx-view/add-lynx-view-client.mdx | desc: register lifecycle observer for lynxView~~ -- added Desktop C++ section
- [x] ~~feature: `lynx-native-api.lynx-view.destroy` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/destroy.json` | query: `lynx-native-api/lynx-view/destroy` | desktop: clay\_macos=3.7, clay\_windows=3.7 | mdx\_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/lynx-view/destroy.mdx, docs/zh/api/lynx-native-api/lynx-view/destroy.mdx | desc: manually destroy lynxView instance~~ -- documented Desktop C++ object destruction
- [x] ~~feature: `lynx-native-api.lynx-view.lynx-view-custom-element` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/lynx-view-custom-element.json` | query: `lynx-native-api/lynx-view/lynx-view-custom-element` | desktop: clay\_macos=3.7, clay\_windows=3.7 | mdx\_desktop: en=no, zh=missing-doc | docs: docs/en/api/lynx-native-api/lynx-view/lynx-view\.mdx | desc: <code>lynx-view</code> The custom element of LynxView.~~ -- corrected desktop support; Web custom element is not public embedder Native API
- [x] ~~feature: `lynx-native-api.lynx-view.remove-lynx-view-client` | compat: `packages/lynx-compat-data/lynx-native-api/lynx-view/remove-lynx-view-client.json` | query: `lynx-native-api/lynx-view/remove-lynx-view-client` | desktop: clay\_macos=3.7, clay\_windows=3.7 | mdx\_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/lynx-view/remove-lynx-view-client.mdx, docs/zh/api/lynx-native-api/lynx-view/remove-lynx-view-client.mdx | desc: remove lifecycle observer of lynxView~~ -- added Desktop C++ section
- [x] ~~feature: `lynx-native-api.trace-event` | compat: `packages/lynx-compat-data/lynx-native-api/trace-event.json` | query: `lynx-native-api/trace-event` | desktop: clay\_macos=3.7, clay\_windows=3.7 | mdx\_desktop: en=no, zh=no | docs: docs/en/api/lynx-native-api/trace-event.mdx, docs/zh/api/lynx-native-api/trace-event.mdx | desc: TraceEvent~~ -- added Desktop C API section

## Compat Desktop Supported But Some Locale MDX Lacks Desktop Docs

Native API items where desktop is supported in compat data, but only some existing locale docs have Desktop-specific content.

_No items found._

## MDX Desktop Docs Present But No Compat Desktop Support

Native API items where the MDX page has Desktop-specific documentation, but neither `clay_macos` nor `clay_windows` is supported in compat data.

_No items found._

## MDX Desktop Docs Present But Compat Desktop Support Is Partial

Native API items where the MDX page has Desktop-specific documentation, but only one of `clay_macos` or `clay_windows` is supported in compat data.

_No items found._



---
url: /ai/agentsmd.md
---

# `AGENTS.md` for Lynx

[`AGENTS.md`](https://agents.md) is a project-level instruction file for coding agents, similar to how `README.md` is for human developers.

## Getting Started

New Lynx projects created via [Quick Start](/guide/start/quick-start.md#create-a-new-lynx-project) already include an `AGENTS.md`. For existing projects, copy the template and adapt it to your project:

- [`AGENTS.md` in Lynx Template Project](https://github.com/lynx-family/lynx-stack/blob/main/packages/rspeedy/create-rspeedy/template-common/AGENTS.md)

## Point Agents to Lynx Docs

The most important thing to add is a pointer to [llms.txt](https://lynxjs.org/llms.txt), which serves as an entry point to all Lynx documentation in an LLM-friendly format. Add a section like this to your `AGENTS.md`:

```markdown
## Read in Advance

Read the docs below in advance to help you understand the library or frameworks this project depends on.

- Lynx: [llms.txt](https://lynxjs.org/llms.txt).
  While dealing with a Lynx task, an agent **MUST** read this doc because it is an entry point of all available docs about Lynx.
```

This isn't a magic incantation. It works because the snippet gives the agent a concrete URL to fetch, and the strong language ("MUST") tells it to prioritize the docs over guessing from training data.

If agents still ignore the documentation, you can inline the full contents of `llms.txt` directly into your `AGENTS.md`:

```bash
curl https://lynxjs.org/llms.txt > AGENTS.md
```

To keep it up-to-date automatically, add this command to your `prepare` script in `package.json` and gitignore the generated file.

## Monorepo Setup

In a monorepo, place a root `AGENTS.md` for global guidelines and per-package files for project-specific context. Agents read the closest file first, then walk up.

```bash
$ tree
.
├── AGENTS.md           # global guidelines
├── README.md
└── packages
    ├── web
    │   ├── AGENTS.md   # web-specific
    │   ├── package-a
    │   │   └── AGENTS.md
    │   └── package-b
    │       └── AGENTS.md
    └── lynx
        ├── AGENTS.md   # lynx-specific
        ├── package-c
        │   └── AGENTS.md
        └── package-d
            └── AGENTS.md
```

Place Lynx-specific guidance in `packages/lynx/AGENTS.md`. Keep information consistent across files to avoid conflicting instructions.



---
url: /ai/index.md
---

# Lynx for AI

LLMs are trained on public web data, which means they often lack awareness of the latest Lynx features and best practices. The Lynx team and community are developing a suite of tools to help coding agents understand and develop Lynx more effectively.

## Set Up Your Project with `AGENTS.md`

The [`AGENTS.md`](https://agents.md) file is similar to `README.md`, but written for coding agents. It gives agents the project-specific context they need to work effectively in your Lynx codebase, with zero dependencies and immediate value.

Learn how to add a suitable `AGENTS.md` for your Lynx project in [AGENTS.md for Lynx](/ai/agentsmd.md).

## Add Domain Expertise with Agent Skills

[Agent Skills](https://agentskills.io/home) are reusable rule sets that give coding agents domain-specific knowledge about Lynx's dual-thread architecture, common patterns, and debugging techniques. Install the community collection with:

```bash
npx skills add lynx-community/skills
```

Read more in [Agent Skills for Lynx](https://github.com/lynx-community/skills).

## Connect Tools with MCP

[Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) is a standard for connecting coding agents to external tools.

- [**Lynx Docs MCP**](/ai/lynx-docs-mcp.md) allows agents to fetch accurate guides and API references directly from the Lynx documentation site, ensuring answers stay correct and up to date.
- [**Lynx DevTool MCP**](/ai/lynx-devtool-mcp.md) lets coding agents _**control, operate and preview**_ Lynx pages, just like a human does in DevTool.

## Using `llms.txt`

The Lynx website also supports the [llms.txt](https://llmstxt.org/) standard, which is useful for feeding Lynx documentation into any LLM with web browsing. For every page, you can get the original Markdown by replacing the `.html` extension with `.md`. For example:

- [https://lynxjs.org/llms.txt](https://lynxjs.org/llms.txt)
- [https://lynxjs.org/react/introduction.md](https://lynxjs.org/react/introduction.md)



---
url: /ai/lynx-devtool-mcp.md
---

# Lynx DevTool MCP

Lynx DevTool MCP is a [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/docs/learn/server-concepts) that lets coding agents _**control, operate and preview**_ Lynx pages.

## Get started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "lynx-devtool": {
      "command": "npx",
      "args": ["-y", "@lynx-js/devtool-mcp-server@latest"]
    }
  }
}
```

Claude Code
Use the Claude Code CLI to add the Lynx DevTool MCP server ([guide](https://docs.anthropic.com/en/docs/claude-code/mcp)):
```bash
claude mcp add lynx-devtool npx @lynx-js/devtool-mcp-server@latest
```

Codex
Follow the [configure MCP guide](https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp) using the standard config from above. You can also install the Lynx DevTool MCP server using the Codex CLI:
```bash
codex mcp add lynx-devtool -- npx @lynx-js/devtool-mcp-server@latest
```

Copilot / VS Code
Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), with the standard config from above. You can also install the Lynx DevTool MCP server using the VS Code CLI:
```bash
code --add-mcp '{"name":"lynx-devtool","command":"npx","args":["@lynx-js/devtool-mcp-server@latest"]}'
```

Cursor
**Click the button to install:**
[![Install Lynx DevTool MCP in Cursor](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=lynx-devtool&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBseW54LWpzL2RldnRvb2wtbWNwLXNlcnZlckBsYXRlc3QiXX0=)**Or install manually:**
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.

Gemini CLI
Install the Lynx DevTool MCP server using the Gemini CLI.
**Project wide:**
```bash
gemini mcp add lynx-devtool npx @lynx-js/devtool-mcp-server@latest
```
**Globally:**
```bash
gemini mcp add -s user lynx-devtool npx @lynx-js/devtool-mcp-server@latest
```
Alternatively, follow the [MCP guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server) and use the standard config from above.

## Usage

Using the Lynx DevTool MCP server is just like using DevTool.

You need to connect to the devices and open Apps like LynxExplorer.

### Elements

Just like the "Elements" tab in DevTool,
there are various tools (prefixed with `CSS_*` or `DOM_*`) in Lynx DevTool MCP server to help you inspect the element tree.

:::note
All these tools are read-only. Modify the source code to make changes to the element tree.
:::

### Console

Just like the "Console" tab in DevTool, the coding agent may use Lynx DevTool MCP server to read all the message in Console and their stack traces.

### Sources

Just like the "Sources" tab in DevTool, all the loading JavaScript sources can be read by the Lynx DevTool MCP server.

This is useful for coding agent to find the corresponding code in Console stack traces.

### Interaction

The coding agent may also interact with the Lynx page using Lynx DevTool MCP server, performing actions like tap or drag.

### Screenshot

The Lynx DevTool MCP server also provides tools to take screenshot of the current Lynx page. Using a multimodal model to understand the screenshot.



---
url: /ai/lynx-docs-mcp.md
---

# Lynx Docs MCP

`@lynx-js/docs-mcp-server` is an MCP server providing docs for LLMs from [Lynx official site](https://lynxjs.org/), with carefully designed prompting. It lets your coding agent (such as Gemini, Claude, Cursor or Copilot) access Lynx documentation to assist you in development tasks. Therefore, we have specifically optimized [llms.txt](https://lynxjs.org/llms.txt), a condensed version of the documentation site optimized for LLMs.

## Requirements

- [Node.js](https://nodejs.org/) v18.17 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.

## Getting started

Add the following config to your MCP client:

```json
{
  "mcpServers": {
    "lynx-docs": {
      "command": "npx",
      "args": ["-y", "@lynx-js/docs-mcp-server@latest"]
    }
  }
}
```

`@lynx-js/docs-mcp-server` works best with MCP clients that supports [Server Instructions](https://modelcontextprotocol.io/specification/draft/schema#initializeresult), such as Claude Code.
If you find your MCP client doesn't know about the MCP server,
you can manually provide the following instructions
(e.g. in your `AGENTS.md`, `CLAUDE.md`, or just send it along with your question):

```md
For any questions or requirements regarding Lynx:

1. Use the "List Resources Tool" to list all Resources provided in MCP "lynx-docs".
2. First read MCP Resources "lynx-docs://llms.txt" (**REQUIRED**), this document is an ENTRYPOINT of all Lynx Docs.
3. After reading "lynx-docs://llms.txt", use the "Read MCP Resources Tool" to retrieve docs you need based on the user's questions or requirements, please read them proactively.
4. If available, prioritize obtaining Lynx-related information through MCP Resources tools over external web searches.
```

Claude Code
Use the Claude Code CLI to add the Lynx Docs MCP server (<a href="https://docs.anthropic.com/en/docs/claude-code/mcp">guide</a>):
```bash
claude mcp add lynx-docs npx @lynx-js/docs-mcp-server@latest
```

Codex
Follow the <a href="https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp">configure MCP guide</a>
using the standard config from above. You can also install the Lynx Docs MCP server using the Codex CLI:
```bash
codex mcp add lynx-docs -- npx @lynx-js/docs-mcp-server@latest
```

Copilot / VS Code
Follow the MCP install <a href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server">guide</a>,
with the standard config from above. You can also install the Lynx Docs MCP server using the VS Code CLI:
```bash
code --add-mcp '{"name":"lynx-docs","command":"npx","args":["@lynx-js/docs-mcp-server@latest"]}'
```

Cursor
**Install manually:**
Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.

Gemini CLI
Install the Lynx Docs MCP server using the Gemini CLI.
**Project wide:**
```bash
gemini mcp add lynx-docs npx @lynx-js/docs-mcp-server@latest
```
**Globally:**
```bash
gemini mcp add -s user lynx-docs npx @lynx-js/docs-mcp-server@latest
```
Alternatively, follow the <a href="https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server">MCP guide</a> and use the standard config from above.

## Credits

This project is inspired by [Svelte MCP server](https://svelte.dev/docs/mcp/overview). Both the implementation and documentation have been adapted and referenced from the original MCP server.



---
url: /ai/skills/lynx-debug-info-remapping.md
---

# lynx-debug-info-remapping

Helps agents debug main-thread runtime errors by remapping minified error messages back to their original source, making stack traces actionable.

## Installation

```bash
npx skills add lynx-community/skills -s lynx-debug-info-remapping
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/lynx-devtool.md
---

# lynx-devtool

Lets agents interact with Lynx DevTool to inspect and debug running Lynx applications on connected devices (Android, iOS, Desktop):

- **CDP commands** — Send Chrome DevTools Protocol commands for DOM inspection, CSS querying, console log retrieval, and taking screenshots.
- **App commands** — Open or close pages in the connected Lynx application.
- **Open URLs** — Launch URLs directly in Lynx for development and testing.
- **Troubleshooting** — Built-in diagnostics for connector and transport issues between the agent and DevTool.

## Installation

```bash
npx skills add lynx-community/skills -s lynx-devtool
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Codex

When using this skill with Codex, make sure network access is enabled. Lynx DevTool needs network access to discover and connect to running clients.

Put one of the following configuration snippets in your project config at `<project>/.codex/config.toml` or in your global config at `~/.codex/config.toml`.


**Codex CLI >= 0.133.0**

Use a dedicated permission profile:
```toml
default_permissions = "lynx-devtool"

[permissions.lynx-devtool]
extends = ":workspace"

[permissions.lynx-devtool.network]
enabled = true
```


**Older Codex CLI**

Enable network access in the workspace-write sandbox:
```toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true
```


## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/lynx-typescript.md
---

# lynx-typescript

This article discusses common TypeScript issues and solutions in Lynx development, including environment configuration, type extension, event handling, LynxUI components, and advanced ReactLynx usage.

## Installation

```bash
npx skills add lynx-community/skills -s lynx-typescript
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/lynx-ui.md
---

# lynx-ui

Helps coding agents use [`@lynx-js/lynx-ui`](/lynx-ui/introduction.md) components with curated references from the lynx-ui repository.

Use it when an agent needs to:

- choose the right lynx-ui component for a feature
- verify supported props, events, ref methods, exports, or type aliases
- adapt official examples into project code
- debug a component usage issue against the documented public API
- avoid inventing unsupported lynx-ui APIs from model memory

## Installation

```bash
npx skills add lynx-community/skills -s lynx-ui
```

This installs the `lynx-ui` skill so compatible coding agents can load its routing guide and bundled references automatically.

## What It Contains

`lynx-ui` is structured for progressive disclosure:

- `SKILL.md`: entrypoint and workflow rules for the agent
- `reference.md`: component selection and routing guide
- `references/index.md`: included component coverage
- `references/components/<component>/guide.md`: usage patterns, composition guidance, and common pitfalls
- `references/components/<component>/api.md`: public API source of truth
- `references/components/<component>/examples.md`: concise implementation patterns

## Recommended Workflow

Ask the agent to use `lynx-ui` before implementing lynx-ui code.

1. Identify the concrete component or a small set of candidate components.
2. Use `reference.md` when component selection is unclear.
3. Read the component `guide.md` first for usage patterns.
4. Read `api.md` when exact public surface details matter.
5. Read `examples.md` only when an implementation pattern is needed.

The agent should prefer imports from `@lynx-js/lynx-ui` by default and treat `api.md` as the source of truth for public props, events, ref methods, and exported types.

## Learn More

- [lynx-ui documentation](/lynx-ui/introduction.md)
- [lynx-family/lynx-ui on GitHub](https://github.com/lynx-family/lynx-ui)
- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/reactlynx-best-practices.md
---

# reactlynx-best-practices

Teaches agents patterns writing dual-threaded React code with [ReactLynx](/react/introduction.md). Includes static analysis rules and auto-fix for common issues:

- **`detect-background-only`** (Critical) — Ensures native API calls (`lynx.getJSModule`, `NativeModules`) only happen in background thread contexts, preventing UI blocking.
- **`proper-event-handlers`** — Correct event handler patterns (`bindtap`, `catchtap`) and propagation in ReactLynx.
- **`main-thread-scripts-guide`** — How to properly use `'main thread'` directive and `main-thread:` event prefix for smooth animations and gesture handling.
- **`hoist-static-jsx`** — Performance optimization by hoisting static JSX elements outside components to avoid unnecessary re-creation.

:::tip
These rules are also documented as a standalone guide. See [Best Practices](/react/best-practices.md) for detailed explanations and code examples.
:::

## Installation

```bash
npx skills add lynx-community/skills -s reactlynx-best-practices
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/trace-analysis.md
---

# lynx-trace-analysis

Specializes in analyzing Lynx trace data to diagnose performance issues and provide actionable optimization strategies. It covers startup/loading metrics (FCP, FMP, TTI) and white screen issues, smoothness problems (scroll jank, frame drops, interaction lag), regressions, rendering pipeline stages, and native module latency.

## Installation

```bash
npx skills add lynx-community/skills -s lynx-trace-analysis
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /ai/skills/trace-record.md
---

# lynx-trace-record

Enables agents to capture Lynx performance traces for subsequent analysis, supporting features like system trace, JS profiling for in-depth performance diagnosis.

## Installation

```bash
npx skills add lynx-community/skills -s lynx-trace-record
```

This adds the skill rules to your project so that compatible coding agents (such as Claude Code, Cursor, or Copilot) can automatically apply them.

## Learn More

- [lynx-community/skills on GitHub](https://github.com/lynx-community/skills)
- [Agent Skills specification](https://github.com/anthropics/skills)



---
url: /help/api.md
---

# Documenting APIs

The Lynx documentation relies on a structured system to ensure API references are accurate and consistent.

## Compatibility Data (`lynx-compat-data`)

The source of truth for platform compatibility is stored in `packages/lynx-compat-data`. This is a JSON database similar to MDN's browser-compat-data.

### Adding a New API

1. Navigate to `packages/lynx-compat-data`.
2. Find the appropriate JSON file (e.g., `lynx-api/global/console/log.json`).
3. Add your API definition following the schema.

## Displaying API Tables

To display a compatibility table in your documentation, use the `<APITable>` component.

### Using Frontmatter (Recommended)

It is recommended to define the `api` field in the frontmatter.

```yaml
---
api: lynx-api/global/console/log
---
```

Then place `<APITable />` in your MDX file. It will automatically read the `api` field.

```tsx
<APITable />
```

### Multiple Tables (Explicit Query)

When you need to display multiple tables on a single page, you can pass the `query` prop explicitly.

For example, in [fetch](/api/lynx-api/global/fetch.md), separate tables are used for `Headers`, `Request`, and `Response`:

```tsx
### Headers

<APITable query="lynx-api/fetch/Headers" />

### Request

<APITable query="lynx-api/fetch/Request" />
```

**Compatibility Table**
**Query:** `lynx-api.fetch.Headers`

**MDN Reference:** [https://developer.mozilla.org/docs/Web/API/Headers](https://developer.mozilla.org/docs/Web/API/Headers)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.18 | - |
| iOS | 2.18 | - |
| HarmonyOS | 3.5 | - |
| Clay macOS | 3.7 | - |
| Clay Windows | 3.7 | - |
| Web | ✅ Yes | - |


You can verify valid queries using the [Interactive Explorer](#interactive-explorer) below.

## API Summary

For a high-level view of API groups (like methods, properties, events), use `<APISummary>`. Similar to `<APITable>`, it defaults to reading from the `api` frontmatter field.

```tsx
<APISummary />
```

## Interactive Explorer

You can use the explorer below to find valid API queries and preview their tables.

API Compatibility ExplorerSearch for any Lynx API to view its compatibility across platformsQuick access:CSS`gap`Element`view`CSS`align-self`Nested`align-self → flex layout`Embed this table in your MDX:
```jsx
import { APISummary, APITable } from '@lynx';

<APISummary query="css/properties/gap" />
<APITable query="css/properties/gap" />
```
APISummary**Compatibility Table**
**Query:** `css.properties.gap`

**MDN Reference:** [https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap](https://developer.mozilla.org/zh-CN/docs/Web/CSS/gap)

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 2.14 | - |
| iOS | 2.14 | - |
| HarmonyOS | 3.4 | - |
| Clay Android | 2.14 | - |
| Clay iOS | 2.14 | - |
| Clay macOS | 2.14 | - |
| Clay Windows | 2.14 | - |
| Web | ✅ Yes | - |


## Validating Documentation

We provide a script to ensure your API documentation matches the compatibility data.

```bash
pnpm run check-docs
```

This script (`scripts/check_api_doc`) checks for:

- Invalid `api` frontmatter keys.
- Missing documentation for defined APIs.

## TypeDoc Generation

API reference pages are automatically generated from TypeScript source code using TypeDoc.

- **Config**: `scripts/typedoc/`
- **Command**: `pnpm run typedoc`

Do not manually edit files generated by TypeDoc (usually in `docs/en/api/...`), as they will be overwritten. Edit the source comments instead.



---
url: /help/blog.md
---

# Writing Blog Posts

The Lynx website hosts a blog to share updates, tutorials, and announcements.

## Location

All blog posts are located in `docs/en/blog/`.

## Creating a New Post

1. Create a new `.mdx` file in `docs/en/blog/`. The filename will be part of the URL.
2. Add the necessary frontmatter.

```yaml
---
title: My New Blog Post
date: 2024-01-01
author: Your Name
description: A short summary of the post.
---
```

3. Write your content using standard Markdown and MDX components.

## Blog Components

We provide specialized components for blog listings and author avatars.

### `<BlogList>`

Renders the list of blog posts automatically.

```tsx
import { BlogList } from '@lynx';

<BlogList limit={1} />;
```

[May 31, 2026Lynx 3.8: WebAssembly on Android, Adaptive Layout, and MoreLynx 3.8 starts the monthly release cadence with WebAssembly on Android, adaptive layout and text fitting, HarmonyOS SessionStorage, LynxEngine reuse, and DevTool protocol support.

![](https://github.com/mitchilling.png)![](https://github.com/lynx-family.png)Mitchell Yue, The Lynx Team](/next/blog/lynx-3-8)
### `<BlogAvatar>`

Renders avatars for blog authors.

You can add new authors in `src/components/blog-avatar/authors.json`.

```tsx
import { BlogAvatar } from '@lynx';

<BlogAvatar list={['lynx']} />;
```

![The Lynx Team](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org
## Blog Index

The blog index is automatically generated. Ensure your `date` field is correct so posts are ordered chronologically.

## Images

Place images in the `public/` directory or relative to the blog post if configured.



---
url: /help/components.md
---

# MDX Components Reference

This page serves as a reference for the custom components available in the Lynx documentation. You can import these from `@lynx`.

## Callout & Alerts

Used to highlight important information. You can use standard Markdown syntax `:::type` for callouts.

```markdown
:::info
This is an info callout.
:::

:::warning
This is a warning callout.
:::

:::tip
This is a tip callout.
:::

:::danger
This is a danger callout.
:::
```

:::info
This is an info callout.
:::

:::warning
This is a warning callout.
:::

:::tip
This is a tip callout.
:::

:::danger
This is a danger callout.
:::

## Badges

### Platform Badges

Indicate platform support.

```tsx
<AndroidOnly />
<IOSOnly />
<WebOnly />
<HarmonyOnly />
```

AndroidiOSWebHarmony
### Status Badges

Indicate API or feature status.

```tsx
<Deprecated />
<Experimental />
<Required />
```

DeprecatedExperimentalRequired
### Runtime Badges

Indicate which thread the script runs on.

```tsx
<RuntimeBadge type="mts" />
<RuntimeBadge type="bts" />
```

[MTS Only](/guide/spec.html#scripting-mts)[BTS Only](/guide/spec.html#scripting-bts)
### Version Badge

Indicates the Lynx version a feature was introduced.

```tsx
<VersionBadge v={2.5} />
<VersionBadge>2.5.1</VersionBadge>
```

2.52.5.1

### Generic Badges

Standard Rspress badge.

```tsx
<Badge type="tip" text="Recommended" />
<Badge type="warning" text="Deprecated" />
```

RecommendedDeprecated
## Layout & Containers

### Platform Tabs

Organize content by platform.

```tsx
<PlatformTabs defaultPlatform="ios" queryKey="platform">
  <PlatformTabs.Tab platform="ios">iOS Content</PlatformTabs.Tab>
  <PlatformTabs.Tab platform="android">Android Content</PlatformTabs.Tab>
</PlatformTabs>
```

iOSAndroidiOS Content
Android Content

### Columns

Split content into columns. Pass `titles` prop for column headers.

```tsx
<Columns titles={['Left Column', 'Right Column']}>
  <div>Content for the left column.</div>
  <div>Content for the right column.</div>
</Columns>
```

Left ColumnContent for the left column.
Right ColumnContent for the right column.

### Responsive Dual Column

A layout that switches to single column on smaller screens. Use `FlexItem` to control width.

```tsx
<ResponsiveDualColumn>
  <FlexItem minWidth={300}>
    <div>Left Content (min 300px)</div>
  </FlexItem>
  <FlexItem minWidth={300}>
    <div>Right Content (min 300px)</div>
  </FlexItem>
</ResponsiveDualColumn>
```

Left Content (min 300px)
Right Content (min 300px)

### Browser Container

Wraps content in a browser-like window frame.

```tsx
<BrowserContainer>
  <div style={{ padding: '20px', textAlign: 'center' }}>Browser Content</div>
</BrowserContainer>
```

Browser Content

### CodeFold

Collapsible code block, optionally with an image.

````tsx
<CodeFold toggle>```ts console.log('Hidden code'); ```</CodeFold>
````

```ts
console.log('Hidden code');
```

## Media & Embeds

### YouTube

```tsx
<YouTubeIframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" />
```


### Video List

Display a list of videos with titles.

```tsx
<VideoList
  videos={[
    {
      src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/ifr_fib.mp4',
      title: 'Demo Video',
    },
  ]}
  playbackRate={1.0}
/>
```

Demo Video
### Mermaid Diagrams

```tsx
<Mermaid>
  graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
</Mermaid>
```

**undefined** 
graph TD; A-->B; A-->C; B-->D; C-->D;

## Complex Components

### Blog & Social

See [Writing Blog Posts](/help/blog.md) for details on `<BlogList>` and `<BlogAvatar>`.

```tsx
<BlogList />
<BlogAvatar list={['lynx']} />
```

### Interactive Example

See [Managing Interactive Examples](/help/example.md) for details on `<Go>`.

```tsx
<Go example="view" defaultFile="src/App.tsx" />
```

### API Tables

See [Documenting APIs](/help/api.md) for details on `<APITable>` and `<APISummary>`.

```tsx
<APITable query="lynx-api/global/fetch" />
```

## Documentation Utilities

### Edit This

Renders "Edit source" and "Edit in Cloud IDE" links.

```tsx
<EditThis />
```

[View Source](https://github.com/lynx-family/lynx-website/tree/main/docs/en/help/components.mdx)
### Version Table

Renders a table of Lynx versions.

```tsx
<VersionTable type="latest" />
```

| Version Number | release | docs repo branch | docs link | release blog |
| --- | --- | --- | --- | --- |
| 3.8 | --- | [release/3.8](https://github.com/lynx-family/lynx-website/tree/release/3.8) | [https://lynxjs.org/](https://lynxjs.org/) | --- |




---
url: /help/dashboard.md
---

# API Status Dashboard Guide

:::tip
This usage guide was generated with AI assistance. If you find any inaccuracies, please help us improve it by submitting a pull request.
:::

This guide explains how to use the Lynx API Status Dashboard to explore API compatibility across different platforms.

![API Status Dashboard Overview](/api-status-help/api-status-main.png)

***

## 1. Select Platform

At the top of the dashboard, you'll find the **Platform Selector** which allows you to select one or multiple platforms to view their specific API coverage.

### Native Platforms

- **Android** - Mobile Android platform
- **iOS** - Apple iOS platform
- **Harmony** - HarmonyOS platform
- **Web** - Web Lynx implementation

Use the checkboxes to select multiple platforms simultaneously. The dashboard will update to show coverage statistics for the combined selection.

### Clay Platforms

Click the **Clay** toggle button to reveal additional Clay platform options:

![Clay Platforms Expanded](/api-status-help/api-status-clay-platforms.png)

Clay platforms include:

- **Clay (Android)** - Clay running on Android
- **Clay (iOS)** - Clay running on iOS
- **Clay (macOS)** - Clay running on macOS
- **Clay (Windows)** - Clay running on Windows

***

## 2. Search, Filter, and View APIs

### Search Box

Use the search box to quickly find specific APIs by name or description. The search is case-insensitive and matches partial text.

**Examples:**

- Search `image` to find all image-related APIs
- Search `scroll` to find scrolling functionality
- Search `animation` to find animation APIs

### Category Filter

The first dropdown allows you to filter APIs by category:

- **All** - Show all categories
- **ELEMENT** - Element-related APIs
- **CSS** - CSS property support
- **API** - JavaScript API methods

### State Filter

The second dropdown filters APIs by their support status on the selected platform:

- **All** - Show all APIs
- **Supported** - Only show supported APIs
- **Unsupported** - Only show unsupported APIs

### API List

The API list displays all matching APIs in a two-column grid layout. Each API item shows:

- **Category badge** (e.g., `ELEMENT`, `CSS`, `API`)
- **API name** (e.g., `commonality`, `image.loop-count`)
- **Color coding**:
  - 🟢 **Green background** - API is supported on all selected platforms
  - 🟡 **Yellow background** - API is partially supported (supported on some but not all selected platforms)
  - 🔴 **Red background** - API is not supported on any selected platform

For partially supported APIs, a small indicator (e.g., "2/3") shows how many of the selected platforms support that feature.

By default, only the first 100 results are shown for performance. Click **"Show All"** to display all matching results.

### API Detail Drawer

Click on any API item to open the detailed compatibility drawer:

![API Detail Drawer](/api-status-help/api-status-drawer.png)

The drawer shows a compatibility table with:

- **Rows** - Each sub-API or property
- **Columns** - All platforms (Android, iOS, HarmonyOS, macOS, Windows, Web)

| Icon           | Meaning                      |
| -------------- | ---------------------------- |
| ✓ with version | Supported since that version |
| ✗ No           | Not supported                |
| ?              | Support status unknown       |

Click the **"View source"** link to see the raw compatibility data in the GitHub repository.

***

## 3. View Platform Coverage and Trends

The bottom section shows platform statistics and historical trends:

![Coverage Card and Trend Chart](/api-status-help/api-status-coverage-trend.png)

### Coverage Card (Left)

- **Percentage** - Overall API coverage (e.g., 87%)
- **Fraction** - Exact count (e.g., 945 / 1,092)
- **Progress bar** - Visual representation with platform-specific color

### Trend Chart (Right)

- **X-axis** - Lynx versions (e.g., 2.14 → 3.4)
- **Y-axis** - API coverage percentage
- **Line** - Coverage progression over time

This helps you understand how API support has improved across versions.

### Category Table

The **Coverage** section provides a breakdown by API category:

![Category Table with Expanded View](/api-status-help/api-status-category-expanded.png)

| Column   | Description                             |
| -------- | --------------------------------------- |
| Category | API category name (e.g., Elements, CSS) |
| Coverage | Percentage and count of supported APIs  |
| Missing  | Number of unsupported APIs (if any)     |

**Highlight Modes:**

- **Highlight Good** (Green mode) - Emphasizes high coverage categories
- **Highlight Gap** (Red mode) - Emphasizes low coverage categories

Click on any category row to expand it and see the individual APIs. Unsupported APIs are highlighted in red for easy identification.

***

## 4. Recently Added APIs

The **Recently Added** section lists APIs that were recently added to Lynx, grouped by version.

![Recently Added APIs by Version](/api-status-help/api-status-recently-added.png)

Each version group shows:

- **Version number** (e.g., v3.5, v3.4, v2.18)
- **API count** for the selected platform
- **List of APIs** added in that version

This is useful for tracking new features in each Lynx release.

***

## Tips

1. **Start with platform selection** - Choose your target platforms (one or more) first to see relevant coverage data.
2. **Use Colorblind Mode** - Toggle the **Colorblind Mode** switch in the sidebar footer to enable a high-contrast Blue/Orange theme for better accessibility.
3. **Use search for specific APIs** - If you know the API name, search is faster than scrolling.
4. **Check the drawer for details** - The compatibility table shows version-specific information.
5. **Monitor trends** - Use the trend chart to understand coverage improvements over time.
6. **Toggle Clay for desktop** - Enable Clay platforms if you're building cross-platform desktop apps.

***

## Need Help?

If you have questions about API compatibility or need assistance:

- Check the [API documentation](/api/index.md)
- Contribute on [GitHub](https://github.com/lynx-family/lynx)



---
url: /help/example.md
---

# Managing Interactive Examples (`<Go>`)

Interactive examples allow users to preview and edit code directly in the documentation. This guide explains how to manage these examples using the dedicated workspace and the `<Go>` component.

## Overview

The interactive example system allows you to embed live, runnable Lynx code in your documentation. It consists of:

1. **Source Packages**: Examples are real npm packages managed in `packages/lynx-example-packages/`.
2. **Build Process**: A script bundles these packages into static assets for the website.
3. **`<Go>` Component**: A React component that renders the interactive editor and preview in your MDX files.

***

## 1. Using the `<Go>` Component

To embed an interactive example in your documentation, use the `<Go>` component.

### Basic Usage

Import `Go` from `@lynx` and provide the `example` ID (which corresponds to the package directory name).

```tsx
import { Go } from '@lynx';

<Go example="view" />;
```

### Component Props

| Prop               | Type     | Default          | Description                                                                                                 |
| :----------------- | :------- | :--------------- | :---------------------------------------------------------------------------------------------------------- |
| `example`          | `string` | **Required**     | The ID of the example to load (e.g., `"view"`). Matches the directory name in `docs/public/lynx-examples/`. |
| `defaultFile`      | `string` | `"package.json"` | The file path to display in the code editor initially.                                                      |
| `defaultEntryName` | `string` | -                | The specific entry point to run (if the example has multiple bundles).                                      |
| `img`              | `string` | -                | URL to a custom preview image (overrides the default `preview-image.png`).                                  |
| `highlight`        | `object` | -                | Line highlighting configuration. Format: `{ "path/to/file": "start-end" }`.                                 |
| `schema`           | `string` | -                | Custom schema URL pattern for the preview. Use `{{{url}}}` as a placeholder for the bundle URL.             |

### Advanced Example

```tsx
<Go
  example="view"
  defaultFile="src/App.tsx"
  defaultEntryName="main"
  highlight={{ 'src/App.tsx': '5-10' }}
/>
```

**This is an example below: view**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx 5-10
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import type { ReactElement } from "react";

const RenderExample = () => {
  return (
    <view
      style={{
        borderLeftWidth: "15px",
        borderRightWidth: "60px",
        borderTopWidth: "100px",
        borderBottomWidth: "50px",
        borderColor: "green red",
        backgroundColor: "blue",
        width: "100vw",
        height: "500px",
      }}
    />
  );
};

const LayoutExample = () => {
  return (
    <view
      style={{
        width: "100vw",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        marginTop: "100px",
      }}
    >
      <text
        style={{
          fontSize: "50px",
          padding: "30px",
          background: "red",
        }}
      >
        Hello World
      </text>
      <text
        style={{
          fontSize: "50px",
          marginTop: "50px",
          padding: "30px",
          background: "green",
        }}
      >
        Hello Lynx
      </text>
    </view>
  );
};

export const App = () => {
  const examples: ReactElement[] = [
    <RenderExample />,
    <LayoutExample />,
  ];

  return (
    <scroll-view scroll-orientation="vertical" style="padding:5px;width:100%; height:100%;">
      <text className="title">View Examples</text>
      {examples.map((example, index) => example)}
    </scroll-view>
  );
};

```



***

## 2. Managing Example Packages

All interactive examples are managed as dependencies in the `packages/lynx-example-packages/` workspace.

### Directory Structure

```text
packages/lynx-example-packages/
├── package.json          # Manifest listing all example dependencies
├── pnpm-lock.yaml       # Lockfile for examples
└── node_modules/        # Where installed examples reside
    └── @lynx-example/   # Namespace for official examples
```

### Adding a New Example

To make a new example available to the `<Go>` component:

1. **Publish the Package**: Your example must be a valid npm package (e.g., `@lynx-example/my-feature`).
2. **Add Dependency**: Add the package to `packages/lynx-example-packages/package.json`.
3. **Install**: Run `pnpm install` in the workspace root to download the new example.
4. **Rebuild Assets**: The website build process will automatically detect and bundle the new example.

***

## 3. Build Architecture

For those interested in how it works under the hood:

- **Script**: `scripts/lynx-example.js` runs during the build.
- **Process**:
  1. Scans `node_modules/@lynx-example/` for packages.
  2. Identifies bundle files (`.lynx.bundle`, `.web.bundle`) and source code.
  3. Generates an `example-metadata.json` for each example.
  4. Copies assets to `docs/public/lynx-examples/`.
- **Runtime**: The `<Go>` component fetches this metadata at runtime to hydrate the editor and preview.



---
url: /help/index.md
---

# Contributor Guide

Welcome to the Lynx website contributor guide! This documentation project is a large-scale repository that powers the official Lynx documentation. To help you navigate and contribute effectively, we've organized the guidelines into specific topics.

Whether you are writing a blog post, updating API documentation, or adding a new example, this guide will help you understand the tools and conventions we use.

## Catalog

### ✍️ Writing

- [**Guides**](/help/writing.md) - Best practices for page configuration, frontmatter, and writing platform-specific content.
- [**Example**](/help/example.md) - How to add and embed interactive examples using `lynx-example-packages`.
- [**Blog**](/help/blog.md) - How to write and publish blog posts.
- [**Spec**](/help/spec.md) - Guide to editing the Lynx Living Specification.

### 📚 Managing API

- [**API Reference**](/help/api.md) - The source of truth for API references. Learn about `lynx-compat-data`, `<APITable>`, and generating docs with TypeDoc.
- [**API Status**](/help/dashboard.md) - Guide for using the API Status Dashboard tool.

### 🎨 Website UI

- [**Subsites**](/help/subsite.md) - Understanding how the site handles multiple languages and contexts (subsites).
- [**MDX Components References**](/help/components.md) - A "Storybook-style" reference for using built-in components like badges, callouts, and tabs.



---
url: /help/spec.md
---

# Managing Spec

The Lynx Living Specification serves as the definitive technical reference for the Lynx engine.

## Location

The spec source files are located in `packages/lynx-living-spec/`.
The source `.bs` files are specifically in `packages/lynx-living-spec/src/`.

## Format

The spec is written in **Bikeshed** (`.bs`), a preprocessor for specification documents often used by W3C standards.

## Prerequisites

To build the spec, you need to have **Bikeshed** installed. We recommend using `pipx` to install it.

### Install pipx

If you don't have `pipx` installed, you can install it via Homebrew (on macOS):

```bash
brew install pipx
```

### Install Bikeshed

Once `pipx` is installed, install `bikeshed`:

```bash
pipx install bikeshed
```

## Editing the Spec

1. Modify the `.bs` files in `packages/lynx-living-spec/src/`.
   - `index.bs` is the main entry point.
   - Other sections are split into separate files like `styling.bs`, `scripting.bs`, etc.
2. To build the spec locally, run:

```bash
pnpm gen:living-spec
```

This uses a script (`scripts/lynx-living-spec.js`) to invoke `bikeshed` and generate the HTML output at `docs/public/living-spec/index.html`.



---
url: /help/subsite.md
---

# Multi-Subsite Architecture

The Lynx website operates as a collection of "mini-subsites" (e.g., **Lynx**, **ReactLynx**, **Rspeedy**) housed within a single repository. This architecture allows each subsite to have its own identity (logo, home page, sidebar) while sharing common documentation and infrastructure.

## Configuration

The central configuration for subsites is located in [`shared-route-config.ts`](https://github.com/lynx-family/lynx-website/blob/main/shared-route-config.ts). This file acts as the single source of truth for:

1. **Subsite Metadata**: Defines the list of available subsites.
2. **Shared Routes**: Defines which documentation sections are shared across subsites.

### `SubsiteConfig`

Each subsite is defined by a `SubsiteConfig` object:

```typescript
export type SubsiteConfig = {
  value: string; // Unique ID (e.g., 'guide')
  label: string; // Display name (e.g., 'Lynx')
  description: string; // Short description
  home: string; // Root path (e.g., '/')
  url: string; // Landing page URL
  logo: {
    // Logo assets
    light: string;
    dark: string;
  };
};
```

## Adding a New Subsite

To add a new subsite (e.g., `my-framework`):

1. **Create Directory**: Create `docs/en/my-framework/` (and `docs/zh/my-framework/`).
2. **Update Config**: Add a new entry to `SUBSITES_CONFIG` in `shared-route-config.ts`.
   ```typescript
   {
     value: 'my-framework',
     label: 'My Framework',
     // ...
   }
   ```
3. **Configure Sidebar**: Create `docs/en/my-framework/_meta.json` to define its specific sidebar structure.

## Shared Documentation

To avoid duplicating content (like "Quick Start" guides) across multiple subsites, we use a shared documentation system.

### How it Works

1. **Source of Truth**: Shared files are physically located in `docs/en/guide/start/`.
2. **Virtual Routes**: The `sharedSidebarPlugin` in `rspress.config.ts` dynamically creates virtual pages for other subsites (e.g., `react/start/quick-start`) that point to the same content.
3. **Unified Sidebar**: The `BeforeSidebar` component (in `theme/BeforeSidebar.tsx`) automatically injects the shared "Start" section into the sidebar of every subsite.

### Managing Shared Content

To modify which files are shared, update `SHARED_DOC_TITLES` in `shared-route-config.ts`.

```typescript
const SHARED_DOC_TITLES = {
  'quick-start': { en: 'Quick Start', zh: '快速上手' },
  // ...
};
```

## Subsite UI

The subsite navigation and identity are handled by custom theme components:

- **`SubsiteSelect`** (`theme/BeforeSidebar.tsx`): The dropdown menu at the top of the sidebar allows users to switch between subsites.
- **`SubsiteLogo`** (`theme/subsite-ui.tsx`): Renders the correct logo for the current subsite and theme mode.

These components read directly from `SUBSITES_CONFIG`, so any changes there are immediately reflected in the UI.



---
url: /help/writing.md
---

# Authoring Guides

This page outlines the standards and best practices for writing **Guides** on the Lynx website. Guides are narrative documentation designed to teach concepts, explain architecture, or walk users through specific tasks.

For excellent examples of well-structured guides, refer to the [Quick Start](/guide/start/quick-start.md) and [Integrate with Existing Apps](/guide/start/integrate-with-existing-apps.md) pages.

## Page Structure (Frontmatter)

Every guide page is an `.mdx` file that starts with YAML frontmatter to define its metadata.

### `title`

Sets the page title displayed in the sidebar, browser tab, and search results.

```yaml
---
title: Understanding the Lifecycle
---
```

### `context`

Defines the framework or context for the page (e.g., `react`, `vue`, `new`). This is crucial for the **DSL Switcher** feature, which allows users to toggle the documentation view between different framework implementations.

```yaml
---
context: react
---
```

## Writing Tutorials

When writing step-by-step tutorials, use the following components to create a structured and engaging flow.

### `<Steps>`

Use the `<Steps>` component to wrap sequential instructions. This renders a vertical line connecting the steps, improving readability.

### Step 1: Install
Run the installation command...
### Step 2: Configure
Update your config file...

```tsx
import { Steps } from '@theme';

<Steps>
  ### Step 1: Install Run the installation command... ### Step 2: Configure
  Update your config file...
</Steps>;
```

### `<PackageManagerTabs>`

When providing installation commands, use `<PackageManagerTabs>` to automatically show tabs for `npm`, `pnpm`, `yarn`, and `bun`.


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

```tsx
import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="install" />;
```

### `<NextSteps>`

At the end of a guide, use `<NextSteps>` to suggest relevant follow-up reading. This helps users navigate a learning path.

[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)[Layout

Understand the layout system

](/guide/ui/layout)
```tsx
import * as NextSteps from '@lynx/NextSteps';

<NextSteps.Root>
  <NextSteps.Step
    href="/guide/ui/styling"
    title="Styling"
    description="Learn how to apply different styles in Lynx"
  />
  <NextSteps.Step
    href="/guide/ui/layout"
    title="Layout"
    description="Understand the layout system"
  />
</NextSteps.Root>;
```

## Platform-Specific Content

Lynx runs on multiple platforms (Android, iOS, Web, etc.). When writing guides, it is essential to clearly distinguish content that varies by platform.

### Using Platform Tabs

Use the `<PlatformTabs>` component to organize platform-specific instructions. This component persists the user's platform selection as they navigate the site.

iOSAndroidiOS specific instructions...
Android specific instructions...
## 


```tsx
import { PlatformTabs } from '@lynx';

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    iOS specific instructions...
  </PlatformTabs.Tab>
  <PlatformTabs.Tab platform="android">
    Android specific instructions...
  </PlatformTabs.Tab>
</PlatformTabs>;
```

### Using Platform Badges

Use `<PlatformBadge>` or specific platform icons (like `<AndroidOnly />`) to explicitly mark features or caveats that apply only to certain platforms.

See [MDX Components Reference](/help/components.md#platform-badges) for usage details.

## Related Resources

- [**MDX Components Reference**](/help/components.md) - A catalog of custom components available for use in guides.
- [**Managing Examples**](/help/example.md) - Instructions for embedding interactive code examples.
- [**API Reference**](/help/api.md) - For details on documenting technical API specifications.



---
url: /index.md
---

# Unlock Native for More

> Empower the web community and invite more to build across platforms

[Quick Start](/guide/start/quick-start) | [Why Lynx](/blog/lynx-unlock-native-for-more)



---
url: /lynx-ui/changelog.md
---

# CHANGELOG

::: warning
This file should be sync automatically from npm.
:::



---
url: /lynx-ui/components/button.md
---

# 

# `<Button>`

A headless Button component for ReactLynx. It provides press state tracking (`active`) and render props for custom styling.
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-button) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

## Basic Usage

**This is an example below: lynx-ui-button**

**Entry:** `Basic`
**Bundle:** `dist/ButtonBasic.lynx.bundle` | Web: `dist/ButtonBasic.web.bundle`

```tsx {19-27,29-34}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import { Button } from '@lynx-js/lynx-ui'
import { clsx } from 'clsx'

import { Heart } from '../shared/Heart'

import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark luna-gradient-rose'>
      <view className='demo-canvas'>
        {/* Usage 1: render props to read `active` state and toggle `.active` for styling */}
        <Button onClick={() => console.info('clicked')} className='button-root'>
          {({ active = false }) => (
            <view className={clsx('button', { 'active': active })}>
              <text className='button-text'>
                Button
              </text>
            </view>
          )}
        </Button>
        {/* Usage 2: regular children; styles rely on the primitives-injected `ui-active` state class */}
        <Button className='button'>
          <Heart />
          <text className='button-text'>
            Button
          </text>
        </Button>
      </view>
    </view>
  )
}
root.render(<App />)
export default App

```



### Button

The root component of the Button, containing all of its child components.



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-activeRender Prop`active`·Type`boolean`Whether the button is currently being pressed (and not disabled).
Applied when `status.active` is true.ui-disabledRender Prop`disabled`·Type`boolean`Whether the button is disabled.
Applied when `status.disabled` is true.


---
url: /lynx-ui/components/checkbox.md
---

# 

# `<Checkbox>`

A headless Checkbox component for ReactLynx. It supports controlled/uncontrolled checked state and indeterminate mode.
## Basic Usage

The most basic usage of the `<Checkbox>`

**This is an example below: lynx-ui-checkbox**

**Entry:** `Basic`
**Bundle:** `dist/CheckboxBasic.lynx.bundle` | Web: `dist/CheckboxBasic.web.bundle`

```tsx {23-32,41-53,62-66,70-74}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Checkbox, CheckboxIndicator } from '@lynx-js/lynx-ui'

import { CheckMark } from '../shared/Checkmark'
import { hitSlop } from '../shared/hitSlop'
import './index.css'

function App() {
  const [checked, setChecked] = useState(false)

  return (
    <view className='demo-container lunaris-dark luna-gradient-ocean'>
      <view className='demo-canvas'>
        {/* Uncontrolled */}
        <view className='section'>
          <text className='title'>Uncontrolled</text>
          <view className='row'>
            <Checkbox
              className='checkbox'
              defaultChecked={true}
              onChange={(value) => console.log('Uncontrolled changed:', value)}
              checkboxProps={hitSlop}
            >
              <CheckboxIndicator className='checkbox-indicator'>
                <CheckMark />
              </CheckboxIndicator>
            </Checkbox>
            <text className='label'>Uncontrolled Checkbox</text>
          </view>
        </view>

        {/* Controlled */}
        <view className='section'>
          <text className='title'>Controlled</text>
          <view className='row'>
            <Checkbox
              className='checkbox'
              checked={checked}
              onChange={(value) => {
                console.log('Controlled changed:', value)
                setChecked(value)
              }}
              checkboxProps={hitSlop}
            >
              <CheckboxIndicator className='checkbox-indicator'>
                <CheckMark />
              </CheckboxIndicator>
            </Checkbox>
            <text className='label'>{checked ? 'Checked' : 'Unchecked'}</text>
          </view>
        </view>

        {/* Disabled */}
        <view className='section'>
          <text className='title'>Disabled</text>
          <view className='row'>
            <Checkbox disabled className='checkbox'>
              <CheckboxIndicator className='checkbox-indicator'>
                <CheckMark />
              </CheckboxIndicator>
            </Checkbox>
            <text className='label disabled'>Disabled</text>
          </view>
          <view className='row'>
            <Checkbox disabled checked className='checkbox'>
              <CheckboxIndicator className='checkbox-indicator'>
                <CheckMark />
              </CheckboxIndicator>
            </Checkbox>
            <text className='label disabled'>Disabled & Checked</text>
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Indeterminate State

The indeterminate state is used when a `<Checkbox>` represents a group of options where some, but not all, are selected

**This is an example below: lynx-ui-checkbox**

**Entry:** `Indeterminate`
**Bundle:** `dist/CheckboxIndeterminate.lynx.bundle` | Web: `dist/CheckboxIndeterminate.web.bundle`

```tsx {46-56,63-72}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Checkbox, CheckboxIndicator } from '@lynx-js/lynx-ui'

import { CheckMark } from '../shared/Checkmark'
import { hitSlop } from '../shared/hitSlop'
import './index.css'

const FRUITS = ['Apple', 'Banana', 'Orange']

function IndeterminateMark() {
  return <view className='indeterminate-mark' />
}

function App() {
  const [selected, setSelected] = useState<string[]>([FRUITS[0]])

  const allSelected = selected.length === FRUITS.length
  const noneSelected = selected.length === 0
  const indeterminate = !noneSelected && !allSelected

  const handleSelectAll = (checked: boolean) => {
    console.log('Select All changed:', checked)
    setSelected(checked ? FRUITS : [])
  }

  const handleItem = (item: string, checked: boolean) => {
    console.log(`Item "${item}" Changed:`, checked)
    setSelected((prev) => {
      if (checked) return prev.includes(item) ? prev : [...prev, item]
      return prev.filter((x) => x !== item)
    })
  }

  return (
    <view className='demo-container lunaris-dark luna-gradient-ocean'>
      <view className='demo-canvas'>
        <view className='section'>
          <text className='title'>Indeterminate</text>

          <view className='row'>
            <Checkbox
              className='checkbox'
              checked={allSelected}
              indeterminate={indeterminate}
              onChange={handleSelectAll}
              checkboxProps={hitSlop}
            >
              <CheckboxIndicator className='checkbox-indicator'>
                {indeterminate ? <IndeterminateMark /> : <CheckMark />}
              </CheckboxIndicator>
            </Checkbox>
            <text className='label'>Select All</text>
          </view>

          <view className='fruits'>
            {FRUITS.map((fruit) => (
              <view key={fruit} className='row'>
                <Checkbox
                  className='checkbox'
                  checked={selected.includes(fruit)}
                  onChange={(checked) => handleItem(fruit, checked)}
                  checkboxProps={hitSlop}
                >
                  <CheckboxIndicator className='checkbox-indicator'>
                    <CheckMark />
                  </CheckboxIndicator>
                </Checkbox>
                <text className='label'>{fruit}</text>
              </view>
            ))}
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)
export default App

```



## Structure

```tsx
<Checkbox className="checkbox">
  <CheckboxIndicator className="checkbox-indicator">
    {<YourOwnCheckIcon />}
  </CheckboxIndicator>
</Checkbox>
```

## API

### Checkbox



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-checkedRender Prop`checked`·Type`boolean`Whether the checkbox is currently checked.
Applied when `status.checked` is true.ui-indeterminateRender Prop`indeterminate`·Type`boolean`Whether the checkbox is in an indeterminate state.
Applied when `status.indeterminate` is true.ui-activeRender Prop`active`·Type`boolean`Whether the checkbox is currently being pressed (and not disabled).
Applied when `status.active` is true.ui-disabledRender Prop`disabled`·Type`boolean`Whether the checkbox is disabled.
Applied when `status.disabled` is true.
### CheckboxIndicator




---
url: /lynx-ui/components/dialog.md
---

# 

# `Dialog`

A headless Dialog (modal) component for ReactLynx. It provides backdrop overlay, open/close state management, and enter/exit animations via Presence.
The dialog component. Have a customizable background mask layer.

## Basic Usage

**This is an example below: lynx-ui-dialog**

**Entry:** `Basic`
**Bundle:** `dist/DialogBasic.lynx.bundle` | Web: `dist/DialogBasic.web.bundle`

```tsx {25-56}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import './index.css'

import {
  DialogBackdrop,
  DialogClose,
  DialogContent,
  DialogRoot,
  DialogTrigger,
  DialogView,
} from '@lynx-js/lynx-ui'

function App() {
  const handleDismissed = () => {
    console.log('dismissed!')
  }
  const handleShowed = () => {
    console.log('showed!')
  }
  const [show, setShow] = useState(true)

  return (
    <view className='demo-container lunaris-dark'>
      <DialogRoot
        onClose={handleDismissed}
        onOpen={handleShowed}
        show={show}
        onShowChange={setShow}
      >
        <DialogTrigger className='dialog-trigger'>
          <text className='dialog-trigger-text'>Show Dialog</text>
        </DialogTrigger>

        <DialogView className='dialog-viewport'>
          <DialogBackdrop className='dialog-backdrop' />

          <DialogContent className='dialog-content'>
            <view className='dialog-body'>
              <text className='dialog-title'>Step into the next phase</text>
              <text className='dialog-desc'>
                This action will shift your current state. Nothing drastic, just
                a subtle drift, like moonlight sliding across a quiet surface.
              </text>
            </view>

            <DialogClose className='dialog-close'>
              <text className='dialog-close-text'>Proceed</text>
            </DialogClose>
          </DialogContent>
        </DialogView>
      </DialogRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

```jsx
<DialogRoot>
  <DialogView>
    <DialogBackdrop />
    <DialogContent />
  </DialogView>
</DialogRoot>
```

## API

### DialogRoot

The root component of the Dialog, containing all of its child components.



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-animatingRender Prop`animating`·Type`boolean`The popper is doing the animations. Takes effect when transition:true.
Applied when `status.animating` is true.ui-closedRender Prop`closed`·Type`boolean`The popper is closed.
If it's force mounted, the initial status will be closed.
Applied when `status.closed` is true.ui-enteringRender Prop`entering`·Type`boolean`The popper is performing the entering animation. Takes effect when transition:true.
Applied when `status.entering` is true.ui-leavingRender Prop`leaving`·Type`boolean`The popper is performing the leaving animation. Takes effect when transition:true.
Applied when `status.leaving` is true.ui-openRender Prop`open`·Type`boolean`The popper is opened.
Applied when `status.open` is true.
### DialogBackdrop

The backdrop mask of the dialog.


### DialogView

View container. When 'container' is set correctly, the underlying layer will be replaced with overlay; otherwise, it will be a regular view. When the underlying layer is overlay, the 'level' property can be used to control the hierarchical relationship. For a regular view, use 'z-index' to control the hierarchical relationship. If this dialog needs to be used outside of LynxView, consider enabling overlay.



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-openRender Prop`open`·Type`boolean`The popper is opened.
Applied when `status.open` is true.ui-closedRender Prop`closed`·Type`boolean`The popper is closed.
If it's force mounted, the initial status will be closed.
Applied when `status.closed` is true.ui-leavingRender Prop`leaving`·Type`boolean`The popper is performing the leaving animation. Takes effect when transition:true.
Applied when `status.leaving` is true.ui-enteringRender Prop`entering`·Type`boolean`The popper is performing the entering animation. Takes effect when transition:true.
Applied when `status.entering` is true.ui-animatingRender Prop`animating`·Type`boolean`The popper is doing the animations. Takes effect when transition:true.
Applied when `status.animating` is true.
### DialogContent

The main content of the dialog.




---
url: /lynx-ui/components/draggable.md
---

# 

# `<Draggable>`

A headless Draggable component for ReactLynx. It provides drag-and-drop primitives via main-thread execution.
## Basic Usage

Draggable supports two gesture modes: `immediate` (drag starts instantly on touch) and `longpress` (drag starts after a long press gesture).
You can also control whether the position resets when the drag ends or preserves its transform position.

**This is an example below: lynx-ui-draggable**

**Entry:** `Basic`
**Bundle:** `dist/DraggableBasic.lynx.bundle`

```tsx {16-17}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import { Draggable } from '@lynx-js/lynx-ui'

import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <Draggable
        className='draggable'
        resetOnEnd={true}
        trigger='immediate'
      />
    </view>
  )
}

root.render(<App />)

export default App

```



## With bounds

The draggable area allowed can be limited with min(max)TranslateX/Y props.

**This is an example below: lynx-ui-draggable**

**Entry:** `WithBounds`
**Bundle:** `dist/DraggableWithBounds.lynx.bundle`

```tsx {18-21}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import { Draggable } from '@lynx-js/lynx-ui'

import './index.css'

function App() {
  return (
    <view className='container lunaris-dark'>
      <view className='draggable-area'>
        <Draggable
          className='draggable'
          resetOnEnd={true}
          minTranslateX={-100}
          minTranslateY={-100}
          maxTranslateX={100}
          maxTranslateY={100}
          trigger='immediate'
        />
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

The whole component is draggable.

```tsx
<Draggable />
```

Only the DraggableArea accepts the dragging gesture.

```tsx
<DraggableRoot>
  <DraggableArea />
</DraggableRoot>
```

## API

### Draggable


### DraggableArea




---
url: /lynx-ui/components/feed-list.md
---

# 

# `<FeedList>`

A FeedList component for ReactLynx. Designed to render lists with complex layouts and infinite scrolling.
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-feed-list) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

Moreover, you can also implement your own feed/list interaction behavior with [MTS](https://lynxjs.org/api/lynx-api/main-thread.html).

:::

Basic UsageUnder the `refreshOptions`## Basic Usage

Use FeedList when the page needs both virtualized list rendering and feed
behaviors such as pull-to-refresh or load-more. Keep each row as a direct
`list-item` child with a stable `item-key`, and provide `listId` plus `listType`
so the underlying list can manage identity and layout.

**This is an example below: lynx-ui-feed-list**

**Entry:** `Basic`
**Bundle:** `dist/FeedListBasic.lynx.bundle`

```tsx {79-113}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useMemo, useRef, useState } from '@lynx-js/react'

import { FeedList } from '@lynx-js/lynx-ui'
import type { FeedListRef } from '@lynx-js/lynx-ui'

import { FEED_INITIAL, FEED_MORE, FEED_REFRESH } from './data'
import type { LetterItem } from './data'
import { RectangleCard } from '../shared/RectangleCard'
import { RefreshHeader } from '../shared/RefreshHeader'

import './index.css'

function App() {
  const feedListRef = useRef<FeedListRef>(null)
  const [items, setItems] = useState<LetterItem[]>(FEED_INITIAL)
  const noMoreData = useRef(false)
  const isLoadingMore = useRef(false)

  const renderRefreshHeader = useMemo(
    () => <RefreshHeader />,
    [],
  )

  const renderLoadMoreFooter = useMemo(
    () => (
      <list-item key='footer' item-key='footer' full-span>
        <view className='load-more-footer'>
          <image
            src='https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/loading.gif'
            className='load-more-footer__spinner'
          />
        </view>
      </list-item>
    ),
    [],
  )

  const renderNoMoreFooter = useMemo(
    () => (
      <list-item key='noMore' item-key='noMore' full-span>
        <text className='no-more-data-footer'>
          That's everything!
        </text>
      </list-item>
    ),
    [],
  )

  const handleRefresh = () => {
    setTimeout(() => {
      // Reset so load-more can fire again after refresh
      noMoreData.current = false
      isLoadingMore.current = false
      setItems(prev =>
        prev[0]?.key.startsWith('refresh-') ? FEED_INITIAL : FEED_REFRESH
      )
      feedListRef.current?.changeHasMoreStatus(true)
      feedListRef.current?.finishRefresh()
    }, 2000)
  }

  const handleLoadMore = () => {
    if (noMoreData.current || isLoadingMore.current) return
    isLoadingMore.current = true
    setTimeout(() => {
      noMoreData.current = true
      setItems(prev => [...prev, ...FEED_MORE])
      feedListRef.current?.changeHasMoreStatus(false)
      isLoadingMore.current = false
    }, 2000)
  }

  return (
    <view className='lunaris-dark demo-container'>
      <FeedList
        className='feed-list'
        listId='feedListBasic'
        ref={feedListRef}
        listType='single'
        spanCount={1}
        scrollOrientation='vertical'
        refreshOptions={{
          enableRefresh: true,
          headerContent: renderRefreshHeader,
          onStartRefresh: handleRefresh,
        }}
        loadMoreFooter={renderLoadMoreFooter}
        noMoreDataFooter={renderNoMoreFooter}
        useRefactorList={true}
        bounces={false}
        upperThresholdItemCount={1}
        lowerThresholdItemCount={1}
        onScrollToLower={handleLoadMore}
      >
        <list-item item-key='demo-header'>
          <view className='demo-header' />
        </list-item>
        {items.map((item: LetterItem) => (
          <list-item key={item.key} item-key={item.key}>
            <RectangleCard
              letter={item.letter}
              height={500}
            />
          </list-item>
        ))}
        <list-item item-key='demo-footer'>
          <view className='demo-footer' />
        </list-item>
      </FeedList>
    </view>
  )
}

root.render(<App />)
export default App

```



## How to manage footer status

Use `loadMoreFooter` for the loading state and `noMoreDataFooter` when the feed
has reached the end. Switch between them through `changeHasMoreStatus`; this
footer state is independent from refresh state and list diff results.

**This is an example below: lynx-ui-feed-list**

**Entry:** `Basic`
**Bundle:** `dist/FeedListBasic.lynx.bundle`

```tsx {28-51,66-75,91-92}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useMemo, useRef, useState } from '@lynx-js/react'

import { FeedList } from '@lynx-js/lynx-ui'
import type { FeedListRef } from '@lynx-js/lynx-ui'

import { FEED_INITIAL, FEED_MORE, FEED_REFRESH } from './data'
import type { LetterItem } from './data'
import { RectangleCard } from '../shared/RectangleCard'
import { RefreshHeader } from '../shared/RefreshHeader'

import './index.css'

function App() {
  const feedListRef = useRef<FeedListRef>(null)
  const [items, setItems] = useState<LetterItem[]>(FEED_INITIAL)
  const noMoreData = useRef(false)
  const isLoadingMore = useRef(false)

  const renderRefreshHeader = useMemo(
    () => <RefreshHeader />,
    [],
  )

  const renderLoadMoreFooter = useMemo(
    () => (
      <list-item key='footer' item-key='footer' full-span>
        <view className='load-more-footer'>
          <image
            src='https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/loading.gif'
            className='load-more-footer__spinner'
          />
        </view>
      </list-item>
    ),
    [],
  )

  const renderNoMoreFooter = useMemo(
    () => (
      <list-item key='noMore' item-key='noMore' full-span>
        <text className='no-more-data-footer'>
          That's everything!
        </text>
      </list-item>
    ),
    [],
  )

  const handleRefresh = () => {
    setTimeout(() => {
      // Reset so load-more can fire again after refresh
      noMoreData.current = false
      isLoadingMore.current = false
      setItems(prev =>
        prev[0]?.key.startsWith('refresh-') ? FEED_INITIAL : FEED_REFRESH
      )
      feedListRef.current?.changeHasMoreStatus(true)
      feedListRef.current?.finishRefresh()
    }, 2000)
  }

  const handleLoadMore = () => {
    if (noMoreData.current || isLoadingMore.current) return
    isLoadingMore.current = true
    setTimeout(() => {
      noMoreData.current = true
      setItems(prev => [...prev, ...FEED_MORE])
      feedListRef.current?.changeHasMoreStatus(false)
      isLoadingMore.current = false
    }, 2000)
  }

  return (
    <view className='lunaris-dark demo-container'>
      <FeedList
        className='feed-list'
        listId='feedListBasic'
        ref={feedListRef}
        listType='single'
        spanCount={1}
        scrollOrientation='vertical'
        refreshOptions={{
          enableRefresh: true,
          headerContent: renderRefreshHeader,
          onStartRefresh: handleRefresh,
        }}
        loadMoreFooter={renderLoadMoreFooter}
        noMoreDataFooter={renderNoMoreFooter}
        useRefactorList={true}
        bounces={false}
        upperThresholdItemCount={1}
        lowerThresholdItemCount={1}
        onScrollToLower={handleLoadMore}
      >
        <list-item item-key='demo-header'>
          <view className='demo-header' />
        </list-item>
        {items.map((item: LetterItem) => (
          <list-item key={item.key} item-key={item.key}>
            <RectangleCard
              letter={item.letter}
              height={500}
            />
          </list-item>
        ))}
        <list-item item-key='demo-footer'>
          <view className='demo-footer' />
        </list-item>
      </FeedList>
    </view>
  )
}

root.render(<App />)
export default App

```



## How to trigger refresh directly

Use `startRefresh` when refresh should be driven by a command instead of a pull
gesture, such as a retry button or external filter change. After the data request
finishes, call `finishRefresh` to release the refresh header.

**This is an example below: lynx-ui-feed-list**

**Entry:** `Refresh`
**Bundle:** `dist/FeedListRefresh.lynx.bundle`

```tsx {17,45-62,73-77}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useEffect, useMemo, useRef, useState } from '@lynx-js/react'

import { Button, FeedList } from '@lynx-js/lynx-ui'
import type { FeedListRef } from '@lynx-js/lynx-ui'

import { FEED_INITIAL, FEED_REFRESH } from './data'
import type { LetterItem } from './data'
import { RectangleCard } from '../shared/RectangleCard'
import { RefreshHeader } from '../shared/RefreshHeader'
import './index.css'

function App() {
  const feedListRef = useRef<FeedListRef>(null)
  const refreshTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
  const refreshing = useRef(false)
  const showRefreshSet = useRef(false)

  const [items, setItems] = useState<LetterItem[]>(FEED_INITIAL)

  useEffect(() => {
    return () => {
      if (refreshTimer.current) {
        clearTimeout(refreshTimer.current)
      }
    }
  }, [])

  const refreshHeader = useMemo(
    () => <RefreshHeader text='Refreshing' />,
    [],
  )

  const startRefresh = () => {
    if (refreshing.current) {
      return
    }

    feedListRef.current?.startRefresh()
  }

  const handleStartRefresh = (
    _event: { triggeredBy: 'startRefresh' | 'drag' },
  ) => {
    refreshing.current = true

    if (refreshTimer.current) {
      clearTimeout(refreshTimer.current)
    }

    refreshTimer.current = setTimeout(() => {
      showRefreshSet.current = !showRefreshSet.current
      const nextItems = showRefreshSet.current ? FEED_REFRESH : FEED_INITIAL
      setItems(nextItems)

      feedListRef.current?.finishRefresh()
      refreshing.current = false
    }, 1500)
  }

  return (
    <view className='lunaris-dark demo-container'>
      <FeedList
        className='feed-list'
        listId='feedListRefresh'
        ref={feedListRef}
        listType='single'
        spanCount={1}
        scrollOrientation='vertical'
        refreshOptions={{
          enableRefresh: true,
          headerContent: refreshHeader,
          onStartRefresh: handleStartRefresh,
        }}
        useRefactorList={true}
        bounces={false}
      >
        <list-item item-key='demo-header'>
          <view className='demo-header' />
        </list-item>
        {items.map((item: LetterItem) => (
          <list-item key={item.key} item-key={item.key}>
            <RectangleCard
              letter={item.letter}
              height={500}
            />
          </list-item>
        ))}
        <list-item item-key='demo-footer'>
          <view className='demo-footer' />
        </list-item>
      </FeedList>
      <view className='demo-actions'>
        <Button
          className='action-button'
          onClick={() => {
            startRefresh()
          }}
        >
          <text className='action-button__text'>Refresh</text>
        </Button>
      </view>
    </view>
  )
}

root.render(<App />)
export default App

```


## FeedListProps

### Properties


### Events


### headerReleased


### refreshOffsetEvent


## FeedListRef


## RefreshEvent


## RefreshStateChange

## How to `Use refreshOptions`

The `useRefresh` hook extends the `useBounces hook`, leveraging its core functionality while adding several key capabilities:

- Supports a dedicated refreshHeader node (counterpart to `upperBounceItem`)

- Enables pause behavior at the `refreshHeader` position to simulate pull-to-refresh effects

We modified rebound curve to pause at the `refreshHeader` boundary (refresh zone edge), remaining there until manually released via `finishRefresh` after data loading completes.

A complete refresh consists of four distinct phases, and the events below map to those transitions.

### Events

Each phase triggers specific events:

- `onStartRefresh`: The key event in phase 3 for initiating data updates.

- `onRefreshOffsetChange`: Continuously fires while `refreshHeader` is visible, reporting its exposure percentage

- `onHeaderReleased`: Triggers when releasing drag after phase 2 (beginning rebound to `refreshHeader`)

- `onRefreshStateChange`: Fires during phase transitions, providing full state tracking:

  - `IDLE`: Default state (`refreshHeader` hidden)

  - `OVER_DRAG_RELEASE`: Matches `onHeaderReleased` timing (post-drag release)

  - `REFRESHING`: Matches `onStartRefresh` timing

  - `DRAGGING`: Continuous state while dragging with `refreshHeader` exposed



---
url: /lynx-ui/components/form.md
---

# 

# `<Form>`

A headless Form component for ReactLynx. It provides form context and a submit button that collects field values.
## Basic Usage

Use `<Form>` to manage form state, handle form validation, and submission

**This is an example below: lynx-ui-form**

**Entry:** `Basic`
**Bundle:** `dist/FormBasic.lynx.bundle` | Web: `dist/FormBasic.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import {
  CheckboxIndicator,
  FormField,
  FormRoot,
  FormSubmitButton,
  Radio,
  RadioIndicator,
  ScrollView,
} from '@lynx-js/lynx-ui'

import { formPageData } from './data'

import './index.css'

function App() {
  const [formValues, setFormValues] = useState<Record<string, unknown>>({})
  const [submitted, setSubmitted] = useState(false)

  return (
    <view className='demo-container lunaris-dark luna-gradient-berry'>
      <ScrollView scrollOrientation='vertical' className='demo-canvas'>
        <FormRoot
          onChanged={(values: Record<string, unknown>) => {
            setFormValues(values)
            setSubmitted(false)
          }}
          initialValues={{
            workspaceType: formPageData.workspaceTypeOptions[0]?.value ?? '',
            workspaceName: 'My Workspace',
            description: 'A place for collaboration',
          }}
        >
          <view className='form-container'>
            <text className='form-title'>{formPageData.title}</text>
            <text className='form-subtitle'>{formPageData.subtitle}</text>

            <view className='form-divider' />

            <text className='form-section-title'>Workspace type</text>
            <FormField as='RadioGroupRoot' name='workspaceType'>
              <view className='radio-group-container'>
                {formPageData.workspaceTypeOptions.map(({ label, value }) => (
                  <Radio className='radio-item' key={value} value={value}>
                    <RadioIndicator className='radio-indicator'>
                      <view className='radio-indicator-checked-item' />
                    </RadioIndicator>
                    <text className='form-label'>{label}</text>
                  </Radio>
                ))}
              </view>
            </FormField>

            <view className='form-divider' />

            <text className='form-section-title'>Workspace name</text>
            <view className='input-container'>
              <FormField
                as='Input'
                name='workspaceName'
                className='form-input'
              />
            </view>

            <text className='form-section-title'>Description</text>
            <view className='input-container'>
              <FormField as='Input' name='description' className='form-input' />
            </view>

            <view className='form-divider' />

            <FormField as='Checkbox' name='agreement' className='checkbox-item'>
              <CheckboxIndicator className='checkbox-indicator'>
                <view className='checkbox-indicator-checked-item' />
              </CheckboxIndicator>
              <text className='form-label'>
                I agree to the terms and conditions
              </text>
            </FormField>

            <FormSubmitButton
              onSubmit={(e) => {
                console.info(e)
                setSubmitted(true)
              }}
              className='submit-button'
            >
              <text className='submit-button-text'>Submit</text>
            </FormSubmitButton>

            <view className='form-divider' />

            {submitted && (
              <text className='form-submitted-hint'>Submitted ✓</text>
            )}
            <text className='form-values-display'>
              {JSON.stringify(formValues, null, 2)}
            </text>
          </view>
        </FormRoot>
      </ScrollView>
    </view>
  )
}

root.render(<App />)

export default App

```



## Avoiding Keyboard Overlap

Prevent the on-screen keyboard from obscuring the input field by automatically adjusting the view when the keyboard appears

**This is an example below: lynx-ui-form**

**Entry:** `KeyboardAware`
**Bundle:** `dist/FormKeyboardAware.lynx.bundle` | Web: `dist/FormKeyboardAware.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import {
  FormField,
  FormRoot,
  FormSubmitButton,
  KeyboardAwareResponder,
  KeyboardAwareRoot,
  KeyboardAwareTrigger,
} from '@lynx-js/lynx-ui'

import { demoItems } from './data'

import './index.css'

const initialValues = Object.fromEntries(
  demoItems
    .filter(
      (item) => item.type === 'input' || item.type === 'textarea',
    )
    .map((item) => [item.name, '']),
) as Record<string, string>

function App() {
  const [submitted, setSubmitted] = useState<Record<string, unknown> | null>(
    null,
  )

  return (
    <view className='demo-container lunaris-dark luna-gradient-berry'>
      <KeyboardAwareRoot androidStatusBarPlusBottomBarHeight={74}>
        <FormRoot
          initialValues={initialValues}
        >
          <KeyboardAwareResponder as='ScrollView' className='demo-canvas'>
            <view className='form-container'>
              <text className='form-title'>Keyboard-aware Form</text>
              <text className='form-subtitle'>
                Form fields stay visible while typing in a long scroll.
              </text>

              <view className='form-divider' />

              {demoItems.map((item) => {
                if (item.type === 'block') {
                  return <view key={item.key} className='block' />
                }

                if (item.type === 'input') {
                  return (
                    <KeyboardAwareTrigger key={item.key} offset={0}>
                      <view className='form-card'>
                        <text className='form-label'>{item.label}</text>
                        <view className='input-container'>
                          <FormField
                            as='Input'
                            name={item.name}
                            className='form-input'
                            placeholder={item.placeholder}
                          />
                        </view>
                      </view>
                    </KeyboardAwareTrigger>
                  )
                }

                return (
                  <KeyboardAwareTrigger key={item.key} offset={0}>
                    <view className='form-card'>
                      <text className='form-label'>{item.label}</text>
                      <view className='form-textarea-wrap'>
                        <FormField
                          as='TextArea'
                          name={item.name}
                          className='form-textarea'
                          placeholder={item.placeholder}
                          maxLines={12}
                          maxLength={600}
                        />
                      </view>
                    </view>
                  </KeyboardAwareTrigger>
                )
              })}

              <view className='form-divider' />

              <FormSubmitButton
                className='submit-button'
                onSubmit={(values) => setSubmitted(values)}
              >
                <text className='submit-button-text'>Submit</text>
              </FormSubmitButton>

              {submitted
                ? (
                  <view className='form-values-display'>
                    <text className='form-values-text'>
                      {JSON.stringify(submitted, null, 2)}
                    </text>
                  </view>
                )
                : null}

              <view className='bottom-spacer' />
            </view>
          </KeyboardAwareResponder>
        </FormRoot>
      </KeyboardAwareRoot>
    </view>
  )
}

root.render(<App />)
export default App

```



## Structure

```tsx
<FormRoot initialValues={}>
  <FormField as="RadioGroupRoot" name="select">
    {data.map(() => (
      <Radio>
        <RadioIndicator />
      </Radio>
    ))}
  </FormField>

  <FormField as="Input" name="input1" />
  <FormField as="Input" name="input2" />

  <FormSubmitButton onSubmit={handleSubmit}></FormSubmitButton>
</FormRoot>
```

## API

### FormRoot


### FormField


### FormSubmitButton



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-activeRender Prop`active`·Type`boolean`Whether the button is currently being pressed (and not disabled).
Applied when `status.active` is true.ui-disabledRender Prop`disabled`·Type`boolean`Whether the button is disabled.
Applied when `status.disabled` is true.


---
url: /lynx-ui/components/input.md
---

# 

# `<Input>`

A headless Input component for ReactLynx. It provides primitives for text entry and keyboard awareness.
Input component that supports controlled, uncontrolled, and keyboard avoidance capabilities. Use `<Input>` for single-line input and `<TextArea>` for multi-line input.

## Basic Usage

Use `<Input>` to render a single-line input field, and `<TextArea>` to render a multi-line text area.

**This is an example below: lynx-ui-input**

**Entry:** `Basic`
**Bundle:** `dist/InputBasic.lynx.bundle`

```tsx {35-40,45-51,60-63}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import { Input, TextArea } from '@lynx-js/lynx-ui'
import type { InputRef } from '@lynx-js/lynx-ui'

import './index.css'

function App() {
  const controlledInputRef = useRef<InputRef>(null)
  const uncontrolledInputRef = useRef<InputRef>(null)

  const [controlledValue, setControlledValue] = useState<string>(
    'controlledValue',
  )
  const uncontrolledValueRef = useRef<string>('demo-uncontrolledValue')

  return (
    <view className='demo-container lunaris-dark luna-gradient-rose'>
      <view className='demo-canvas'>
        {/* Input */}
        <view className='section'>
          <text className='title'>Input</text>

          <view className='field'>
            <text className='label'>Basic</text>
            <Input className='input' placeholder='Type here' />
          </view>

          <view className='field'>
            <text className='label'>Uncontrolled</text>
            <Input
              ref={uncontrolledInputRef}
              className='input'
              placeholder='Uncontrolled'
              defaultValue={uncontrolledValueRef.current}
            />
          </view>

          <view className='field'>
            <text className='label'>Controlled</text>
            <Input
              ref={controlledInputRef}
              className='input'
              placeholder='Controlled'
              value={controlledValue}
              onInput={setControlledValue}
            />
          </view>
        </view>

        {/* TextArea */}
        <view className='section'>
          <text className='title'>TextArea</text>

          <view className='textarea-wrap'>
            <TextArea
              className='textarea'
              placeholder='Write something...'
            />
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Avoiding Keyboard Overlap

Prevent the on-screen keyboard from obscuring the input field by automatically adjusting the view when the keyboard appears

**This is an example below: lynx-ui-input**

**Entry:** `KeyboardAwareView`
**Bundle:** `dist/InputKeyboardAwareView.lynx.bundle`

```tsx {23-81}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef } from '@lynx-js/react'

import {
  Input,
  KeyboardAwareResponder,
  KeyboardAwareRoot,
  KeyboardAwareTrigger,
  TextArea,
} from '@lynx-js/lynx-ui'
import type { InputRef } from '@lynx-js/lynx-ui'

import './index.css'

function App() {
  const input2Ref = useRef<InputRef>(null)

  return (
    <view className='container lunaris-dark luna-gradient-rose'>
      <KeyboardAwareRoot androidStatusBarPlusBottomBarHeight={74}>
        <KeyboardAwareResponder className='canvas' style={{ height: 'auto' }}>
          <view className='section'>
            <text className='title'>Keyboard Aware</text>
            <text className='subtitle'>
              Type <text className='code'>next</text> to jump focus.
            </text>
          </view>

          <KeyboardAwareTrigger offset={0}>
            <view className='card'>
              <text className='label'>Input 0</text>
              <Input
                className='input'
                placeholder="inputId: 'input0'"
                onInput={(value: string) => {
                  if (value === 'next') input2Ref.current?.focus()
                }}
              />
            </view>
          </KeyboardAwareTrigger>

          <KeyboardAwareTrigger>
            <view className='card'>
              <text className='label'>Input 1</text>
              <Input
                className='input'
                placeholder="Type 'next' to focus input2"
                onInput={(value: string) => {
                  if (value === 'next') input2Ref.current?.focus()
                }}
              />
            </view>
          </KeyboardAwareTrigger>

          <KeyboardAwareTrigger>
            <view className='card'>
              <text className='label'>Input 2</text>
              <Input
                ref={input2Ref}
                className='input'
                placeholder='Input'
              />
            </view>
          </KeyboardAwareTrigger>

          <KeyboardAwareTrigger offset={0}>
            <view className='card'>
              <text className='label'>TextArea</text>
              <view className='textarea-wrap'>
                <TextArea
                  className='textarea'
                  placeholder='Write something...'
                />
              </view>
            </view>
          </KeyboardAwareTrigger>
        </KeyboardAwareResponder>
      </KeyboardAwareRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

```jsx
<KeyboardAwareRoot>
  <view className='container'>
    <KeyboardAwareResponder>
      <KeyboardAwareTrigger>
          <Input
            style={{
              width: '100%',
              padding: '10px',
              backgroundColor: 'yellow',
            }}
          />
      </KeyboardAwareTrigger>
      <KeyboardAwareTrigger>
          <TextArea
            style={{
              width: '100%',
            }}
            placeholder="textareaId:'textarea2'"
          />
      </KeyboardAwareTrigger>
    </KeyboardAwareResponder>
  </view>
<KeyboardAwareRoot>
```

## API

## TextAreaProps


### KeyboardAwareTriggerProps


### KeyboardAwareRootProps


### KeyboardAwareResponderProps



### InputProps


## TextAreaRef


## KeyboardAwareResponderRef


## InputRef




---
url: /lynx-ui/components/lazy-component.md
---

# 

# `<LazyComponent>`

A LazyComponent for ReactLynx. It defers the loading of non-critical UI elements.
![](/static/image/lazy_component.1921d90308.jpeg)
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-lazy-component) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

## Basic Usage

`<LazyComponent>` renders its content after it's exposed, optimizing initial screen rendering performance

**This is an example below: lynx-ui-lazy-component**

**Entry:** `Basic`
**Bundle:** `dist/LazyComponentBasic.lynx.bundle`

```tsx {55-61}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Button, LazyComponent } from '@lynx-js/lynx-ui'

import './index.css'

function Item() {
  return (
    <view
      native-interaction-enabled={false}
      user-interaction-enabled={false}
      className='lazy-item'
    >
      {/* Render many lightweight cells to emphasize mount/layout work and render timing (not paint). */}
      {Array.from({ length: 1000 }).map((_, index) => (
        <view
          key={index}
          flatten={false}
          className='lazy-item-cell'
        />
      ))}
    </view>
  )
}

function App() {
  const [lazyVisible, setLazyVisible] = useState<boolean>(false)
  const [nonLazyVisible, setNonLazyVisible] = useState<boolean>(false)

  return (
    <view className='demo-container lunaris-dark luna-gradient-berry'>
      <view className='demo-canvas'>
        <text className='description'>
          Click the button. With 'Lazy', the solid block appears after the
          border. With 'Non-lazy', both appear at the same time.
        </text>
        <view className='panels'>
          <view className='panel'>
            <Button
              className='button'
              onClick={() => {
                setLazyVisible((v) => !v)
              }}
            >
              <text className='button-text'>Lazy</text>
            </Button>

            {lazyVisible
              ? (
                <view className='preview'>
                  <LazyComponent
                    scene='scene'
                    pid='pid'
                    estimatedStyle={{ width: '100%', height: '100%' }}
                  >
                    <Item />
                  </LazyComponent>
                </view>
              )
              : <view className='preview preview-dimmed' />}
          </view>

          <view className='panel'>
            <Button
              className='button'
              onClick={() => {
                setNonLazyVisible((v) => !v)
              }}
            >
              <text className='button-text'>Non-lazy</text>
            </Button>

            {nonLazyVisible
              ? (
                <view className='preview'>
                  <Item />
                </view>
              )
              : <view className='preview preview-dimmed' />}
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Adjust Visibility Margin

Adjust the visibility margin to render `<LazyComponent>` content earlier, optimizing the visual experience of scrolling and animations.

**This is an example below: lynx-ui-lazy-component**

**Entry:** `VisibilityMargin`
**Bundle:** `dist/LazyComponentVisibilityMargin.lynx.bundle`

```tsx {135}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useCallback, useEffect, useRef, useState } from '@lynx-js/react'

import { Button, LazyComponent, ScrollView, invokeById } from '@lynx-js/lynx-ui'

import './index.css'

const restartDelay = 1000
const itemCount = 30

function Item({ isEnd }: { isEnd?: boolean }) {
  return (
    <view className={`item${isEnd ? ' item-end' : ''}`}>
      <text className='item-text'>Item</text>
      {Array.from({ length: 5 }).map((_, index) => (
        <view className='item-sub-block' key={index} />
      ))}
    </view>
  )
}

function App() {
  const [mountEpoch, setMountEpoch] = useState(0)
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)

  const restart = useCallback(() => {
    setMountEpoch((value) => value + 1)
  }, [])

  useEffect(() => {
    if (timerRef.current) {
      clearTimeout(timerRef.current)
    }

    void invokeById('scrollview1', 'autoScroll', {
      rate: 3000,
      start: false,
    }).catch(() => {/* empty */})
    void invokeById('scrollview2', 'autoScroll', {
      rate: 3000,
      start: false,
    }).catch(() => {/* empty */})

    void invokeById('scrollview1', 'scrollTo', {
      index: 0,
      offset: 0,
      smooth: false,
    }).catch(() => {/* empty */})
    void invokeById('scrollview2', 'scrollTo', {
      index: 0,
      offset: 0,
      smooth: false,
    }).catch(() => {/* empty */})

    timerRef.current = setTimeout(() => {
      void invokeById('scrollview1', 'autoScroll', {
        rate: 3000,
        start: true,
      }).catch(() => {/* empty */})
      void invokeById('scrollview2', 'autoScroll', {
        rate: 3000,
        start: true,
      }).catch(() => {/* empty */})
    }, restartDelay)

    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current)
      }
    }
  }, [mountEpoch])

  return (
    <view className='container lunaris-dark luna-gradient-berry'>
      <view className='canvas'>
        <view className='toolbar'>
          <Button className='restart-button' onClick={restart}>
            <text className='restart-button-text'>Run Again</text>
          </Button>
        </view>

        <text className='description'>
          Compare LazyComponent visibility margin: the right column uses
          `bottom=200px`, so items mount up to 200px before entering the
          viewport.
        </text>

        <view className='columns'>
          {/* Left */}
          <view className='column'>
            <view className='info'>
              <text>bottom: 0px (mount when visible)</text>
            </view>

            <ScrollView
              scrollviewId='scrollview1'
              scrollOrientation='vertical'
              lazyOptions={{ enableLazy: false }}
              className='scrollview'
            >
              {Array.from({ length: itemCount }).map((_, index) => (
                <LazyComponent
                  key={`${mountEpoch}_${index}`}
                  scene='scene_1'
                  pid={`pid_1_${index}`}
                  bottom='0px'
                  estimatedStyle={{ width: '100%', height: '300px' }}
                >
                  <Item isEnd={index === itemCount - 1} />
                </LazyComponent>
              ))}
            </ScrollView>
          </view>

          {/* Right */}
          <view className='column'>
            <view className='info'>
              <text>bottom: 200px (preload before visible)</text>
            </view>

            <ScrollView
              scrollviewId='scrollview2'
              scrollOrientation='vertical'
              lazyOptions={{ enableLazy: false }}
              className='scrollview'
            >
              {Array.from({ length: itemCount }).map((_, index) => (
                <LazyComponent
                  key={`${mountEpoch}_${index}`}
                  scene='scene_2'
                  pid={`pid_2_${index}`}
                  bottom='200px'
                  estimatedStyle={{ width: '100%', height: '300px' }}
                >
                  <Item isEnd={index === itemCount - 1} />
                </LazyComponent>
              ))}
            </ScrollView>
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## LazyComponentProps




---
url: /lynx-ui/components/list.md
---

# 

# `<List>`

A virtualized List component for ReactLynx. Designed to render long lists of data.
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-list) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

## Basic Usage

**This is an example below: lynx-ui-list**

**Entry:** `Basic`
**Bundle:** `dist/ListBasic.lynx.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import { Button, List } from '@lynx-js/lynx-ui'
import type { ListRef } from '@lynx-js/lynx-ui'

import { ListItemCard } from '../shared/ListItemCard'
import './index.css'

const itemData = Array.from({ length: 16 }, (_, i) => ({
  id: String(i),
  label: String(i),
}))
const orientation = 'vertical'
const scrollToIndex = 7

function App() {
  const listRef = useRef<ListRef>(null)
  const [isAutoScrolling, setIsAutoScrolling] = useState(false)

  const handleAutoScrollClick = () => {
    setIsAutoScrolling(prev => !prev)
    listRef.current?.autoScroll('60px', !isAutoScrolling, true)
  }

  return (
    <view className='demo-container lunaris-dark'>
      <List
        className='list-container'
        listId='ListBasic'
        ref={listRef}
        listType='single'
        spanCount={1}
        scrollOrientation={orientation}
        useRefactorList={true}
        bounces={false}
      >
        <list-item item-key='demo-header'>
          <view className='demo-header' />
        </list-item>
        {itemData.map((item) => (
          <list-item key={item.id} item-key={item.id}>
            <ListItemCard
              letter={item.label}
              height={300}
            />
          </list-item>
        ))}
        <list-item item-key='demo-footer'>
          <view className='demo-footer' />
        </list-item>
      </List>
      <view className='button-container'>
        <Button
          className='button'
          onClick={() =>
            listRef.current?.scrollTo(true, 'middle', scrollToIndex, 0)}
        >
          <text className='button-text'>
            {`scrollTo(index ${scrollToIndex})`}
          </text>
        </Button>
        <Button
          className='button neutral'
          onClick={handleAutoScrollClick}
        >
          <text className='button-text neutral'>autoScroll()</text>
        </Button>
        <Button
          className='button subtle'
          onClick={() => console.log(listRef.current?.getVisibleCells())}
        >
          <text className='button-text subtle'>getVisibleCells()</text>
        </Button>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## ListProps

### Properties


### Events


### diffResultDetails


### LayoutCompleteEvent


### layoutCompleteEventDetail


### ListItemInfo


### ListItemSnapAlignment


## ListRef




---
url: /lynx-ui/components/overlay.md
---

# 

# `Overlay`

An Overlay component for ReactLynx. It renders content in a native overlay layer above the main view tree.
OverlayView is a drop-in replacement for `<overlay>`. Prefer using it over raw `<overlay>` to reduce setup work and avoid platform quirks and mistakes.

It can render either a plain `view` (when `container` is not provided) or an `<overlay>` (when `container` is provided). Prefer using `OverlayView` over raw `<overlay>`.

## Basic Usage

```tsx
import { OverlayView } from '@lynx-js/lynx-ui';

export function Example() {
  return (
    <OverlayView container="default">
      <view className="panel">
        <text>Overlay content</text>
      </view>
    </OverlayView>
  );
}
```

## Structure

```tsx
<OverlayView>
  <view />
</OverlayView>
```

## OverlayViewProps


## OverlayViewRef




---
url: /lynx-ui/components/popover.md
---

# 

# `Popover`

A headless Popover component for ReactLynx. It provides primitives for positioning and anchor tracking.
## Basic Usage

**This is an example below: lynx-ui-popover**

**Entry:** `Basic`
**Bundle:** `dist/PopoverBasic.lynx.bundle` | Web: `dist/PopoverBasic.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        defaultShow={true}
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
          <PopoverPositioner
            placement='bottom'
            placementOffset={12}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              <OptionsMenu />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Extra Anchor

If you want to add an extra anchor, you can use the PopoverAnchor Component.

**This is an example below: lynx-ui-popover**

**Entry:** `ExtraAnchor`
**Bundle:** `dist/PopoverExtraAnchor.lynx.bundle` | Web: `dist/PopoverExtraAnchor.web.bundle`

```tsx {29}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverAnchor,
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
        defaultShow={true}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
        </PopoverTrigger>
        <PopoverAnchor className='popover-anchor'>
          <text className='popover-anchor-text'>Anchor</text>
          <PopoverPositioner
            placement='bottom-start'
            placementOffset={12}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              {
                /* In ExtraAnchor scenario, PopoverContent is not wrapped by PopoverTrigger,
               *  so tap-to-close is not supported. Use a different description accordingly.
               */
              }
              <OptionsMenu description='Only the trigger dismisses this popover. Tapping the anchor or content has no effect.' />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverAnchor>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Cross axis offset adjustment

Use 'crossAxisOffset' on PopoverPositioner to set the skidding offset of the floating element.

**This is an example below: lynx-ui-popover**

**Entry:** `OffsetAdjustment`
**Bundle:** `dist/PopoverOffsetAdjustment.lynx.bundle` | Web: `dist/PopoverOffsetAdjustment.web.bundle`

```tsx {29-30}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  PopoverContent,
  PopoverPositioner,
  PopoverRoot,
  PopoverTrigger,
} from '@lynx-js/lynx-ui'

import { EllipsisIcon, OptionsMenu } from '../shared/index.js'
import './index.css'

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <PopoverRoot
        onClose={() => console.info('dismissed!')}
        onOpen={() => console.info('shown!')}
        defaultShow={true}
      >
        <PopoverTrigger className='popover-trigger'>
          <EllipsisIcon />
          <PopoverPositioner
            placement='bottom'
            placementOffset={12}
            crossAxisOffset={40}
            autoAdjust='shift'
            className='popover-positioner'
          >
            <PopoverContent className='popover-content'>
              <OptionsMenu />
            </PopoverContent>
          </PopoverPositioner>
        </PopoverTrigger>
      </PopoverRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

```jsx
<PopoverRoot>
  <PopoverTrigger />
  <PopoverAnchor>
    <PopoverPositioner>
      <PopoverContent />
      <PopoverArrow />
    </PopoverPositioner>
  </PopoverAnchor>
</PopoverRoot>
```

## API

### PopoverRoot

The root component of the Popover, containing all of its child components.


### PopoverTrigger

The element that triggers the Popover to show.


### PopoverPositioner

Helps position the Content and Arrow correctly.



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-openRender Prop`open`·Type`boolean`The popper is opened.
Applied when `status.open` is true.ui-closedRender Prop`closed`·Type`boolean`The popper is closed.
If it's force mounted, the initial status will be closed.
Applied when `status.closed` is true.ui-leavingRender Prop`leaving`·Type`boolean`The popper is performing the leaving animation. Takes effect when transition:true.
Applied when `status.leaving` is true.ui-enteringRender Prop`entering`·Type`boolean`The popper is performing the entering animation. Takes effect when transition:true.
Applied when `status.entering` is true.ui-animatingRender Prop`animating`·Type`boolean`The popper is doing the animations. Takes effect when transition:true.
Applied when `status.animating` is true.
### PopoverContent

The content of the Popover.


### PopoverArrow

The arrow of the Popover.




---
url: /lynx-ui/components/radio-group.md
---

# 

# `RadioGroup`

A headless RadioGroup component for ReactLynx. It manages single-selection state across a group of radio buttons.
## Basic Usage

**This is an example below: lynx-ui-radio-group**

**Entry:** `Basic`
**Bundle:** `dist/RadioGroupBasic.lynx.bundle` | Web: `dist/RadioGroupBasic.web.bundle`

```tsx {21-41}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Radio, RadioGroupRoot, RadioIndicator } from '@lynx-js/lynx-ui'
import { clsx } from 'clsx'

import { hitSlop } from '../shared/hitSlop'
import './index.css'

const radioTags = ['lunaris-dark', 'lunaris-light', 'luna-dark', 'luna-light']

function App() {
  const [value, setValue] = useState(radioTags[0])

  return (
    <view className={clsx('demo-container luna-gradient-rose', value)}>
      <view className='demo-canvas'>
        <RadioGroupRoot
          value={value}
          onValueChange={setValue}
        >
          <view className='radio-group-root'>
            {radioTags.map((tag) => (
              <view key={tag} className='radio-option'>
                <Radio
                  className='radio-item'
                  value={tag}
                  radioProps={hitSlop}
                >
                  <RadioIndicator className='radio-indicator'>
                    <view className='radio-indicator-dot' />
                  </RadioIndicator>
                </Radio>
                <text className='label'>{tag}</text>
              </view>
            ))}
          </view>
        </RadioGroupRoot>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Disabled

RadioGroup supports disabling the entire group or individual options.

**This is an example below: lynx-ui-radio-group**

**Entry:** `Disabled`
**Bundle:** `dist/RadioGroupDisabled.lynx.bundle` | Web: `dist/RadioGroupDisabled.web.bundle`

```tsx {32-36,42-51}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Button, Radio, RadioGroupRoot, RadioIndicator } from '@lynx-js/lynx-ui'
import { clsx } from 'clsx'

import { hitSlop } from '../shared/hitSlop'
import './index.css'

const radioTags = ['Dawn', 'Bloom', 'Glow', 'Fade', 'Rest']

function App() {
  const [value, setValue] = useState(radioTags[0])
  const [disabled, setDisabled] = useState(false)

  return (
    <view className='demo-container lunaris-dark luna-gradient-rose'>
      <view className='demo-canvas'>
        <view className='section'>
          <text className='label'>
            Status: {disabled ? 'Disabled' : 'Enabled'}
          </text>
          <text className='label'>
            Selected Value: {value}
          </text>
        </view>

        <view className='section'>
          <RadioGroupRoot
            value={value}
            onValueChange={setValue}
            disabled={disabled}
          >
            <view className='radio-group-root'>
              {radioTags.map((tag) => {
                const itemDisabled = tag === 'Glow' // item-level disabled
                return (
                  <view key={tag} className='radio-option'>
                    <Radio
                      className='radio-item'
                      value={tag}
                      disabled={itemDisabled}
                      radioProps={hitSlop}
                    >
                      <RadioIndicator className='radio-indicator'>
                        <view className='radio-indicator-dot' />
                      </RadioIndicator>
                    </Radio>
                    <text
                      className={clsx(
                        'label',
                        (itemDisabled || disabled) && 'disabled',
                      )}
                    >
                      {tag}
                      {itemDisabled ? ' (disabled)' : ''}
                    </text>
                  </view>
                )
              })}
            </view>
          </RadioGroupRoot>
        </view>
        {/* toggle group disabled */}
        <view className='section'>
          <Button className='button' onClick={() => setDisabled((v) => !v)}>
            <text className='button-text'>
              {disabled ? 'Enable group' : 'Disable group'}
            </text>
          </Button>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

```jsx
<RadioGroupRoot>
  <Radio>
    <RadioIndicator />
  </Radio>
</RadioGroupRoot>
```

## API

### RadioGroupRoot

The root component of the RadioGroup, containing all of its child components.


### Radio

The item inside RadioGroup.


### RadioIndicator

The check slot indicating this Radio is now selected. Normally a circle. It's children will only be rendered when selected so it can be a custom inner selected indicator. Can be a ReactNode or a render function returns a ReactNode.




---
url: /lynx-ui/components/scroll-view.md
---

# 

# `<Scrollview>`

A ScrollView component for ReactLynx. It provides scrolling primitives and bounce handling.
- Lazy-loading optimized container powered by LazyComponent, designed to reduce first-screen rendering time

- Built-in platform-consistent bounces behavior (iOS/Android alignment)

:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-scroll-view) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

Basic UsageUnder the `bounceableOptions`## Basic Usage

Use `<ScrollView>` to enable scrollable content.

**This is an example below: lynx-ui-scroll-view**

**Entry:** `Basic`
**Bundle:** `dist/ScrollViewBasic.lynx.bundle`

```tsx {17-23}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import { ScrollView } from '@lynx-js/lynx-ui'

import { CircleLetterCard } from './CircleLetterCard'
import './index.css'

const LETTERS = ['L', 'Y', 'N', 'X', 'U', 'I', 'L', 'Y', 'N', 'X', 'J', 'S']

function App() {
  return (
    <view className='demo-container lunaris-dark'>
      <ScrollView scrollOrientation='horizontal' className='scroll-view'>
        <view className='scroll-view-content'>
          {LETTERS.map((letter, i) => (
            <CircleLetterCard letter={letter} key={`circle-${i}`} />
          ))}
        </view>
      </ScrollView>
    </view>
  )
}

root.render(<App />)

export default App

```


## ScrollViewProps

### Properties


### Events


### BounceableBasicProps



### scrollToBouncesInfo

## How to understand properties in useBounces

Let's see how useBounces is implemented. This hook can be attached to any scrollable container.

### Inputs and Outputs

First, let's treat this hook as a black box that receives component settings and returns a series of methods to handle scroll container events:

- Input: `options`

- id: The scrollable container's id (required to avoid conflicts between identical containers on the same page).

- `scrollOrientation`: Container scrolling direction (horizontal or vertical).

- `bounceableOptions`: Additional hook configuration:

- `enableBounces`: Whether to enable the bounce effect.

- `startBounceTriggerDistance`/`endBounceTriggerDistance`: Thresholds for triggering `onScrollToBounces` (e.g., for "swipe-to-navigate" scenarios).

- `enableBounceEventInFling`: Whether to trigger bounce effects during momentum scrolling.

- `upperBounceItem`/`lowerBounceItem`: Content displayed in bounce areas.

- `alwaysBouncing`: Enables bounce effects even when the container isn't scrollable.

- `singleSidedBounce`: Restricts bounce effects to one side only.

- `onScrollToBounces`: Triggered when bounce distance exceeds thresholds (filters minor bounces).

- Output: Methods for binding to scroll containers:

- `main-thread:bindtouchstart`/`main-thread:bindtouchend`/`main-thread:bindtouchmove`: Handles touch events.

- `main-thread:bindlayoutchange`: Tracks container dimensions.

- `main-thread:bindscroll`/`main-thread:bindscrollend`: Handles scroll events.

- `onUpperExposure`/`onUpperDisexposure`/`onLowerExposure`/`onLowerDisexposure`: Manages container boundary states (bounce only occurs at edges).

### Scroll Simulation

We use `MTS` and `transform` to simulate bounce effects:

1. Locate nodes via `lynx.querySelector`:

```tsx
lynx.querySelector(`#${containerID}`)
```

2. Apply `transform` based on scroll curves from touch events:

useBounces divides scrolling into three phases:

1. Rubber-band effect during touchmove

2. Momentum scrolling

3. Bounce-back effect

### Using `bounceableOptions`

#### `onScrollToBounces` with distance thresholds

This event triggers only after completed bounces, requiring:

1. The container must be in a bounce zone at touchEnd (not in neutral area).

2. The bounce effect must fully complete (container returns to edge).
   The event fires only if the maximum bounce distance exceeds the threshold.

#### `enableBounceEventInFling`

When enabled (default), momentum scrolling can trigger bounces if the container reaches edges mid-fling. Disable this for bounce effects that require explicit touch gestures.

#### Where will `upperBounceItem`/`lowerBounceItem` show up？

These appear exclusively in bounce zones. When unset, the translated container reveals underlying content.

#### `alwaysBouncing`

Forces edge detection even when the container isn't scrollable, allowing bounce effects without actual scrolling.
## 




---
url: /lynx-ui/components/sheet.md
---

# 

# `<Sheet>`

A directional Sheet component for ReactLynx. It supports bottom-sheet and side-drawer semantics with drag interactions and snap point primitives.
- Supports controlled and uncontrolled visibility.
- Supports snap points, including percentages and content-driven height.
- Supports imperative control through `SheetRootRef`.

:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-sheet) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

Sheet is a sliding surface for contextual actions, detail panels, and transient
workflows. It supports bottom sheets, top sheets, side drawers, snap points,
dragging, backdrop dismissal, and both controlled and imperative usage.

## Basic Usage

Start with `SheetRoot`, `SheetView`, `SheetBackdrop`, and `SheetContent`. Put
the visual surface on `SheetContent`, then use the backdrop and drag gestures for
natural dismissal.

**This is an example below: lynx-ui-sheet**

**Entry:** `Basic`
**Bundle:** `dist/SheetBasic.lynx.bundle`

```tsx {26-56}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'
import './index.css'

const snapPoints = ['50%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Basic Sheet</text>
      <TriggerButton
        onClick={() => sheetRef.current?.open()}
        text='Open Sheet'
      />
      <SheetRoot
        ref={sheetRef}
        snapPoints={snapPoints}
        initialSnap={0}
        onOpen={() => console.log('Sheet opened')}
        onClose={() => console.log('Sheet closed')}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>Basic Sheet</text>
              <text className='info-text'>
                Simple uncontrolled sheet. Drag or tap backdrop to dismiss.
              </text>
              <ActionButton
                onClick={() => sheetRef.current?.close()}
                text='Close'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Auto Height

Use the `fit` snap point when the panel height should follow its content. This
works well for menus, short forms, and content whose height is not known ahead of
time.

**This is an example below: lynx-ui-sheet**

**Entry:** `AutoHeight`
**Bundle:** `dist/SheetAutoHeight.lynx.bundle`

```tsx {18-19,48-50,57-72}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'
import './index.css'

const fitSnapPoints = ['fit']
const fitAndPercentSnapPoints = ['fit', '80%']
const claimedGestureAngles: [number, number][] = [[-135, -45], [45, 135]]

const longText =
  'The Sheet component supports autoHeight mode, where the height is dynamically calculated based on its content. '
    .repeat(10)

function App() {
  const fitSheetRef = useRef<SheetRootRef>(null)
  const fitAndPercentSheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Sheet Auto Height</text>

      <view className='button-group'>
        <TriggerButton
          onClick={() => fitSheetRef.current?.open()}
          text='Open Fit Sheet'
        />
        <TriggerButton
          onClick={() => fitAndPercentSheetRef.current?.open()}
          text='Open Fit + 80% Sheet'
        />
      </view>

      <SheetRoot
        ref={fitSheetRef}
        onShowChange={(show) => {
          console.log('fit show change', show)
        }}
        onOpen={() => {
          console.log('fit open change')
        }}
        onClose={() => {
          console.log('fit close change')
        }}
        snapPoints={fitSnapPoints}
        initialSnap={0}
        claimedGestureAngles={claimedGestureAngles}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('fit snap change', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Fit Sheet with Long Content
              </text>
              <text className='info-text'>snapPoints=["fit"]</text>
              <text className='info-text'>{longText}</text>
              <ActionButton
                onClick={() => fitSheetRef.current?.close()}
                text='Close via Ref'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={fitAndPercentSheetRef}
        snapPoints={fitAndPercentSnapPoints}
        initialSnap={0}
        claimedGestureAngles={claimedGestureAngles}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('fit + 80% snap change', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Fit Sheet with Percent Snap
              </text>
              <text className='info-text'>snapPoints=["fit", "80%"]</text>
              <text className='info-text'>
                The fit snap uses measured content height, while 80% resolves
                against the viewport height.
              </text>
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.snapTo(0)}
                text='Snap to fit'
              />
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.snapTo(1)}
                text='Snap to 80%'
              />
              <ActionButton
                onClick={() => fitAndPercentSheetRef.current?.close()}
                text='Close via Ref'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Controlled

Use `show` with `onShowChange` when the open state belongs to the page. This is
the right model when other UI, analytics, or navigation logic must stay in sync
with the sheet.

**This is an example below: lynx-ui-sheet**

**Entry:** `Controlled`
**Bundle:** `dist/SheetControlled.lynx.bundle`

```tsx {23-24,32-42,36-54}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef, useState } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, SnapButton, TriggerButton } from '../shared/index.js'

import './index.css'

const snapPoints = ['40%', '80%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)
  // Fully controlled state - parent manages show/hide
  const [show, setShow] = useState(false)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Controlled Sheet</text>
      <text className='subtitle-text'>
        show: {show ? 'true' : 'false'}
      </text>
      <TriggerButton
        onClick={() => setShow(s => !s)}
        text={show ? 'Opened' : 'Open (setShow(true))'}
      />
      <SheetRoot
        ref={sheetRef}
        show={show}
        onShowChange={(newShow) => {
          console.log('onShowChange:', newShow)
          setShow(newShow)
        }}
        onOpen={() => {
          console.log('onOpen - sheet fully opened')
        }}
        onClose={() => {
          console.log('onClose - sheet fully closed')
        }}
        snapPoints={snapPoints}
        initialSnap={0}
        onSnapChange={(snapIndex, snapValue) => {
          console.log('onSnapChange:', snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
            snapAnimation={{ type: 'spring', stiffness: 300, damping: 25 }}
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Controlled Sheet
              </text>
              <text className='info-text'>
                The parent component manages the `show` state. Backdrop taps and
                gestures trigger `onShowChange`.
              </text>
              <view className='button-group'>
                <SnapButton
                  onClick={() => sheetRef.current?.snapTo(0)}
                  text='Snap to 40%'
                />
                <SnapButton
                  onClick={() => sheetRef.current?.snapTo(1)}
                  text='Snap to 80%'
                />
              </view>

              <ActionButton
                onClick={() => setShow(false)}
                text='Close (setShow(false))'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Side

Use `side` to choose whether Sheet behaves like a bottom panel, top panel, or
drawer. Prefer `start` and `end` for layouts that should follow RTL, and `left`
or `right` when the physical edge must stay fixed.

**This is an example below: lynx-ui-sheet**

**Entry:** `Directional`
**Bundle:** `dist/SheetDirectional.lynx.bundle`

```tsx {95-119,134-139,173-204}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, TriggerButton } from '../shared/index.js'

import './index.css'

function DrawerSection(
  props: {
    title: string
    description: string
    note: string
    close: () => void
    surfaceClassName: string
    innerClassName: string
  },
) {
  const {
    title,
    description,
    note,
    close,
    surfaceClassName,
    innerClassName,
  } = props

  return (
    <SheetContent
      className={surfaceClassName}
      innerClassName={innerClassName}
    >
      <view className='drawer-panel'>
        <text className='header-text'>{title}</text>
        <text className='info-text'>{description}</text>
        <text className='info-text'>{note}</text>
        <ActionButton onClick={close} text='Close Drawer' />
      </view>
    </SheetContent>
  )
}

function App() {
  const leftDrawerRef = useRef<SheetRootRef>(null)
  const rightDrawerRef = useRef<SheetRootRef>(null)
  const startDrawerRef = useRef<SheetRootRef>(null)
  const endDrawerRef = useRef<SheetRootRef>(null)
  const rtlLeftDrawerRef = useRef<SheetRootRef>(null)
  const rtlRightDrawerRef = useRef<SheetRootRef>(null)
  const topSheetRef = useRef<SheetRootRef>(null)
  const bottomSheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Directional Sheet</text>
      <text className='subtitle-text'>
        Left and right are physical sides. Start and end are logical sides that
        can flip with enableRTL.
      </text>
      <view className='button-group'>
        <TriggerButton
          onClick={() => leftDrawerRef.current?.open()}
          text='Open Left Drawer'
        />
        <TriggerButton
          onClick={() => rightDrawerRef.current?.open()}
          text='Open Right Drawer'
        />
        <TriggerButton
          onClick={() => startDrawerRef.current?.open()}
          text='Open Start Drawer'
        />
        <TriggerButton
          onClick={() => endDrawerRef.current?.open()}
          text='Open End Drawer'
        />
        <TriggerButton
          onClick={() => rtlLeftDrawerRef.current?.open()}
          text='Open RTL Left Drawer'
        />
        <TriggerButton
          onClick={() => rtlRightDrawerRef.current?.open()}
          text='Open RTL Right Drawer'
        />
        <TriggerButton
          onClick={() => topSheetRef.current?.open()}
          text='Open Top Sheet'
        />
        <TriggerButton
          onClick={() => bottomSheetRef.current?.open()}
          text='Open Bottom Sheet'
        />
      </view>

      <SheetRoot
        ref={leftDrawerRef}
        side='left'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Left Drawer'
            description='This drawer uses side="left" with snapPoints=["fit"].'
            note='Use physical sides when the panel should stay on that edge in both LTR and RTL.'
            close={() => leftDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-left'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rightDrawerRef}
        side='right'
        snapPoints={['72%']}
        initialSnap={0}
        rubberBand={true}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Right Drawer'
            description='This drawer uses side="right" with a percentage snap point.'
            note='The 72% snap point resolves against viewport width instead of viewport height.'
            close={() => rightDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={startDrawerRef}
        side='start'
        enableRTL={true}
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='Start Drawer'
            description='This drawer uses side="start" with snapPoints=["fit"].'
            note='This example sets enableRTL, so start resolves to right. Disable it to make start resolve to left.'
            close={() => startDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={endDrawerRef}
        side='end'
        snapPoints={['72%']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='End Drawer'
            description='This drawer uses side="end" with a percentage snap point.'
            note='Without enableRTL, end resolves to right. Turn enableRTL on to make end resolve to left.'
            close={() => endDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rtlLeftDrawerRef}
        side='left'
        enableRTL={true}
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='RTL Left Drawer'
            description='This drawer uses side="left" with enableRTL.'
            note='Physical left stays left, while the Sheet viewport direction becomes RTL.'
            close={() => rtlLeftDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-left'
            innerClassName='drawer-inner-content drawer-inner-content-fit'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={rtlRightDrawerRef}
        side='right'
        enableRTL={true}
        snapPoints={['72%']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <DrawerSection
            title='RTL Right Drawer'
            description='This drawer uses side="right" with enableRTL.'
            note='Physical right stays right, while the Sheet viewport direction becomes RTL.'
            close={() => rtlRightDrawerRef.current?.close()}
            surfaceClassName='drawer-content drawer-content-right'
            innerClassName='drawer-inner-content drawer-inner-content-percent'
          />
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={topSheetRef}
        side='top'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='top-sheet-shell'
            innerClassName='top-sheet-content'
          >
            <view className='top-sheet-panel'>
              <text className='header-text'>Top Sheet</text>
              <text className='info-text'>
                This sheet uses side="top". Its fit snap point resolves from
                measured height.
              </text>
              <ActionButton
                onClick={() => topSheetRef.current?.close()}
                text='Close Top Sheet'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>

      <SheetRoot
        ref={bottomSheetRef}
        side='bottom'
        snapPoints={['fit']}
        initialSnap={0}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='bottom-sheet-shell'
            innerClassName='bottom-sheet-content'
          >
            <SheetHandle className='bottom-sheet-handle' />
            <view className='bottom-sheet-panel'>
              <text className='header-text'>Bottom Sheet</text>
              <text className='info-text'>
                This sheet uses the default bottom side. Its fit snap point
                resolves from measured height.
              </text>
              <ActionButton
                onClick={() => bottomSheetRef.current?.close()}
                text='Close Bottom Sheet'
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Imperative

Use `SheetRootRef` when a parent needs to command the sheet directly. Methods
such as `open`, `close`, `snapTo`, `expand`, and `collapse` are useful for
toolbar actions and coordinated multi-step flows.

**This is an example below: lynx-ui-sheet**

**Entry:** `Imperative`
**Bundle:** `dist/SheetImperative.lynx.bundle`

```tsx {22,28-34,63-89}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.
import { root, useRef } from '@lynx-js/react'

import {
  SheetBackdrop,
  SheetContent,
  SheetHandle,
  SheetRoot,
  SheetView,
} from '@lynx-js/lynx-ui'
import type { SheetRootRef } from '@lynx-js/lynx-ui'

import { ActionButton, SnapButton, TriggerButton } from '../shared/index.js'

import './index.css'

const snapPoints = ['40%', '60%', '90%']

function App() {
  const sheetRef = useRef<SheetRootRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <text className='title-text'>Imperative Sheet</text>

      <TriggerButton
        text='Open Sheet (via ref)'
        onClick={() => sheetRef.current?.open()}
      />

      <SheetRoot
        ref={sheetRef}
        onShowChange={(show) => {
          console.log('show change', show)
        }}
        onOpen={() => {
          console.log('open change')
        }}
        onClose={() => {
          console.log('close change')
        }}
        snapPoints={snapPoints}
        initialSnap={0}
        onSnapChange={(snapIndex, snapValue) => {
          console.log(snapIndex, snapValue)
        }}
      >
        <SheetView className='sheet-viewport'>
          <SheetBackdrop className='sheet-overlay' clickToClose={true} />
          <SheetContent
            className='sheet-content'
            innerClassName='sheet-inner-content'
            snapAnimation={{ type: 'spring', stiffness: 300, damping: 20 }}
          >
            <SheetHandle className='sheet-handle' />
            <view className='control-panel'>
              <text className='header-text'>
                Imperative Methods
              </text>

              <view className='button-group'>
                <SnapButton
                  text='40%'
                  onClick={() => sheetRef.current?.snapTo(0)}
                />
                <SnapButton
                  text='60%'
                  onClick={() => sheetRef.current?.snapTo(1)}
                />
                <SnapButton
                  text='90%'
                  onClick={() => sheetRef.current?.snapTo(2)}
                />
                <SnapButton
                  text='Expand (Max)'
                  onClick={() => sheetRef.current?.expand()}
                />
                <SnapButton
                  text='Collapse (Min)'
                  onClick={() => sheetRef.current?.collapse()}
                />
              </view>

              <ActionButton
                text='Close'
                onClick={() => sheetRef.current?.close()}
              />
            </view>
          </SheetContent>
        </SheetView>
      </SheetRoot>
    </view>
  )
}

root.render(<App />)

export default App

```



## Structure

```jsx
<SheetRoot>
  <SheetView>
    <SheetBackdrop />
    <SheetContent>
      <SheetHandle />
    </SheetContent>
  </SheetView>
</SheetRoot>
```

## API

### SheetRoot

The root component of the Sheet, containing all of its child components.


### SheetBackdrop

The backdrop mask of the Sheet.


### SheetView

The view container of the Sheet. Can be `x-overlay-ng` or `view`.
Controls the Sheet's overlay layer and stacking order.


### SheetContent

The main content of the Sheet.




---
url: /lynx-ui/components/sortable.md
---

# 

# `<Sortable>`

A headless Sortable list component for ReactLynx. It provides list reordering primitives via main-thread animations.
## Basic Usage

**This is an example below: lynx-ui-sortable**

**Entry:** `Basic`
**Bundle:** `dist/SortableBasic.lynx.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import './index.css'

import { SortableItem, SortableItemArea, SortableRoot } from '@lynx-js/lynx-ui'
import type { SortableData } from '@lynx-js/lynx-ui'

import type { SortableDemoItem } from '../shared/data'
import { createDemoData } from '../shared/data'

export function App() {
  const [data, setData] = useState<SortableData<SortableDemoItem>[]>(
    createDemoData,
  )

  return (
    <view
      className='sortable-root lunaris-dark'
      id='sortableContainer'
      // Required: establish a stacking context for sortable drag layers
      style={{ zIndex: '0' }}
    >
      <SortableRoot
        data={data}
        boundaryId='sortableContainer'
        onSortEnd={(sortedData: SortableData<SortableDemoItem>[]) =>
          setData(sortedData)}
      >
        {(item: SortableData<SortableDemoItem>) => {
          const { id, tone } = item.dataItem

          return (
            <SortableItem
              key={item.getSortingKey()}
              as='DraggableRoot'
              className={`sortable-item sortable-item--${id}`}
              sortingKey={item.getSortingKey()}
            >
              <SortableItemArea className='sortable-item-area'>
                <text className={`drag-here-text drag-here-text--${tone}`}>
                  Drag Here
                </text>
              </SortableItemArea>
            </SortableItem>
          )
        }}
      </SortableRoot>
    </view>
  )
}

root.render(<App />)

```



## Drag Without a boundary

If no boundaryId is provided, the SortableItem can be dragged freely without restrictions.

**This is an example below: lynx-ui-sortable**

**Entry:** `NoBoundary`
**Bundle:** `dist/SortableNoBoundary.lynx.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import './index.css'

import { SortableItem, SortableRoot } from '@lynx-js/lynx-ui'
import type { SortableData } from '@lynx-js/lynx-ui'

import type { SortableDemoItem } from '../shared/data'
import { createDemoData } from '../shared/data'

export function App() {
  const [data, setData] = useState<SortableData<SortableDemoItem>[]>(
    createDemoData,
  )

  return (
    <view className='sortable-root lunaris-dark'>
      <SortableRoot
        data={data}
        onSortEnd={(sortedData: SortableData<SortableDemoItem>[]) => {
          setData(sortedData)
        }}
      >
        {(item: SortableData<SortableDemoItem>) => {
          const { id, tone } = item.dataItem
          return (
            <SortableItem
              key={item.getSortingKey()}
              className={`sortable-item sortable-item--${id}`}
              sortingKey={item.getSortingKey()}
            >
              <text className={`drag-here-text drag-here-text--${tone}`}>
                {id}
              </text>
            </SortableItem>
          )
        }}
      </SortableRoot>
    </view>
  )
}

root.render(<App />)

```



## Disable all dragging and sorting behavior

**This is an example below: lynx-ui-sortable**

**Entry:** `DisableSorting`
**Bundle:** `dist/SortableDisableSorting.lynx.bundle`

```tsx {32}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import './index.css'

import { SortableItem, SortableRoot } from '@lynx-js/lynx-ui'
import type { SortableData } from '@lynx-js/lynx-ui'

import type { SortableDemoItem } from '../shared/data'
import { createDemoData } from '../shared/data'

export function App() {
  const [data, setData] = useState<SortableData<SortableDemoItem>[]>(
    createDemoData,
  )

  return (
    <view
      className='sortable-root lunaris-dark'
      id='sortableContainer'
      // Required: establish a stacking context for sortable drag layers
      style={{ zIndex: '0' }}
    >
      <SortableRoot
        data={data}
        boundaryId='sortableContainer'
        onSortEnd={(sortedData: SortableData<SortableDemoItem>[]) =>
          setData(sortedData)}
        enableSorting={false}
      >
        {(item: SortableData<SortableDemoItem>) => {
          const { id, tone } = item.dataItem

          return (
            <SortableItem
              key={item.getSortingKey()}
              className={`sortable-item sortable-item--${id}`}
              sortingKey={item.getSortingKey()}
            >
              <text className={`drag-here-text drag-here-text--${tone}`}>
                {id}
              </text>
            </SortableItem>
          )
        }}
      </SortableRoot>
    </view>
  )
}

root.render(<App />)

```



## Structure

The whole SortableItem is draggable.

```jsx
 <SortableRoot data={data}>
    {(item: SortableData<string>) => {
      return (
        <SortableItem />
      )
    }}
 </SortableRoot>
```

Only the SortableItemArea is draggable.

```jsx
 <SortableRoot data={data}>
    {(item: SortableData<string>) => {
      return (
        <SortableItem as='DraggableRoot' >
          <SortableItemArea />
        </SortableItem>
      )
    }}
 </SortableRoot>
```

## API

## SortableRootProps


### SortableItemProps


### SortableData




---
url: /lynx-ui/components/swipe-action.md
---

# 

# `<SwipeAction>`

A SwipeAction component for ReactLynx. It provides swipeable list item primitives via main-thread gestures.
- Key Composition:

- displayArea: Visible content section

- actionArea: Hidden actionable area (e.g. for swipe-to-delete functionality)

- Use Cases:

- Implement swipe gestures (e.g. delete/archive actions)

- Build interactive touch controls

:::info Requirements
LynxSDK version >= 2.16

@lynx-js/react version > 0.24

```js
// pageConfig
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

pluginReactLynx({
  enableNewGesture: true,
}),
```

:::

:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-swipe-action) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

**This is an example below: lynx-ui-swipe-action**

**Entry:** `Basic`
**Bundle:** `dist/SwipeActionBasic.lynx.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import { Button, SwipeAction } from '@lynx-js/lynx-ui'
import type { SwipeActionRef } from '@lynx-js/lynx-ui'

import './index.css'

function App() {
  const swipeActionRef = useRef<SwipeActionRef>(null)
  const [showAction, setShowAction] = useState<boolean>(false)
  const renderDisplayArea = () => (
    <view className='display-area-container'>
      <view className='display-area-content' />
    </view>
  )
  const renderActionArea = () => (
    <view className='action-area-container'>
      <view className='action-area-content' />
    </view>
  )

  return (
    <view className='demo-container lunaris-dark'>
      <view className='swipe-action-container'>
        <SwipeAction
          className='swipe-action'
          swipeActionId='SwipeAction'
          ref={swipeActionRef}
          enableSwipe={true}
          displayArea={renderDisplayArea()}
          actionArea={renderActionArea()}
          onAction={(id: string) => {
            console.log('delete', id)
          }}
          onSwipeStart={(id: string) => {
            console.log('start', id)
          }}
          onSwipeEnd={(id: string) => {
            console.log('end', id)
          }}
        />
      </view>
      <view className='button-container'>
        <Button
          className='button'
          onClick={() => {
            if (showAction) {
              swipeActionRef.current?.closeActionArea(true)
            } else {
              swipeActionRef.current?.showActionArea(true)
            }
            setShowAction(!showAction)
          }}
        >
          <text className='button-text'>
            {showAction ? 'Hide actionArea' : 'Show actionArea'}
          </text>
        </Button>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## SwipeActionProps


## SwipeActionRef




---
url: /lynx-ui/components/swiper.md
---

# 

# `<Swiper>`

A Swiper (carousel) component for ReactLynx. It provides pagination and gesture-handling primitives.
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-swiper) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::

Basic UsageAdvanced Usage## Basic Usage

Start with normal mode for common paged content. Keep the item size and
container size explicit, then use `onChange` to sync the current index with an
indicator or other page state.

**This is an example below: lynx-ui-swiper**

**Entry:** `Basic`
**Bundle:** `dist/SwiperBasic.lynx.bundle` | Web: `dist/SwiperBasic.web.bundle`

```tsx {33-46,63-66}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Button } from '../Common/Button'
import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import './styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

const itemWidths = [250, 350, 400]
const alignArr: ['start', 'center', 'end'] = ['start', 'center', 'end']

const INITIAL_INDEX = 2

function SwiperEntry(): JSX.Element {
  const [itemWidthsIndex, setItemWidthsIndex] = useState<number>(0)
  const [alignIndex, setAlignIndex] = useState<number>(1)
  const [currentIndex, setCurrentIndex] = useState<number>(INITIAL_INDEX)
  const swiperRef = useRef<SwiperRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={itemWidths[itemWidthsIndex] ?? 0}
          containerWidth={lynx.__globalProps.screenWidth - 32
            || SystemInfo.pixelWidth / SystemInfo.pixelRatio - 32}
          duration={500}
          initialIndex={INITIAL_INDEX}
          onChange={setCurrentIndex}
          mode='normal'
          modeConfig={{
            align: alignArr[alignIndex],
            spaceBetween: 16,
          }}
          autoPlay={false}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
      <view className='operation'>
        <Button
          onClick={() => {
            swiperRef.current?.swipePrev()
          }}
          className='expand'
          text='SwipePrev'
        />
        <Button
          onClick={() => {
            swiperRef.current?.swipeNext()
          }}
          className='expand'
          type='primary'
          text='SwipeNext'
        />
      </view>
      <view className='sub-operation'>
        <Button
          onClick={() => {
            setItemWidthsIndex(prev => (prev + 1) % itemWidths.length)
          }}
          text={'Change Item Width'}
          subText={`ItemWidth: ${itemWidths[itemWidthsIndex]}`}
        >
        </Button>
        <Button
          onClick={() => {
            setAlignIndex(prev => (prev + 1) % itemWidths.length)
          }}
          text={'Change Align Type'}
          subText={`AlignType: ${alignArr[alignIndex]}`}
        >
        </Button>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## Loop

Use loop mode when the first and last items should connect. This avoids a hard
edge in cyclic carousels such as featured content, campaigns, or repeating
recommendations.

**This is an example below: lynx-ui-swiper**

**Entry:** `Loop`
**Bundle:** `dist/SwiperLoop.lynx.bundle` | Web: `dist/SwiperLoop.web.bundle`

```tsx {34-48}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4]

function SwiperEntry() {
  const [currentIndex, setCurrentIndex] = useState(0)
  const SwiperItemGap = 8
  const screenWidth = lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio
  const containWidth = (screenWidth || 375) - SwiperItemGap * 2
  const itemWidth = ((screenWidth || 375) / 375) * 315

  console.log(
    'screenWidth, itemWidth, containWidth',
    screenWidth,
    itemWidth,
    containWidth,
  )
  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          data={itemArr}
          itemWidth={itemWidth + SwiperItemGap}
          itemHeight={250}
          containerWidth={containWidth}
          loop={true}
          duration={500}
          initialIndex={0}
          mode='normal'
          modeConfig={{
            spaceBetween: SwiperItemGap,
          }}
          autoPlay={true}
          onChange={setCurrentIndex}
          experimentalHorizontalSwipeOnly={true}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Loop mode keeps autoplay continuous across the boundary.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## Bounces

Use bounce content for boundary feedback or pull-to-load behavior. Keep it
hidden during normal browsing, and reveal only a lightweight state while the user
drags past the edge.

**This is an example below: lynx-ui-swiper**

**Entry:** `Bounces`
**Bundle:** `dist/SwiperBounces.lynx.bundle` | Web: `dist/SwiperBounces.web.bundle`

```tsx {43-64}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'
import './styles.css'

const itemArr: number[] = [1, 2, 3, 4]
const CONTAINER_PADDING = 32
const BOUNCE_WIDTH = 96
const ITEM_GAP = 16
const ITEM_HEIGHT = 220

const getScreenWidth = () =>
  lynx.__globalProps.screenWidth
  || SystemInfo.pixelWidth / SystemInfo.pixelRatio

function SwiperEntry() {
  const [currentIndex, setCurrentIndex] = useState(0)
  const containerWidth = getScreenWidth() - CONTAINER_PADDING
  const itemWidth = Math.min(300, containerWidth - 48)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area bounces-content-area'>
        <Swiper
          data={itemArr}
          itemWidth={itemWidth}
          itemHeight={ITEM_HEIGHT}
          containerWidth={containerWidth}
          loop={false}
          duration={500}
          initialIndex={2}
          mode='normal'
          modeConfig={{
            align: 'start',
            spaceBetween: ITEM_GAP,
          }}
          style={{
            overflow: 'hidden',
          }}
          bounceConfig={{
            enable: true,
            startBounceItemWidth: 0,
            endBounceItemWidth: BOUNCE_WIDTH,
            endBounceItem: (
              <view className='bounce-loading'>
                <view className='bounce-loading-dot bounce-loading-dot--first' />
                <view className='bounce-loading-dot bounce-loading-dot--second' />
                <view className='bounce-loading-dot bounce-loading-dot--third' />
              </view>
            ),
            onEndBounceItemBounce: ({ type }) => {
              console.log('onBounce result', type)
            },
          }}
          onChange={setCurrentIndex}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: `${ITEM_HEIGHT}px`,
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## Custom

Use a custom mode when the slide should react continuously to swipe progress.
Map the progress value to transforms such as translate, scale, and rotate to
build stacked-card interactions.

You can see [Advanced Usage](/lynx-ui/components/swiper.md?page=1) for more.

**This is an example below: lynx-ui-swiper**

**Entry:** `CustomTinder`
**Bundle:** `dist/SwiperCustomTinder.lynx.bundle` | Web: `dist/SwiperCustomTinder.web.bundle`

```tsx {22-35,81-83}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'

import { Card } from './Card'

import './styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
const ITEM_WIDTH = 220
const ITEM_HEIGHT = 330

const customAnimation = (value: number) => {
  'main thread'
  const translateX = interpolate(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolate(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolate(value, [-1, 0], [-15, 0], 'clamp')
  const scale = interpolate(value, [0, 1], [1, 0.95], 'extend')
  const opacity = interpolate(value, [-1, -0.8, 0, 1], [0, 0.9, 1, 1], 'clamp')

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
  }
}

const customAnimationFirstScreen = (value: number, _index: number) => {
  const translateX = interpolateJS(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolateJS(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolateJS(value, [-1, 0], [-15, 0], 'clamp')
  const zIndex = interpolateJS(
    value,
    itemArr.map((_, index) => index),
    itemArr.map((_, index) => (itemArr.length - index) * 10),
    'extend',
  )

  const scale = interpolateJS(
    value,
    [0, 1, 0],
    [1, 0.95, 1],
    'extend',
  )
  const opacity = interpolateJS(
    value,
    [-1, -0.8, 0, 1],
    [0, 0.9, 1, 1],
    'clamp',
  )

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
    zIndex: zIndex,
  }
}

function SwiperEntry() {
  return (
    <view className='demo-container lunaris-dark'>
      <Swiper
        data={itemArr}
        itemWidth={ITEM_WIDTH}
        itemHeight={ITEM_HEIGHT}
        containerWidth={ITEM_WIDTH}
        duration={500}
        initialIndex={0}
        mode='custom'
        main-thread:customAnimation={customAnimation}
        customAnimationFirstScreen={customAnimationFirstScreen}
        style={{
          overflow: 'visible',
        }}
      >
        {({ index }) => (
          <SwiperItem>
            <view
              class='block-view'
              style={{
                width: '100%',
                height: '100%',
                display: 'flex',
                justifyContent: 'center',
                alignItems: 'center',
              }}
            >
              <Card index={index} />
            </view>
          </SwiperItem>
        )}
      </Swiper>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```


## SwiperProps


### RenderFunctionProps


### BounceConfig


### onBounceParams


### SwipeToOptions


## SwiperRef

## Advanced Usage

Use the advanced APIs when the default slide layout is not enough. `customAnimation`
lets each item respond to swipe progress, while `mode` decides whether Swiper
places items for you or leaves placement to your animation function.

### Understanding `customAnimation`

```
type customAnimation = (value: number, index: number) => CSSProperties
```

`customAnimation` is a main thread function. While Swiper is scrolling, each
`SwiperItem` receives its distance from the active item and returns the style it
should use for that frame.

The function parameter `value` represents the distance of this `<SwiperItem>` relative to the selected `<SwiperItem>`.

In this example, when `<Swiper>`'s progress is 2:

- `<SwiperItem>-2` receives a `value` of 0
- `<SwiperItem>-1` receives a `value` of -1
- `<SwiperItem>-3` receives a `value` of 1

Furthermore, when `<Swiper>`'s progress is updated to 3:

- `<SwiperItem>-2` receives a `value` of -1
- `<SwiperItem>-1` receives a `value` of -2
- `<SwiperItem>-3` receives a `value` of 0

Use this value as a stable input for interpolation. For example, `0` is the
active item, `-1` is the previous item, and `1` is the next item.

### Practice with `customAnimation`

This pattern is useful when Swiper should keep its normal layout but the items
need visual treatment such as scale, opacity, or rotation.

**This is an example below: lynx-ui-swiper**

**Entry:** `Custom`
**Bundle:** `dist/SwiperCustom.lynx.bundle` | Web: `dist/SwiperCustom.web.bundle`

```tsx {22-44,54-70}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

function customAnimation(value: number, _index: number) {
  'main thread'

  const scale = interpolate(value, [-1, 0, 1], [0.5, 1, 0.5])

  return {
    transform: `scale(${scale})`,
  }
}

function customAnimationFirstScreen(value: number, _index: number) {
  const scale = interpolateJS(value, [-1, 0, 1], [0.5, 1, 0.5])

  return {
    transform: `scale(${scale})`,
  }
}

function SwiperEntry(): JSX.Element {
  const swiperRef = useRef<SwiperRef>(null)
  const [currentIndex, setCurrentIndex] = useState(0)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={250}
          duration={500}
          initialIndex={0}
          mode='normal'
          modeConfig={{
            align: 'center',
          }}
          onChange={setCurrentIndex}
          main-thread:customAnimation={customAnimation}
          customAnimationFirstScreen={customAnimationFirstScreen}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator current={currentIndex} count={itemArr.length} />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Custom animation scales each slide around the active item.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## Understanding `mode`

`<Swiper>` supports two `mode` options: `normal` and `custom`. Their differences are as follows:

`mode='normal'`

- `<SwiperItem>`s are arranged sequentially in the direction

- Provides center alignment, right alignment, and other capabilities through `modeConfig`
  `mode='custom'`

- The position of `<SwiperItem>` needs to be specified through [`customAnimation`](#understanding-customanimation)

- Offers higher customization capabilities

To summarize:

- `normal` mode handles the position of `<SwiperItem>`s, making it more suitable for horizontal sliding scenarios and easier to use
- `custom` mode requires manual position calculation but offers higher extensibility

### Practice with `customAnimation` when `mode='custom'`

Use `custom` mode when item placement itself is part of the design. In this
mode, the animation function should return both position and visual style.

**This is an example below: lynx-ui-swiper**

**Entry:** `CustomScale`
**Bundle:** `dist/SwiperCustomScale.lynx.bundle` | Web: `dist/SwiperCustomScale.web.bundle`

```tsx {25-60,71-81}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

const ITEM_WIDTH = 250

function customAnimation(value: number, _index: number) {
  'main thread'

  const scale = interpolate(value, [-1, 0, 1], [0.8, 1, 0.8])
  // const scale = 1

  const centerOffset = ((lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio) - ITEM_WIDTH) / 2
  const translateX = interpolate(value, [-1, 0, 1], [
    -ITEM_WIDTH + centerOffset,
    centerOffset,
    ITEM_WIDTH + centerOffset,
  ], 'extend')

  return {
    transform: `translateX(${translateX}px) scale(${scale})`,
    'transform-origin': 'center',
  }
}

function customAnimationFirstScreen(value: number, _index: number) {
  const scale = interpolateJS(value, [-1, 0, 1], [0.8, 1, 0.8])
  // const scale = 1
  const centerOffset = ((lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio) - ITEM_WIDTH) / 2
  const translateX = interpolateJS(value, [-1, 0, 1], [
    -ITEM_WIDTH + centerOffset,
    centerOffset,
    ITEM_WIDTH + centerOffset,
  ], 'extend')

  console.log(
    'customAnimationFirstScreen',
    value,
    scale,
    translateX,
    centerOffset,
  )
  return {
    transform: `translateX(${translateX}px) scale(${scale})`,
    'transform-origin': 'center',
  }
}

function SwiperEntry(): JSX.Element {
  const swiperRef = useRef<SwiperRef>(null)
  const [currentIndex, setCurrentIndex] = useState(0)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={ITEM_WIDTH}
          itemHeight={250}
          duration={500}
          initialIndex={0}
          mode='custom'
          modeConfig={{
            align: 'center',
          }}
          onChange={setCurrentIndex}
          main-thread:customAnimation={customAnimation}
          customAnimationFirstScreen={customAnimationFirstScreen}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator current={currentIndex} count={itemArr.length} />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Custom mode keeps the active slide centered while scaling neighbors.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```





---
url: /lynx-ui/components/switch.md
---

# 

# `<Switch>`

A headless Switch (toggle) component for ReactLynx. It provides unstyled primitives for toggle states.
## Basic Usage

The basic usage of `<Switch>`

**This is an example below: lynx-ui-switch**

**Entry:** `Basic`
**Bundle:** `dist/SwitchBasic.lynx.bundle` | Web: `dist/SwitchBasic.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Switch, SwitchThumb, SwitchTrack } from '@lynx-js/lynx-ui'

import { hitSlop } from '../shared/hitSlop'
import './index.css'

function App() {
  const [checked, setChecked] = useState(true)

  return (
    <view className='demo-container lunaris-dark luna-gradient-berry'>
      <view className='demo-canvas'>
        {/* Uncontrolled */}
        <view className='section'>
          <view className='row'>
            <Switch className='switch' switchProps={hitSlop}>
              <SwitchTrack className='switch-track' />
              <SwitchThumb className='switch-thumb' />
            </Switch>
            <text className='label'>Uncontrolled</text>
          </view>
        </view>

        {/* Controlled */}
        <view className='section'>
          <view className='row'>
            <Switch
              className='switch'
              checked={checked}
              onChange={setChecked}
              switchProps={hitSlop}
            >
              <SwitchTrack className='switch-track' />
              <SwitchThumb className='switch-thumb' />
            </Switch>
            <text className='label'>Controlled</text>
          </view>
        </view>

        {/* Disabled */}
        <view className='section'>
          <view className='row'>
            <Switch
              className='switch'
              disabled
              defaultChecked
              switchProps={hitSlop}
            >
              <SwitchTrack className='switch-track' />
              <SwitchThumb className='switch-thumb' />
            </Switch>
            <text className='label disabled'>Disabled</text>
          </view>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)

export default App

```



## Theme Control

Use a controlled Switch (`checked` + `onChange`) to drive page theme, and let token changes update the Switch visuals automatically. The example also shows a composed `ThemedSwitch` wrapper alongside part-level primitives; see [Styling & Theming](/lynx-ui/styling-theming.md).

**This is an example below: lynx-ui-switch**

**Entry:** `Themed`
**Bundle:** `dist/SwitchThemed.lynx.bundle` | Web: `dist/SwitchThemed.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { clsx } from 'clsx'

import {
  ThemedSwitch,
  ThemedSwitchRoot,
  ThemedSwitchThumb,
  ThemedSwitchTrack,
} from './themed-switch'
import './index.css'

function App() {
  const [outerDark, setOuterDark] = useState(true)
  const [innerLight, setInnerLight] = useState(false)

  return (
    <view
      className={clsx(
        'size-full flex flex-col justify-center px-[48px] py-[72px]',
        'luna-gradient-berry',
        outerDark ? 'lunaris-dark' : 'lunaris-light',
      )}
    >
      <view className='flex flex-col gap-[24px] px-[48px] py-[64px] rounded-[16px] overflow-hidden text-content bg-canvas'>
        <text className='text-lg text-content-2'>Theme Switching</text>

        {/* 1) Outer container theme toggle (uses composed component) */}
        <view className='flex flex-row items-center gap-[16px] w-full'>
          <ThemedSwitch checked={outerDark} onChange={setOuterDark} />
          <text className='text-base text-content-2'>
            {outerDark ? 'lunaris-dark' : 'lunaris-light'}
          </text>
        </view>

        <view
          className={clsx(
            'flex flex-col mt-[16px] gap-[10px] py-[16px] px-[16px] rounded-[16px] overflow-hidden bg-canvas border border-line',
            innerLight ? 'lunaris-light' : 'lunaris-dark',
          )}
        >
          {/* 3) Inner container theme toggle (uses themed Primitives)*/}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitchRoot
              defaultChecked={innerLight}
              onChange={setInnerLight}
            >
              <ThemedSwitchTrack />
              <ThemedSwitchThumb />
            </ThemedSwitchRoot>
            <text className='text-base text-content-2'>
              {innerLight ? 'lunaris-light' : 'lunaris-dark'}
            </text>
          </view>
          {/* 3) Inner disabled sample */}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitch disabled checked={innerLight} />
            <text className='text-base text-content-2 opacity-50'>
              Disabled
            </text>
          </view>
        </view>
        {/* 4) Outer disabled sample */}
        <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
          <ThemedSwitch disabled checked={outerDark} />
          <text className='text-base text-content-2 opacity-50'>Disabled</text>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)
export default App

```



## Structure

```tsx
<Switch>
  <SwitchThumb />
</Switch>
```

```tsx
<Switch>
  <SwitchTrack />
  <SwitchThumb />
</Switch>
```

## API

### SwitchTrack

The track of the Switch.
Represents the background area on which the thumb slides.
Can also be used for pressed overlays or state decorations.


### SwitchThumb

The thumb of the Switch.
The draggable/clickable handle that toggles the state.


### Switch

Props for the Switch component.



### State-based styling & rendering

This component exposes each of its internal states through **two interchangeable channels**, and the table below maps them one-to-one:

- **CSS className** — a class like `ui-<state>` is toggled on the root node, so you can style it with selectors such as `.ui-<state> { ... }`.
- **Render-prop field** — when `children` is a function, the same state is passed in via `children({ <state>: boolean, ... })` for runtime-driven rendering.


ui-checkedRender Prop`checked`·Type`boolean`Whether the Switch is currently checked.
Applied when `status.checked` is true.ui-activeRender Prop`active`·Type`boolean`Whether the Switch is active (pressed or being interacted with).
Applied when `status.active` is true.ui-disabledRender Prop`disabled`·Type`boolean`Whether the Switch is disabled.
Applied when `status.disabled` is true.


---
url: /lynx-ui/contributing.md
---

# Contributing

lynx-ui welcomes contributions from the community. This page focuses on the component development
workflow and the checks that commonly block pull requests. For the full workflow, see the
[lynx-ui contributing guide](https://github.com/lynx-family/lynx-ui/blob/main/CONTRIBUTING.md).

## Prerequisites

- Use **Node.js >= 24.0.0**.
- Use the pnpm version pinned by the repository. Run `corepack enable` before installing dependencies.
- Install dependencies from the repository root with `pnpm install`.

```bash
git clone https://github.com/lynx-family/lynx-ui.git
cd lynx-ui
corepack enable
pnpm install
pnpm build
```

## Component Development

Each component package lives in `packages/lynx-ui-<component-name>` and usually contains:

- `src`: component source code
- `types`: public type definitions, including docs entries
- `README.md`: component-level usage notes

To scaffold a new component with the expected package structure, run:

```bash
pnpm make-new-component --create <component-name>
# Example: pnpm make-new-component --create toast
```

This creates:

```text
packages/lynx-ui-<component-name>
```

## Examples

Add or update examples for component changes so reviewers can verify the behavior visually.

To scaffold example files:

```bash
pnpm make-new-component --example <component-name>
# Example: pnpm make-new-component --example toast
```

Before running an example, check its package name in:

```text
apps/examples/src/<Component>/package.json
```

For detailed instructions, see
[apps/examples/README.md](https://github.com/lynx-family/lynx-ui/blob/main/apps/examples/README.md)
in the lynx-ui repository. Then run the matching example package:

```bash
# Example: run button examples
npx turbo watch dev --filter '@lynx-example/lynx-ui-button'
```

## Before Opening a Pull Request

Run the relevant checks locally before submitting:

```bash
pnpm check
pnpm check:changed
pnpm test
```

Use `pnpm fix:all` or `pnpm check:changed:unsafe` only when you have reviewed the affected files.

## Release Notes and Versioning

lynx-ui uses Changesets for package versioning. Add a changeset for any user-facing change, including
component behavior, APIs, package dependencies, documentation shipped with a component, or example
packages.

```bash
pnpm changeset
```

Example packages are published with the component release. After an example package is released, the
matching example version in the
[lynx-website](https://github.com/lynx-family/lynx-website) repository must be updated manually.
Make sure the stable version of the example package has been published before updating the website,
so the docs do not reference a version that is not available on the registry yet.

## Pull Request Requirements

- Pull requests are usually squash-merged. The final merged PR should become a single commit on the
  target branch.
- The final commit message should follow
  [Conventional Commits](https://www.conventionalcommits.org/).
- User-facing changes need a changeset.
- Contributions are licensed under the
  [Apache-2.0 License](https://github.com/lynx-family/lynx-ui/blob/main/LICENSE). If a CLA check is
  shown on your pull request, complete it before requesting review.



---
url: /lynx-ui/faqs.md
---

# 




---
url: /lynx-ui/index.md
---

<span class="hero-title"> <span class="normal">UI Components for</span> <span class="brand-ani">ReactLynx</span> </span>

> Pack the best Lynx for you, one component at a time

[Quick Start](/lynx-ui/introduction.html#quick-start) | [Components](/lynx-ui/components/button)
![Clear API Circle](/static/svg/TwoHalfCircleLight.d059ca3726.svg)Intuitive and clear APIs![Clear API Rectangle](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3QgeD0iMC4yMzA3MTMiIHk9IjAuMjM3NzkzIiB3aWR0aD0iMjEuNjY2NCIgaGVpZ2h0PSIyMS42NjY0IiByeD0iNSIgZmlsbD0idXJsKCNwYWludDBfbGluZWFyXzQwNl8zNzgwKSIvPgo8ZGVmcz4KPGxpbmVhckdyYWRpZW50IGlkPSJwYWludDBfbGluZWFyXzQwNl8zNzgwIiB4MT0iMjEuODk3MSIgeTE9IjIxLjkwNDIiIHgyPSIwLjIzMDcxMyIgeTI9IjAuMjM3NzkzIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CjxzdG9wIHN0b3AtY29sb3I9IiM5MDU3REIiLz4KPHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjRTZEMEY3Ii8+CjwvbGluZWFyR3JhZGllbnQ+CjwvZGVmcz4KPC9zdmc+Cg==)No need to write complex x elements from scratchVSStandard component code
```typescript
<list list-type="single"
      column-count={1}
      vertical-orientation
      android-new-scroll-top
      ios-scroll-emitter-helper
      android-enable-item-prefetch
      ios-fixed-content-offset
      component-init-measure
      android-trigger-sticky-layout
      use-old-sticky={false}
      lower-threshold={20}
      experimental-disable-filter-scroll
      experimental-disable-platform-implementation
      custom-list-name="list-container"
      enable-async-list
      ios-index-as-z-index
      scroll-bar-enable={false}
/>
```
lynx-ui code
```typescript
<List listId='listBasic'
      listType='flow'
      spanCount={2}
      scrollOrientation='vertical'
/>
```
Consistent across multiple platformsPlatform differences are handled at this layer, with battle-tested solutions ensuring long-term consistency.![Consistency Dark](/static/svg/ConsistencyDark.186d6e27f8.svg)![Consistency Light](/static/svg/ConsistencyLight.736c1282ea.svg)Built for performant Lynx experiencesWe will provide you with the best practices for Lynx APIs.![Performance Dark](/static/svg/PerformanceDark.4e9d4dd36f.svg)![Performance](/static/svg/PerformanceLight.ef5357148b.svg)Forward and backward version compatibilityThe advantage of flexible deployment on the front end enables new features and new engine adaptation schemes to run on more platform versions at the first time.Lynx 3.2Lynx 3.7@lynx-js/react@0.105@lynx-js/react@0.120Start building with lynx-uiGet Started


---
url: /lynx-ui/introduction.md
---

# What is lynx-ui?

`@lynx-js/lynx-ui` is the official **headless UI library** built for **ReactLynx**, the most popular framework for building Lynx apps. It reconciles **cross-platform differences** in UI behavior and APIs, providing **consistent**, **high-performance** frontend components on top of Lynx's low-level primitives.

## Quick Start

`lynx-ui` supports both full-library imports and individual component imports.

### Full-Library Import (Recommended)

Install and import the main `lynx-ui` package. Tree-shaking is supported, so unused components will not increase your final bundle size.


```sh [npm]
npm install @lynx-js/lynx-ui
```

```sh [yarn]
yarn add @lynx-js/lynx-ui
```

```sh [pnpm]
pnpm add @lynx-js/lynx-ui
```

```sh [bun]
bun add @lynx-js/lynx-ui
```

```sh [deno]
deno add npm:@lynx-js/lynx-ui
```

Use it in your project:

```jsx {1}
import { Button } from '@lynx-js/lynx-ui';

export default function App() {
  return (
    <view>
      <Button />
    </view>
  );
}
```

### Importing Individual Components

Each `lynx-ui` component is also published as a separate package. Use this approach when you have compatibility constraints or need to depend on a specific component package.

For example, to use `<Button>`:


```sh [npm]
npm install @lynx-js/lynx-ui-button
```

```sh [yarn]
yarn add @lynx-js/lynx-ui-button
```

```sh [pnpm]
pnpm add @lynx-js/lynx-ui-button
```

```sh [bun]
bun add @lynx-js/lynx-ui-button
```

```sh [deno]
deno add npm:@lynx-js/lynx-ui-button
```

Use it in your project:

```jsx {1}
import { Button } from '@lynx-js/lynx-ui-button';

export default function App() {
  return (
    <view>
      <Button />
    </view>
  );
}
```

:::details Which way should I choose
We recommend full-library imports by default:

1. Installation and usage are simpler

2. Tree-shaking keeps the final bundle size small

:::

## Configuration

```typescript
export default defineConfig({
  ...
  plugins: [
    pluginReactLynx({
      ...
      enableNewGesture: true,
    }),
  ],
})
```

:::details Concerned about configuration changes affecting other pages?
This page lists the requirements for the full library. If you need looser constraints, check the configuration requirements of the specific components you use.
:::

## Compatibility

- [Lynx Engine](/guide/compatibility.md): >= 3.2
- Platforms: full support for **iOS** and **Android**, with ongoing improvements for **Harmony**, **Web**, and **Desktop**

:::details Version not supported?
These are the requirements for the full library. Individual components may support lower versions.
:::

## Further Resources

lynx-ui components make heavy use of [**Main Thread Script**](/react/main-thread-script.md), which runs interaction logic directly on the main thread for smoother, more responsive experiences. To understand how it works, see the [Main Thread Script guide](/react/main-thread-script.md) in the ReactLynx docs.

If you use AI-assisted development, [lynx-ui Skills](/ai/skills/lynx-ui.md) provides pre-configured component references that help coding agents generate more accurate lynx-ui code.

## Building with the Community

lynx-ui is a place to explore and validate new ideas for Lynx components. We welcome contributions from the community and hope to make every improvement visible and reusable.

### Share Real-World Use Cases

Whether you are building e-commerce, social, live-streaming, or other types of apps, we welcome real-world cases from your development practice. If you discover meaningful interactions, stability improvements, or performance optimizations, lynx-ui can help refine them into reusable components with appropriate compatibility and performance considerations.

### Explore New Interaction Patterns

lynx-ui is committed to advancing interaction design in Lynx. We look forward to working with the community to discuss, iterate on, and implement practical solutions for more expressive user experiences.

### Grow the Lynx Ecosystem

Your experience with Lynx development is essential to the growth of the ecosystem. We sincerely welcome your feedback, participation, and contributions.

Visit the [GitHub repository](https://github.com/lynx-family/lynx-ui) to get started, or read the [Contribution Guide](https://github.com/lynx-family/lynx-ui/blob/main/CONTRIBUTING.md) for details.



---
url: /lynx-ui/luna-themes-tokens.md
---

# LUNA Themes and Tokens

LUNA is the theme foundation used across the `lynx-ui` examples. It provides a
small, semantic token system that can be consumed through CSS variables,
Tailwind utilities, or themed wrapper components.


L.U.N.A Studio

Use LUNA when you want a shared visual language across screens without
hard-coding colors into every component. Instead of styling a button, sheet, or
switch with one-off hex values, you style it with semantic roles such as
`paper`, `content`, `primary`, and `line`. Those roles remain stable even when
the visual expression changes between themes.

LUNA currently ships four built-in themes:

| Theme Key       | Variant   | Mode  |
| --------------- | --------- | ----- |
| `luna-light`    | `luna`    | Light |
| `luna-dark`     | `luna`    | Dark  |
| `lunaris-light` | `lunaris` | Light |
| `lunaris-dark`  | `lunaris` | Dark  |

- `luna` is the neutral foundation for product UI.
- `lunaris` is the signature gradient expression for more branded surfaces.
- `light` and `dark` preserve the same semantic token contract, so components
  can keep the same styling logic across modes.

This page includes LUNA Studio, an interactive preview of the theme contract described in this guide: theme variants, token groups, and the recommended override surface.

When should I choose luna vs. lunaris?- Use `luna` for neutral product UI and readability-first surfaces.
- Use `lunaris` for branded or expressive surfaces, especially when container-heavy demos need stronger visual identity.
- Mix them by applying a theme class to a subtree when needed.

## Core Token Groups

LUNA contains more tokens than most applications need on day one, but a small
set of core groups covers most product surfaces. If you are styling
`lynx-ui` components or generating UI with AI, start with these groups first.

### Surface

Surface tokens define the background layers of the interface.

| Token            | Use For                                                                |
| ---------------- | ---------------------------------------------------------------------- |
| `canvas`         | App background and large layout surfaces                               |
| `canvas-ambient` | Deep ambient background below all content                              |
| `paper`          | Primary content surfaces such as cards and panels                      |
| `paper-clear`    | Floating surfaces that lift above `paper`, such as popovers and sheets |
| `paper-veil`     | Soft translucent layer that recedes toward the background              |
| `paper-film`     | Very light translucent surface treatment                               |

Use surface tokens to establish hierarchy before adding accent color. In most
layouts, `canvas` defines the page environment, `paper` defines where content
lives, and `paper-clear` lifts above `paper` for floating surfaces such as
popovers and sheets.

### Content

Content tokens define text and icon presence.

| Token            | Use For                                         |
| ---------------- | ----------------------------------------------- |
| `content`        | Primary text and icons                          |
| `content-2`      | Secondary text and supporting emphasis          |
| `content-muted`  | Helper text and lower-emphasis content          |
| `content-subtle` | Placeholder and quiet UI copy                   |
| `content-faint`  | Decorative or near-background foreground        |
| `content-faded`  | Reduced-presence foreground on colored surfaces |

When in doubt, start with `content` for main text and `content-2` or
`content-muted` for supporting copy.

### Primary

Primary tokens define high-emphasis actions and active states.

| Token                   | Use For                                            |
| ----------------------- | -------------------------------------------------- |
| `primary`               | Main accent, selected states, emphasized actions   |
| `primary-2`             | Variant of `primary` used for active states        |
| `primary-muted`         | Soft primary backgrounds                           |
| `primary-content`       | Text and icons placed on primary surfaces          |
| `primary-content-faded` | Reduced-presence text or icons on primary surfaces |

Use `primary` for action emphasis, not as a replacement for every surface in
the interface.

### Secondary

Secondary tokens define supporting accents and complementary emphasis.

| Token                     | Use For                                              |
| ------------------------- | ---------------------------------------------------- |
| `secondary`               | Supporting accent                                    |
| `secondary-2`             | Softened variant of `secondary`                      |
| `secondary-content`       | Text and icons placed on secondary surfaces          |
| `secondary-content-faded` | Reduced-presence text or icons on secondary surfaces |

### Neutral

Neutral tokens provide structural contrast and low-emphasis fills.

| Token                   | Use For                                         |
| ----------------------- | ----------------------------------------------- |
| `neutral`               | Strong neutral surfaces                         |
| `neutral-2`             | Slightly softened neutral surfaces              |
| `neutral-subtle`        | Quiet structural fills                          |
| `neutral-faint`         | Low-emphasis fills and inactive states          |
| `neutral-ambient`       | Near-background structural fill                 |
| `neutral-content`       | Foreground on neutral surfaces                  |
| `neutral-content-faded` | Reduced-presence foreground on neutral surfaces |
| `neutral-veil`          | Strong translucent layer toward presence        |
| `neutral-film`          | Light translucent layer toward presence         |

In practice, `neutral-faint` is one of the most useful tokens for form controls,
tracks, and supporting UI chrome.

### Lines and Backdrop

These tokens handle separation and screen-level overlays.

| Token             | Use For                                                                  |
| ----------------- | ------------------------------------------------------------------------ |
| `line`            | Thin, airy outlines around components such as buttons, inputs, and cards |
| `rule`            | Dividers that separate regions, such as list items or sections           |
| `backdrop-subtle` | Light overlays for popovers and tooltips                                 |
| `backdrop`        | Standard overlays for dialogs and sheets                                 |
| `backdrop-heavy`  | Strong overlays for immersive or critical contexts                       |

Use `line` to outline a component, and `rule` to separate one region from
another. The distinction is about role, not weight.

### Gradient

Gradients are optional, but they can make container-heavy `lynx-ui` examples more comprehensible by giving surfaces a clear visual identity.

Gradient tokens define the signature Lunaris expression.

| Token                                                  | Use For                                        |
| ------------------------------------------------------ | ---------------------------------------------- |
| `gradient-a`, `gradient-b`, `gradient-c`, `gradient-d` | Gradient stop colors                           |
| `gradient-content`                                     | Foreground on gradient surfaces                |
| `gradient-content-faded`                               | Lower-emphasis foreground on gradient surfaces |
| `gradient-content-trace`                               | Minimal-presence detail on gradient surfaces   |

If you are building neutral product UI, you may not need these tokens often.
If you are building branded or expressive surfaces, these are the first tokens
to reach for.

## Suggested Starting Set

If you want a small token contract for examples, product UI, or AI prompts,
start with this subset:

- Surfaces: `canvas`, `paper`, `paper-clear`
- Text: `content`, `content-2`, `content-muted`
- Actions: `primary`, `primary-2`, `primary-content`
- Structure: `neutral-faint`, `line`, `rule`
- Overlays: `backdrop`, `backdrop-heavy`

This set is intentionally small. It is enough to build a coherent UI without
forcing every use case to choose from the full token inventory.

## Token Usage

You can consume the same tokens in different ways depending on your stack.

### CSS Variables

```css
.card {
  color: var(--content);
  background-color: var(--paper);
  border: 1px solid var(--line);
}

.card-title {
  color: var(--content);
}

.card-description {
  color: var(--content-muted);
}
```

### Tailwind Utilities

```tsx
<view className="bg-paper text-content border border-line">
  <text className="text-content">Card title</text>
  <text className="text-content-muted">Supporting description</text>
</view>
```

The semantic roles stay the same even if you switch from `luna-light` to
`lunaris-dark`.

## Overriding Tokens

LUNA is designed to make branding start at the token layer. Instead of
rewriting component styles, define a product theme by overriding the semantic
tokens those components consume.

### Apply a Built-In Theme As-Is

When you are using a built-in theme without modification, apply its class
directly:

```tsx
<view className="lunaris-dark">{/* themed content */}</view>
```

### Define Your Own Theme

Once you start overriding tokens, give your theme its own name. Treat it as a
peer of the built-in themes, not a modifier layered on top of one:

```css
.my-brand-dark {
  --primary: #ff4f8b;
  --primary-2: #ff2f73;
  --primary-content: #ffffff;
  --paper: #141414;
  --content: #f8f8f8;
  /* inherit remaining tokens from a built-in theme of your choice */
}
```

```tsx
<view className="my-brand-dark">{/* branded content */}</view>
```

This keeps the className surface honest: a single class name corresponds to a
single, fully-defined theme. Light and dark are properties of your brand, not
borrowed from a built-in theme at the markup layer.

### Override Principles

- Prefer overriding semantic tokens over rewriting component classes.
- Start with a small set of brand-defining tokens such as `primary`, `paper`,
  and `content`.
- Keep foreground and background pairs aligned, such as `primary` with
  `primary-content`.
- Preserve the same token names across light and dark modes whenever possible.

## AI Gen UI Guidelines

If you are using LUNA as the visual contract for AI-generated UI, keep the
instructions simple and semantic. The goal is not to expose every available
token. The goal is to give the model a stable vocabulary that maps cleanly to
real theme variables.

### Do and Don't

| Do                                                                   | Don't                                                  |
| -------------------------------------------------------------------- | ------------------------------------------------------ |
| Use semantic tokens like `bg-paper` and `text-content`               | Hard-code hex colors or invent one-off color names     |
| Pair foregrounds with their surfaces (`primary` + `primary-content`) | Break foreground/background pairs                      |
| Use `border-line` for standard separators                            | Use accent tokens like `primary` for every surface     |
| Establish surface hierarchy before adding accent color               | Mix unrelated surface roles without a hierarchy reason |

### Token Vocabulary

For most generated UI, this set is enough:

- Surfaces: `canvas`, `paper`, `paper-clear`
- Text: `content`, `content-2`, `content-muted`
- Actions: `primary`, `primary-2`, `primary-content`
- Structure: `neutral-faint`, `line`
- Overlays: `backdrop`

Map intent to tokens directly:

| Intent                 | Token           |
| ---------------------- | --------------- |
| Page background        | `canvas`        |
| Card surface           | `paper`         |
| Floating surface       | `paper-clear`   |
| Primary call to action | `primary`       |
| Supporting copy        | `content-muted` |
| Inactive control track | `neutral-faint` |

### Recommended Prompt Guidance

Copy a short AI prompt> Use LUNA semantic tokens for all colors. Prefer `canvas`, `paper`, `content`, `content-muted`, `primary`, `primary-content`, `line`, and `backdrop`. Do not use hex values.



---
url: /lynx-ui/main-thread-script.md
---

# Main Thread Script

:::Warning
This is a work in progress.
:::

## What is a Main Thread Script?

A Main Thread Script is a script that runs on the main thread.

## Why use a Main Thread Script?



---
url: /lynx-ui/motion-mini.md
---

# @lynx-js/motion/mini

`@lynx-js/motion/mini` is the lightweight entry of [`@lynx-js/motion`](/lynx-ui/motion.md). It only animates **numbers** and leaves the final style write to your code, for example `translateX(${x}px) scale(${scale})`. This covers most interaction-driven animations and is the entry used by lynx-ui today. See the [full entry](/lynx-ui/motion.md) page for the complete [Motion](https://motion.dev) adaptation and a [comparison table](/lynx-ui/motion.md#what-is-mini-and-when-should-i-use-it).

## Install


```sh [npm]
npm install @lynx-js/motion
```

```sh [yarn]
yarn add @lynx-js/motion
```

```sh [pnpm]
pnpm add @lynx-js/motion
```

```sh [bun]
bun add @lynx-js/motion
```

```sh [deno]
deno add npm:@lynx-js/motion
```

Import from the mini entry:

```ts
import {
  animate,
  useMotionValueRef,
  useMotionValueRefEvent,
} from '@lynx-js/motion/mini';
```

## Basic Pattern

The Mini pattern is:

1. Store each animated number in `useMotionValueRef()`.
2. Subscribe to changes with `useMotionValueRefEvent()`.
3. Write the final style in that subscription.
4. Start `animate()` from a main-thread function.

The example has a separate `mini` entry so the bundle only includes the mini runtime.

**This is an example below: motion**

**Entry:** `src/Mini`
**Bundle:** `dist/mini.lynx.bundle` | Web: `dist/mini.web.bundle`

```tsx {10-11,18-20,23-30,41-57}
import { animate, useMotionValueRef, useMotionValueRefEvent } from "@lynx-js/motion/mini";
import { root, runOnMainThread, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

import { ThemeFrame } from "../shared/ThemeFrame";
import "./styles.css";

export default function MiniExample() {
  const boxRef = useMainThreadRef<MainThread.Element>(null);
  const x = useMotionValueRef(0);
  const scale = useMotionValueRef(1);

  // Consolidate transform updates to avoid redundant DOM operations
  const updateTransform = (xVal?: number, scaleVal?: number) => {
    "main thread";
    const xValue = xVal ?? x.current.get();
    const scaleValue = scaleVal ?? scale.current.get();
    boxRef.current?.setStyleProperties({
      transform: `translateX(${xValue}px) scale(${scaleValue})`,
    });
  };

  useMotionValueRefEvent(x, "change", (v) => {
    "main thread";
    updateTransform(v, undefined);
  });

  useMotionValueRefEvent(scale, "change", (v) => {
    "main thread";
    updateTransform(undefined, v);
  });

  const handleTapSpring = () => {
    void runOnMainThread(startSpring)();
  };

  const handleTapScale = () => {
    void runOnMainThread(startScale)();
  };

  function startSpring() {
    "main thread";
    const target = x.current.get() === 0 ? 160 : 0;
    animate(x.current, target, {
      type: "spring",
      stiffness: 200,
      damping: 20,
    });
  }

  function startScale() {
    "main thread";
    const target = scale.current.get() === 1 ? 1.35 : 1;
    animate(scale.current, target, {
      duration: 0.4,
      ease: (t) => t,
    });
  }

  return (
    <ThemeFrame theme="lunaris-light">
      <view className="mini-container">
        <view main-thread:ref={boxRef} className="mini-box" />
        <view className="mini-controls">
          <view className="mini-btn" bindtap={handleTapSpring}>
            <text className="mini-btn-text">Spring Move</text>
          </view>
          <view className="mini-btn" bindtap={handleTapScale}>
            <text className="mini-btn-text">Scale BackOut</text>
          </view>
        </view>
      </view>
    </ThemeFrame>
  );
}

root.render(
  <MiniExample />,
);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



`useMotionValueRef()` creates a main-thread ref that owns a MotionValue. The value can be read and written inside main-thread functions without rerendering React.

```tsx
const x = useMotionValueRef(0);
const scale = useMotionValueRef(1);
```

Use one motion value for each independent numeric dimension. In the example, `x` controls translation and `scale` controls scale.

`useMotionValueRefEvent()` listens to value changes from the main thread. Use it to apply the latest numeric value to a node.

The callback in this example writes a complete transform string:

```ts
boxRef.current?.setStyleProperties({
  transform: `translateX(${xValue}px) scale(${scaleValue})`,
});
```

That explicit style write is the tradeoff for the smaller runtime. Motion Mini animates numbers; your code maps those numbers to element styles.

## Start Animations

Background-thread event handlers can call `runOnMainThread()` to start a main-thread animation. The animation itself should be created inside the main-thread function.

Use spring options for physical motion:

```ts
animate(x.current, target, {
  type: 'spring',
  stiffness: 200,
  damping: 20,
});
```

Use a duration and easing function for deterministic timing:

```ts
animate(scale.current, target, {
  duration: 0.4,
  ease: (t) => t,
});
```



---
url: /lynx-ui/motion.md
---

# @lynx-js/motion

`@lynx-js/motion` is a thin adaptation layer that reuses [Motion](https://motion.dev)'s source directly to bring its imperative JavaScript APIs to Lynx. All APIs run in the [main-thread script](/react/main-thread-script.md) environment, so animations update visual properties immediately without round-tripping through the background thread. If you know Motion's [`animate()`](https://motion.dev/docs/animate), [`motionValue()`](https://motion.dev/docs/motion-value), and [`spring`](https://motion.dev/docs/spring) on the web, you already know how to use them in Lynx. If you are new to Motion, the [Motion quick-start guide](https://motion.dev/docs/quick-start) covers the fundamentals.

:::details What is Mini and when should I use it?

The package ships two entries. The full entry has not yet reached full feature parity with Motion and has higher engine requirements. [Mini](/lynx-ui/motion-mini.md) is a trimmed-down build with broader compatibility, and is the entry used by lynx-ui today.

|                                                           | `@lynx-js/motion`                                    | `@lynx-js/motion/mini` ([Mini](/lynx-ui/motion-mini.md)) |
| --------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |
| [**Animation**](https://motion.dev/docs/animate)          | numbers, colors, unit strings, keyframe arrays       | numbers only                                             |
| [**Motion values**](https://motion.dev/docs/motion-value) | `motionValue()` (`useMotionValue` not yet supported) | `useMotionValueRef()`                                    |
| [**Spring**](https://motion.dev/docs/spring)              | `type: 'spring'`                                     | `type: 'spring'`                                         |
| [**Stagger**](https://motion.dev/docs/stagger)            | `stagger()` with selectors                           | --                                                       |
| **styleEffect**                                           | derive styles from motion values                     | --                                                       |
| **Lynx Engine**                                           | >= 3.5                                               | no minimum                                               |
| **ReactLynx**                                             | >= 0.115.2                                           | no minimum                                               |
| **Bundle size**                                           | \~275 KB                                             | \~135 KB                                                 |

:::

## Install


```sh [npm]
npm install @lynx-js/motion
```

```sh [yarn]
yarn add @lynx-js/motion
```

```sh [pnpm]
pnpm add @lynx-js/motion
```

```sh [bun]
bun add @lynx-js/motion
```

```sh [deno]
deno add npm:@lynx-js/motion
```

Import from the main package entry:

```ts
import { animate, motionValue, styleEffect } from '@lynx-js/motion';
```

## Animate an element ref

The `animate()` function accepts the same [options](https://motion.dev/docs/animate#options) as Motion on the web, including `duration`, `ease`, `delay`, `repeat`, and `type: 'spring'`. See the [Motion `animate()` reference](https://motion.dev/docs/animate) for the full option list.

The usual pattern is:

1. Create a main-thread element ref with `useMainThreadRef()`.
2. Attach it to the element with `main-thread:ref`.
3. Start [`animate()`](https://motion.dev/docs/animate) inside a main-thread function.
4. Store the animation controls in another main-thread ref so cleanup can call `stop()`.

**This is an example below: motion**

**Entry:** `src/Basic`
**Bundle:** `dist/basic.lynx.bundle` | Web: `dist/basic.web.bundle`

```tsx {20-29,41-44,58-61}
import { animate } from "@lynx-js/motion";
import { root, runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

import { ThemeFrame } from "../shared/ThemeFrame";
import "./styles.css";

export default function Basic() {
  const animateMTRef = useMainThreadRef<ReturnType<typeof animate> | null>(
    null,
  );
  const boxMTRef = useMainThreadRef<MainThread.Element>(null);
  const startTimerMTRef = useMainThreadRef<ReturnType<typeof setTimeout> | null>(
    null,
  );

  function startAnimationNow() {
    "main thread";

    if (boxMTRef.current) {
      animateMTRef.current = animate(
        boxMTRef.current,
        { scale: 0.4, rotate: "45deg" },
        {
          ease: "circInOut",
          duration: 1,
          repeat: Number.POSITIVE_INFINITY,
          repeatType: "reverse",
        },
      );
    }
  }

  function startAnimation() {
    "main thread";

    if (startTimerMTRef.current) {
      clearTimeout(startTimerMTRef.current);
    }

    startTimerMTRef.current = setTimeout(() => {
      startTimerMTRef.current = null;
      startAnimationNow();
    }, 1000);
  }

  function endAnimation() {
    "main thread";

    if (startTimerMTRef.current) {
      clearTimeout(startTimerMTRef.current);
      startTimerMTRef.current = null;
    }

    animateMTRef.current?.stop();
  }

  useEffect(() => {
    void runOnMainThread(startAnimation)();
    return () => {
      void runOnMainThread(endAnimation)();
    };
  }, []);

  return (
    <ThemeFrame>
      <view className="case-container">
        <view
          className="motion-box"
          main-thread:ref={boxMTRef}
        >
        </view>
      </view>
    </ThemeFrame>
  );
}

root.render(<Basic />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Use Springs

Set `type: 'spring'` when a value should settle with spring physics instead of following a fixed-duration easing curve. All [spring options](https://motion.dev/docs/spring) from Motion are supported, including `stiffness`, `damping`, `mass`, and `bounce`.

**This is an example below: motion**

**Entry:** `src/Spring`
**Bundle:** `dist/spring.lynx.bundle` | Web: `dist/spring.web.bundle`

```tsx {20-24,36-39}
import { animate } from "@lynx-js/motion";
import { root, runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

import { ThemeFrame } from "../shared/ThemeFrame";
import "./styles.css";

export default function Spring() {
  const animateMTRef = useMainThreadRef<ReturnType<typeof animate> | null>(
    null,
  );
  const boxMTRef = useMainThreadRef<MainThread.Element>(null);
  const startTimerMTRef = useMainThreadRef<ReturnType<typeof setTimeout> | null>(
    null,
  );

  function startAnimationNow() {
    "main thread";

    if (boxMTRef.current) {
      animateMTRef.current = animate(
        boxMTRef.current,
        { rotate: 90 },
        { type: "spring", repeat: Number.POSITIVE_INFINITY, repeatDelay: 0.2 },
      );
    }
  }

  function startAnimation() {
    "main thread";

    if (startTimerMTRef.current) {
      clearTimeout(startTimerMTRef.current);
    }

    startTimerMTRef.current = setTimeout(() => {
      startTimerMTRef.current = null;
      startAnimationNow();
    }, 1000);
  }

  function endAnimation() {
    "main thread";

    if (startTimerMTRef.current) {
      clearTimeout(startTimerMTRef.current);
      startTimerMTRef.current = null;
    }

    animateMTRef.current?.stop();
  }

  useEffect(() => {
    void runOnMainThread(startAnimation)();
    return () => {
      void runOnMainThread(endAnimation)();
    };
  }, []);

  return (
    <ThemeFrame>
      <view className="case-container">
        <view
          className="motion-box"
          main-thread:ref={boxMTRef}
        >
        </view>
      </view>
    </ThemeFrame>
  );
}

root.render(<Spring />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Use Motion Values

[`motionValue()`](https://motion.dev/docs/motion-value) stores a value, can be animated directly with `animate()`, and lets you subscribe to changes. Use it when multiple effects or event handlers need a shared animated value.

**This is an example below: motion**

**Entry:** `src/MotionValue`
**Bundle:** `dist/motion-value.lynx.bundle` | Web: `dist/motion-value.web.bundle`

```tsx {21-27,35-40}
import { motionValue } from "@lynx-js/motion";
import type { MotionValue } from "@lynx-js/motion";
import { animate } from "@lynx-js/motion";
import { root, runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

import { ThemeFrame } from "../shared/ThemeFrame";
import "./styles.css";

export default function Basic() {
  const boxMTRef = useMainThreadRef<MainThread.Element>(null);
  const animateMTRef = useMainThreadRef<ReturnType<typeof animate> | null>(
    null,
  );
  const valueMTRef = useMainThreadRef<MotionValue<number>>();
  const unsubscribeMTRef = useMainThreadRef<(() => void) | null>(null);

  function bindMotionValueCallback() {
    "main thread";

    valueMTRef.current ??= motionValue(0.5);

    unsubscribeMTRef.current = valueMTRef.current.on("change", (value) => {
      boxMTRef.current?.setStyleProperties({
        transform: `scale(${value})`,
      });
    });
  }

  function startAnimation() {
    "main thread";

    bindMotionValueCallback();

    if (valueMTRef.current) {
      animateMTRef.current = animate(valueMTRef.current, [0.8, 1.4], {
        duration: 1,
        repeat: Number.POSITIVE_INFINITY,
        repeatType: "reverse",
      });
    }
  }

  function endAnimation() {
    "main thread";

    animateMTRef.current?.stop();

    if (unsubscribeMTRef.current) {
      unsubscribeMTRef.current();
      unsubscribeMTRef.current = null;
    }
  }

  useEffect(() => {
    void runOnMainThread(startAnimation)();
    return () => {
      void runOnMainThread(endAnimation)();
    };
  }, []);

  return (
    <ThemeFrame>
      <view className="case-container">
        <view
          className="motion-box"
          main-thread:ref={boxMTRef}
        >
        </view>
      </view>
    </ThemeFrame>
  );
}

root.render(<Basic />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



## Build Gesture Effects

For high-frequency touch input, keep the event handlers on the main thread with `main-thread:bindtouchstart`, `main-thread:bindtouchmove`, and `main-thread:bindtouchend`. Use motion values with `styleEffect()` to derive visual state from gesture state.

**This is an example below: motion**

**Entry:** `src/iOSSlider`
**Bundle:** `dist/gesture.lynx.bundle` | Web: `dist/gesture.web.bundle`

```tsx {48-68,98-103,109-120}
import {
  animate,
  clamp,
  mapValue,
  mix,
  progress as calcProgress,
  styleEffect,
  transformValue,
  useMotionValueRef,
} from "@lynx-js/motion";
import { root, runOnMainThread, useEffect, useMainThreadRef } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

import SunPng from "./sun.png";

import "./styles.css";

/**
 * ==============   Configuration   ================
 */
const maxPull = 20;
const maxSquish = 0.92;
const maxStretch = 1.08;

export default function Comp() {
  /**
   * ==============   State   ================
   */
  const sliderRef = useMainThreadRef<MainThread.Element>(null);
  const progressRef = useMotionValueRef(0.5);
  const sizeRef = useMainThreadRef({ top: 0, bottom: 0 });
  const initialDragYRef = useMainThreadRef(0);
  const initialProgressYRef = useMainThreadRef(0);

  function measureSlider() {
    "main thread";
    void sliderRef.current?.invoke("boundingClientRect").then(
      (res: { top: number; bottom: number }) => {
        sizeRef.current = { top: res.top, bottom: res.bottom };
      },
    );
  }

  function initEffects() {
    "main thread";
    measureSlider();

    const y = mapValue(progressRef.current, [-1, 0, 1, 2], [
      maxPull,
      0,
      0,
      -maxPull,
    ]);
    const scaleX = mapValue(
      y,
      [-maxPull, 0, 0, maxPull],
      [maxSquish, 1, 1, maxSquish],
    );
    const scaleY = mapValue(
      y,
      [-maxPull, 0, 0, maxPull],
      [maxStretch, 1, 1, maxStretch],
    );

    styleEffect(".slider", { y, scaleX, scaleY });

    styleEffect(".indicator", {
      scaleY: transformValue(() => clamp(0, 1, progressRef.current.get())),
    });

    const invertScaleX = transformValue(() => 1 / scaleX.get());
    const invertScaleY = transformValue(() => 1 / scaleY.get());
    styleEffect(".icon-container", {
      scaleX: invertScaleX,
      scaleY: invertScaleY,
    });
  }

  useEffect(() => {
    void runOnMainThread(initEffects)();
  }, []);

  function onTouchStart(e: MainThread.TouchEvent) {
    "main thread";
    progressRef.current.stop();

    initialDragYRef.current = e.detail.y;
    initialProgressYRef.current = mix(
      sizeRef.current.bottom,
      sizeRef.current.top,
      progressRef.current.get(),
    );
  }

  function onTouchMove(e: MainThread.TouchEvent) {
    "main thread";

    const dragOffset = e.detail.y - initialDragYRef.current;
    const newProgressY = initialProgressYRef.current + dragOffset;

    progressRef.current.set(
      calcProgress(sizeRef.current.bottom, sizeRef.current.top, newProgressY),
    );
  }

  function onTouchEnd(_e: MainThread.TouchEvent) {
    "main thread";
    // Animate back to bounds if needed
    if (progressRef.current.get() < 0) {
      animate(progressRef.current, 0, {
        type: "spring",
        stiffness: 200,
        damping: 60,
      });
    } else if (progressRef.current.get() > 1) {
      animate(progressRef.current, 1, {
        type: "spring",
        stiffness: 200,
        damping: 60,
      });
    }
  }

  return (
    <view className="case-container">
      <view
        className="slider"
        main-thread:ref={sliderRef}
        main-thread:bindtouchstart={onTouchStart}
        main-thread:bindtouchmove={onTouchMove}
        main-thread:bindtouchend={onTouchEnd}
      >
        <view className="indicator"></view>
        <view className="icon-container">
          <image className="icon" src={SunPng} />
        </view>
      </view>
    </view>
  );
}

root.render(<Comp />);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```



:::info
Motion's web-only gesture APIs such as [`scroll()`](https://motion.dev/docs/scroll), [`inView()`](https://motion.dev/docs/inview), [`hover()`](https://motion.dev/docs/hover), and [`press()`](https://motion.dev/docs/press) are not part of `@lynx-js/motion`. Use the main-thread touch events shown above instead.
:::



---
url: /lynx-ui/performance-hint.md
---

# Performance Hint



---
url: /lynx-ui/styling-theming.md
---

# Primitives and Themes

`lynx-ui` is an **unstyled** component library (also known as **headless**). Inspired by [Radix Primitives](https://www.radix-ui.com/primitives) and [Base UI](https://base-ui.com/), it splits each component into two layers:

- **Primitives** are the top-level components you import, such as `Switch`, `Popover`, or `Sheet`. Each primitive handles one interaction pattern end to end, but makes no decisions about appearance.
- **Parts** are the structural pieces that make up a primitive. A `Switch` is composed of `SwitchTrack` and `SwitchThumb`. Each part is a separate element you render and style independently.

Since primitives ship with no visual design, you control appearance through two mechanisms:

- **Styling** defines the appearance of a component instance: its size, spacing, transitions, and state-specific visuals.
- **Theming** defines reusable semantic tokens that many components consume, so a single change to the token layer propagates everywhere.

This guide walks through both in practice, using [LUNA](/lynx-ui/luna-themes-tokens.md) as the theme layer (you can bring your own) and a single `Switch` example that evolves from a bare composition into a reusable themed wrapper, in three steps:

1. [Styling the parts](#styling-the-parts)
2. [Consuming tokens](#consuming-tokens)
3. [Composing themed wrappers](#composing-themed-wrappers)

## Setup

For plain CSS, import LUNA styles so token variables are available as CSS variables at
runtime.

```css
@import '@lynx-js/luna-styles/index.css';
```

For Tailwind, use LUNA tailwind preset to further expose the same tokens
as utilities such as `bg-primary` and `text-content`. Tailwind on Lynx requires
`@lynx-js/tailwind-preset` for runtime compatibility.

```ts
// tailwind.config.ts
import { LunaPreset } from '@lynx-js/luna-tailwind';
import LynxPreset from '@lynx-js/tailwind-preset';
import type { Config } from 'tailwindcss';

const config: Config = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  presets: [LynxPreset, LunaPreset],
};

export default config;
```

:::note

Some Tailwind integrations can provide source scanning automatically, so the
`content` field may not be required in every setup. The examples in this guide
use an additional integration layer beyond the basic Tailwind setup.

:::

## Styling the Parts

Every part of a `lynx-ui` component is intended to be styled by the
application. You render the part and attach your own classes. There is no
hidden built-in visual to override.

Using `Switch`:

```tsx
import { Switch, SwitchThumb, SwitchTrack } from '@lynx-js/lynx-ui';

export function ExampleSwitch() {
  return (
    <Switch className="switch">
      <SwitchTrack className="switch-track" />
      <SwitchThumb className="switch-thumb" />
    </Switch>
  );
}
```

The primitive supplies interaction and state. Your code supplies the visual
rules: root size and layout, track and thumb appearance, and how the
component responds to its various states.

The same composition works equivalently with Tailwind utilities. The only
difference is where the styling rules live:

```tsx
<Switch className="flex items-center w-[48px] h-[28px] rounded-full overflow-hidden">
  <SwitchTrack className="w-full h-full" />
  <SwitchThumb className="absolute w-[22px] h-[22px] rounded-full" />
</Switch>
```

A note on platform props: when a primitive needs to expose lower-level
platform attributes, it does so through explicit props such as `switchProps`
rather than mixing them into the styling API. This keeps the className surface
predictable while still allowing platform-level customization where needed.

## Styling States

Stateful primitives expose styling hooks for component state. This serves the
same purpose as the `data-*` state attributes used by libraries such as Radix
UI and Headless UI, and the `data-*` variants commonly used in Tailwind. In
`lynx-ui`, these hooks are exposed as **UI Variants**, implemented as UI state
classes:

- `ui-checked`
- `ui-active`
- `ui-disabled`

This is what makes headless primitives easy to style without hardcoding design
inside the component implementation.

In plain CSS, you target these states with selectors:

```css
.switch.ui-disabled {
  opacity: 0.5;
}
.switch-track.ui-checked {
  background-color: var(--primary);
}
.switch-track.ui-active {
  background-color: var(--primary-2);
}
.switch-thumb.ui-checked {
  transform: translateX(23px);
}
.switch-thumb.ui-active {
  width: 33px;
}
.switch-thumb.ui-checked.ui-active {
  transform: translateX(12px);
}
```

In Tailwind, the same states are expressed with variant chains:

```tsx
<SwitchTrack
  className="bg-neutral-faint
    ui-checked:bg-primary
    ui-active:bg-primary-2"
/>
<SwitchThumb
  className="bg-primary-content
    ui-checked:transform-[translateX(23px)]
    ui-active:w-[33px]
    ui-checked:ui-active:transform-[translateX(12px)]"
/>
```

:::note

This guide uses `transform-[translateX(...)]` instead of `translate-x-[...]`
for transform values.

`@lynx-js/tailwind-preset` is currently built on top of Tailwind v3, but it
adds support for this transform syntax. `translate-x-[...]` relies on CSS
variables, which have known issues in lower-version Lynx runtimes when used
with transitions or animations.

:::

When multiple states can be active at the same time, such as `checked` and `pressed`, make priority explicit. The `ui-checked:ui-active:` chain above is
intentional: it overrides the plain `ui-checked` translation when both states
apply, so the visual stays coherent during interaction. Whether you use
selectors or utilities, treat overlapping states as a design decision rather
than something to leave to specificity.

**This is an example below: lynx-ui-switch**

**Entry:** `BasicTailwind`
**Bundle:** `dist/SwitchBasicTailwind.lynx.bundle` | Web: `dist/SwitchBasicTailwind.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { Switch, SwitchThumb, SwitchTrack } from '@lynx-js/lynx-ui'
import type { SwitchProps } from '@lynx-js/lynx-ui'
import { clsx } from 'clsx'

import { hitSlop } from '../shared/hitSlop'

export function StyledSwitch({
  checked,
  defaultChecked,
  disabled,
  onChange,
  className,
  style,
  switchProps,
}: SwitchProps) {
  return (
    <Switch
      className={clsx(
        'flex flex-row items-center w-[48px] h-[28px] rounded-full overflow-hidden',
        'ui-disabled:opacity-50',
        className,
      )}
      checked={checked}
      defaultChecked={defaultChecked}
      disabled={disabled}
      onChange={onChange}
      style={style}
      switchProps={{ ...hitSlop, ...switchProps }}
    >
      {/* Track */}
      <SwitchTrack
        className={clsx(
          'size-full',
          'transition-colors duration-150 ease-out',
          'bg-neutral-faint',
          'ui-checked:bg-primary',
          'ui-active:bg-primary-2',
          'ui-checked:ui-active:bg-primary-2',
        )}
      />

      {/* Thumb */}
      <SwitchThumb
        className={clsx(
          // positioned relative to Switch root
          'absolute size-[22px] rounded-full bg-primary-content shadow',
          'transition-all duration-150 ease-out',
          // base position
          'transform-[translateX(3px)]',
          // checked position
          'ui-checked:transform-[translateX(23px)]',
          // Jelly press
          'ui-active:w-[33px]',
          // checked position offset for jelly effect
          'ui-checked:ui-active:transform-[translateX(12px)]',
        )}
      />
    </Switch>
  )
}

```



## Consuming Tokens

Notice that the styles above never hard-code literal colors. Instead, they
reference semantic tokens such as `primary` and `content`.

Semantic tokens name the intent of a value in the interface, not the raw value
itself. For example, `primary` means “the main accent in the current theme”,
and `content` means “primary foreground content”.

In this guide, you will most often see those tokens consumed as CSS property
values (`var(--primary)` and `var(--content)`) or Tailwind utilities
(`bg-primary` and `text-content`). These forms all resolve to the same runtime
token values.

Semantic tokens matter for two reasons:

- **Consistency.** A `Button`, a `Switch`, and a `Checkbox` that all read from
  `primary` stay in sync automatically. Changing the token updates every
  surface that consumes it.
- **Themeability.** Components depend on roles such as `primary` and `content`,
  rather than concrete colors. A theme can change what those roles resolve to
  across light, dark, or brand variants without rewriting component styles.

In practice, this means the concrete values for these semantic roles are
provided by the active theme scope on an ancestor node, following the same ancestor-based
theme switching pattern described in the [custom theming guide](/guide/styling/custom-theming.md),
where a theme class is applied at the container level and descendant styles resolve against that
shared theme scope.

Instead of branching styles per theme:

```tsx
<Button className="bg-pink-500 dark:bg-pink-300 text-white dark:text-black" />
```

Prefer semantic tokens over color scalesIn Tailwind utilities, the prefix describes the CSS property, such as `bg-` for
background color or `text-` for text color. The value after the prefix is what
matters for theming.
Values such as `pink-500` and `pink-300` may still come from a design scale,
but that scale is usually global: `pink-500` means the same concrete color
regardless of whether the current theme is light, dark, or brand-specific.
This makes it less suitable for components that need to adapt across multiple
themes.
Semantic values such as `primary` and `primary-content` describe the role of a
style instead. The active theme decides what those roles resolve to, so the
same component style can stay stable while the visual result changes with the
theme.

Components should consume semantic tokens and stay visually stable:

```tsx
<Button className="bg-primary text-primary-content" />
```

Theme switching then happens at the container level:

```tsx
<view className="lunaris-dark">
  {/* themed subtree */}
  <Button className="bg-primary text-primary-content" />
  <Switch className="switch">
    <SwitchTrack className="switch-track" />
    <SwitchThumb className="switch-thumb" />
  </Switch>
</view>
```

Changing the ancestor theme class, for example from `lunaris-dark` to
`lunaris-light`, updates the token values for the entire subtree without
rewriting individual component styles.

In `lynx-ui`, this container-scoped theme model is implemented by LUNA, which
provides four built-in theme classes: `luna-light`, `luna-dark`,
`lunaris-light`, and `lunaris-dark`.

For token names, surface hierarchy, and theme overriding,
see the [LUNA Themes and Tokens](/lynx-ui/luna-themes-tokens.md) documentation.

## Composing Themed Wrappers

Once a styling pattern repeats, the next step is to compose a themed wrapper
on top of the primitive. This gives you a stable, product-facing API without
losing the flexibility of the underlying parts.

The pattern is to wrap each part separately, encode your defaults in those
wrappers, and export a convenience composition for the common case:

```tsx
import {
  Switch as SwitchPrimitive,
  SwitchThumb as SwitchThumbPrimitive,
  SwitchTrack as SwitchTrackPrimitive,
} from '@lynx-js/lynx-ui';
import type {
  SwitchProps,
  SwitchThumbProps,
  SwitchTrackProps,
} from '@lynx-js/lynx-ui';
import { clsx } from 'clsx';

export function ThemedSwitch(props: SwitchProps) {
  return (
    <ThemedSwitchRoot {...props}>
      <ThemedSwitchTrack />
      <ThemedSwitchThumb />
    </ThemedSwitchRoot>
  );
}

export function ThemedSwitchRoot({ className, ...props }: SwitchProps) {
  return (
    <SwitchPrimitive
      className={clsx(
        'flex flex-row items-center w-[48px] h-[28px] rounded-full overflow-hidden',
        'ui-disabled:opacity-50',
        className,
      )}
      {...props}
    />
  );
}

export function ThemedSwitchTrack({ className }: SwitchTrackProps) {
  return (
    <SwitchTrackPrimitive
      className={clsx(
        'size-full transition-colors duration-150 ease-out',
        'bg-neutral-faint ui-checked:bg-primary ui-active:bg-primary-2',
        className,
      )}
    />
  );
}

export function ThemedSwitchThumb({ className }: SwitchThumbProps) {
  return (
    <SwitchThumbPrimitive
      className={clsx(
        'absolute size-[22px] rounded-full bg-primary-content shadow',
        'transition-all duration-150 ease-out transform-[translateX(3px)]',
        'ui-checked:transform-[translateX(23px)]',
        'ui-active:w-[33px]',
        'ui-checked:ui-active:transform-[translateX(12px)]',
        className,
      )}
    />
  );
}
```

A few things to notice in this final form:

- Each part is wrapped individually, so consumers can still override any one
  of them without rebuilding the rest.
- The convenience `ThemedSwitch` covers the common case but does not block
  the part-level API.
- Defaults for sizing, transitions, and state visuals are encoded once and reused everywhere.
- The token layer (`bg-primary`, `bg-neutral-faint`, `bg-primary-content`)
  carries through unchanged; the wrapper adds defaults, not new colors.

This is a typical [shadcn/ui](https://ui.shadcn.com/)-style composition pattern: primitives stay public and composable, while themed components become the default product-facing implementation.

The example below applies the pattern in a real UI: a controlled switch drives container theme,
and nested surfaces can override theme independently. The same demo is embedded on the [`<Switch>`](/lynx-ui/components/switch.md) page.

**This is an example below: lynx-ui-switch**

**Entry:** `Themed`
**Bundle:** `dist/SwitchThemed.lynx.bundle` | Web: `dist/SwitchThemed.web.bundle`

```tsx
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { clsx } from 'clsx'

import {
  ThemedSwitch,
  ThemedSwitchRoot,
  ThemedSwitchThumb,
  ThemedSwitchTrack,
} from './themed-switch'
import './index.css'

function App() {
  const [outerDark, setOuterDark] = useState(true)
  const [innerLight, setInnerLight] = useState(false)

  return (
    <view
      className={clsx(
        'size-full flex flex-col justify-center px-[48px] py-[72px]',
        'luna-gradient-berry',
        outerDark ? 'lunaris-dark' : 'lunaris-light',
      )}
    >
      <view className='flex flex-col gap-[24px] px-[48px] py-[64px] rounded-[16px] overflow-hidden text-content bg-canvas'>
        <text className='text-lg text-content-2'>Theme Switching</text>

        {/* 1) Outer container theme toggle (uses composed component) */}
        <view className='flex flex-row items-center gap-[16px] w-full'>
          <ThemedSwitch checked={outerDark} onChange={setOuterDark} />
          <text className='text-base text-content-2'>
            {outerDark ? 'lunaris-dark' : 'lunaris-light'}
          </text>
        </view>

        <view
          className={clsx(
            'flex flex-col mt-[16px] gap-[10px] py-[16px] px-[16px] rounded-[16px] overflow-hidden bg-canvas border border-line',
            innerLight ? 'lunaris-light' : 'lunaris-dark',
          )}
        >
          {/* 3) Inner container theme toggle (uses themed Primitives)*/}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitchRoot
              defaultChecked={innerLight}
              onChange={setInnerLight}
            >
              <ThemedSwitchTrack />
              <ThemedSwitchThumb />
            </ThemedSwitchRoot>
            <text className='text-base text-content-2'>
              {innerLight ? 'lunaris-light' : 'lunaris-dark'}
            </text>
          </view>
          {/* 3) Inner disabled sample */}
          <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
            <ThemedSwitch disabled checked={innerLight} />
            <text className='text-base text-content-2 opacity-50'>
              Disabled
            </text>
          </view>
        </view>
        {/* 4) Outer disabled sample */}
        <view className='flex flex-row items-center gap-[16px] w-full pt-[8px]'>
          <ThemedSwitch disabled checked={outerDark} />
          <text className='text-base text-content-2 opacity-50'>Disabled</text>
        </view>
      </view>
    </view>
  )
}

root.render(<App />)
export default App

```



## Best Practices

- Keep primitives visually unopinionated. The application owns appearance.
- Style each rendered part explicitly rather than relying on hidden defaults.
- Prefer semantic tokens over literal colors, even early in development.
- Make state priority explicit when multiple states can overlap.
- Promote a styled pattern to a wrapper only after it repeats, not before.
- Treat theming as a shared vocabulary across surfaces, not as a color dump.

## Summary

`lynx-ui` primitives are unstyled: they give you full control over appearance without taking behavior away from you. Style the parts directly with plain CSS or Tailwind, consume semantic tokens from a layer like LUNA so visual decisions stay consistent, and compose themed wrappers when a pattern is ready to be reused.



---
url: /lynx-ui/troubleshooting.md
---

# 




---
url: /react/best-practices.md
---

# Best Practices

:::tip Agent Skill Available
These best practices are also available as an [Agent Skill](https://github.com/lynx-community/skills) for your coding agents. Install with `npx skills add lynx-community/skills` to get automated detection and auto-fix in your editor.
:::

This page covers common patterns and pitfalls when developing with ReactLynx, with a focus on Lynx's dual-thread architecture.

## Use `'background only'` for Native API Calls \{#detect-background-only}

**Severity: Critical**

In Lynx's dual-thread architecture, the **main thread** handles React component rendering and JSX evaluation, while the **background thread** manages effects, event handlers, and native module calls. Calling native APIs like `lynx.getJSModule` or `NativeModules` on the main thread causes UI blocking, synchronization overhead, and degraded user experience.

### Bad

```tsx
// ❌ Native API call at component top level — runs on main thread
function App() {
  const data = NativeModules.Storage.get('key');
  return <text>{data}</text>;
}
```

```tsx
// ❌ Native API call inside render logic
function App() {
  return <text>{lynx.getJSModule('GlobalEventEmitter').emit('event')}</text>;
}
```

### Good

Native module calls are permitted in contexts that execute on the background thread:

```tsx
// ✅ Inside useEffect — runs on background thread
function App() {
  const [data, setData] = useState('');

  useEffect(() => {
    const value = NativeModules.Storage.get('key');
    setData(value);
  }, []);

  return <text>{data}</text>;
}
```

```tsx
// ✅ Inside event handler — runs on background thread
function App() {
  function handleTap() {
    lynx.getJSModule('GlobalEventEmitter').emit('event');
  }

  return (
    <view bindtap={handleTap}>
      <text>Tap me</text>
    </view>
  );
}
```

```tsx
// ✅ Using the 'background only' directive
function fetchData() {
  'background only';
  return NativeModules.Storage.get('key');
}
```

### Allowed Contexts

Native module calls are safe in:

- `useEffect` / `useLayoutEffect` hooks
- `useImperativeHandle` implementations
- Ref callbacks
- Event handlers (`bindtap`, etc.)
- Functions marked with `'background only'` directive

### The `'background only'` Directive

When a function containing native calls doesn't naturally fit into one of the above contexts, mark it with the `'background only'` directive as the first statement in the function body:

```tsx
function sendAnalytics(eventName: string) {
  'background only';
  lynx.getJSModule('Analytics').track(eventName);
}
```

Both single and double quotes work: `'background only'` and `"background only"`.

## Use Event Handlers Correctly \{#proper-event-handlers}

**Severity: Medium**

Event handlers in ReactLynx run on the **background thread**, making them safe for native module calls, API requests, and heavy computations.

### Event Handler Types

| Attribute  | Behavior             | Use Case                            |
| ---------- | -------------------- | ----------------------------------- |
| `bindtap`  | Bubbles up to parent | Default choice for tap events       |
| `catchtap` | Stops propagation    | Prevent parent handlers from firing |

### Basic Usage

Use function references over inline functions for better performance:

```tsx
// ✅ Function reference (recommended)
function App() {
  function handleTap(event) {
    console.log('Target id:', event.target.id);
  }

  return (
    <view id="my-view" bindtap={handleTap}>
      Tap me
    </view>
  );
}
```

### Event Propagation

**Bubbling with `bindtap`:**

```tsx
function App() {
  function handleOuterTap() {
    console.log('outer tapped'); // Fires second
  }
  function handleInnerTap() {
    console.log('inner tapped'); // Fires first
  }

  return (
    <view bindtap={handleOuterTap}>
      <view bindtap={handleInnerTap}>Inner</view>
    </view>
  );
}
// Clicking Inner outputs: "inner tapped", "outer tapped"
```

**Stopping propagation with `catchtap`:**

```tsx
function App() {
  function handleOuterTap() {
    console.log('outer tapped'); // Never fires
  }
  function handleInnerTap() {
    console.log('inner tapped'); // Only this fires
  }

  return (
    <view bindtap={handleOuterTap}>
      <view catchtap={handleInnerTap}>Inner</view>
    </view>
  );
}
```

### Using `dataset`

Pass custom data via `data-` attributes instead of closures:

```tsx
function App() {
  function handleTap(event) {
    const { itemId, itemName } = event.currentTarget.dataset;
    console.log(`Tapped item: ${itemId} - ${itemName}`);
  }

  return (
    <view data-item-id="123" data-item-name="Product" bindtap={handleTap}>
      Tap me
    </view>
  );
}
```

### Tips

1. **Use function references** over inline arrow functions for better performance
2. **Use `catchtap`** only when you need to stop event propagation
3. **Use `dataset`** to pass data instead of closures when possible
4. **Prefer `currentTarget`** over `target` for accessing the listening element's data

## Use Main Thread Scripts for Smooth Animations \{#main-thread-scripts}

**Severity: Medium**

In Lynx's multi-threaded architecture, events are triggered on the main thread, but regular JS event handlers execute on the background thread. This round-trip causes delays that are noticeable in animations and gesture handling. Main thread scripts provide **synchronous event handling on the main thread**, eliminating response delay.

### Bad

```tsx
// ❌ Scroll handler on background thread — animation lags behind gesture
function App() {
  const [pos, setPos] = useState(0);

  function onScroll(event) {
    setPos(event.detail.scrollTop);
  }

  return (
    <scroll-view global-bindscroll={onScroll}>
      <view style={{ transform: `translateY(${pos}px)` }} />
    </scroll-view>
  );
}
```

### Good

```tsx
// ✅ Scroll handler on main thread — no delay
function App() {
  function onScroll(event: MainThread.IScrollEvent) {
    'main thread';
    const scrollTop = event.detail.scrollTop;
    event.currentTarget.setStyleProperty(
      'transform',
      `translateY(${scrollTop}px)`,
    );
  }

  return (
    <scroll-view main-thread:global-bindscroll={onScroll}>
      <view />
    </scroll-view>
  );
}
```

### How to Use

1. Add the `main-thread:` prefix to the event attribute:

```tsx
<view main-thread:bindtap={onTap} />
```

2. Declare the function with the `'main thread'` directive:

```tsx
function onTap(event: MainThread.ITouchEvent) {
  'main thread';
  event.currentTarget.setStyleProperty('background-color', 'red');
}
```

### Using `main-thread:ref`

Use `useMainThreadRef()` to get a node object usable on the main thread:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

function App() {
  const textRef = useMainThreadRef<MainThread.Element>();

  function handleTap(event: MainThread.ITouchEvent) {
    'main thread';
    textRef.current?.setStyleProperty('background-color', 'red');
  }

  return (
    <view main-thread:bindtap={handleTap}>
      <text main-thread:ref={textRef}>This text changes</text>
    </view>
  );
}
```

### Maintaining State in Main Thread

Use `MainThreadRef` to persist state between main thread function calls:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

function App() {
  const countRef = useMainThreadRef(0);

  function handleTap(event: MainThread.ITouchEvent) {
    'main thread';
    countRef.current++;
    event.currentTarget.setStyleProperty(
      'background-color',
      countRef.current % 2 ? 'blue' : 'green',
    );
  }

  return <view main-thread:bindtap={handleTap} />;
}
```

### Rules

| Rule                                                   | Description                       |
| ------------------------------------------------------ | --------------------------------- |
| Must use `'main thread'` directive                     | First statement in function body  |
| Use `main-thread:` prefix for events                   | e.g., `main-thread:bindtap`       |
| Captured variables must be JSON-serializable           | Passed via `JSON.stringify()`     |
| Cannot modify captured variables                       | Read-only access from main thread |
| `MainThreadRef.current` only accessible in main thread | Use `useMainThreadRef()`          |

## Hoist Static JSX Elements \{#hoist-static-jsx}

**Severity: Low**

When JSX elements are defined inside component functions, they get recreated on every render cycle. For static elements that never change, this is unnecessary work. Extract them as constants outside the component.

### Bad

```tsx
// ❌ Static element recreated on every render
function App({ title }) {
  return (
    <view>
      <text>{title}</text>
      <view className="animate-pulse h-20 bg-gray-200" />
    </view>
  );
}
```

### Good

```tsx
// ✅ Static element hoisted outside — reused across renders
const loadingSkeleton = <view className="animate-pulse h-20 bg-gray-200" />;

function App({ title }) {
  return (
    <view>
      <text>{title}</text>
      {loadingSkeleton}
    </view>
  );
}
```

This is especially helpful for large, static SVG nodes, which can be expensive to recreate.

:::note
If your project uses [React Compiler](https://react.dev/learn/react-compiler), it automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
:::



---
url: /react/code-splitting.md
---

# Code Splitting

> Rspack supports code splitting, which allows splitting the code into other chunks. You have the full control about size and number of generated assets, which allow you to gain performance improvements in loading time.
>
> [Rspack - Code Splitting](https://rspack.rs/guide/optimization/code-splitting)

## Lazy-loading components

Usually, you import components with the static import declaration:

<!-- eslint-disable import/no-unresolved -->

```jsx
import LazyComponent from './LazyComponent.jsx';

export function App() {
  return (
    <view>
      <LazyComponent />
    </view>
  );
}
```

To defer loading this component’s code until it’s rendered for the first time, replace this import with:

<!-- eslint-disable import/no-unresolved -->

```diff
- import LazyComponent from './LazyComponent.jsx'
+ import { lazy } from '@lynx-js/react'
+ const LazyComponent = lazy(() => import('./LazyComponent.jsx'))
```

This code relies on [dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), which is supported by Rspack. Using this pattern requires that the lazy component you are importing was exported as the default export.

Now that your component’s code loads on demand, you also need to specify what should be displayed while it is loading. You can do this by wrapping the lazy component or any of its parents into a `<Suspense>` boundary:

:::info
The split components will only start downloading when they are rendered.
:::

<!-- eslint-disable import/no-unresolved -->

```jsx title="src/App.tsx"
import { Suspense, lazy } from '@lynx-js/react';

const LazyComponent = lazy(() => import('./LazyComponent.jsx'));

export function App() {
  return (
    <view>
      <Suspense fallback={<text>Loading...</text>}>
        <LazyComponent />
      </Suspense>
    </view>
  );
}
```

### Load lazy component when needed

In this example, the code for `LazyComponent` won’t be loaded until you attempt to render it. If `LazyComponent` hasn’t loaded yet, a "Loading..." will be shown in its place. For example:

<!-- eslint-disable import/no-unresolved -->

```jsx title="src/App.tsx"
import { Suspense, lazy, useState } from '@lynx-js/react';

const LazyComponent = lazy(() => import('./LazyComponent.jsx'));

export function App() {
  const [shouldDisplay, setShouldDisplay] = useState(false);
  const handleClick = () => {
    setShouldDisplay(true);
  };
  return (
    <view>
      <view bindtap={handleClick}>Load Component</view>
      {shouldDisplay && (
        <Suspense fallback={<text>Loading...</text>}>
          <LazyComponent />
        </Suspense>
      )}
    </view>
  );
}
```

:::warning Differences from the Web
In Lynx, CSS is scoped to each [Bundle](/api/lynx-native-api/template-bundle.md). Since lazy-loaded components generate their own Bundles (see output structure at [Output Files](/rspeedy/output.md)), you shouldn’t expect them to behave like on the Web. Global CSS defined in the main Bundle will not affect lazy-loaded components, and vice versa.
:::

### Error handling

#### Use ErrorBoundary

If loading is completed, lazy-loaded components are essentially also a React component, so the error handling practices in React are still applicable.

Checkout [React - Catching rendering errors with an error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) for details.

## Lazy-loading standalone project

You may also lazy-load modules that being built in a standalone Rspeedy project.

### Glossary of Terms

- Producer (Remote): An application that exposes modules to be consumed by other Lynx applications.
- Consumer (Host): An application that consumes modules from other Producers.

### Create a standalone Producer project

Create a standalone project using [`create-rspeedy`](https://npmjs.com/create-rspeedy):

```bash
pnpm create rspeedy@latest
```

Then add [`experimental_isLazyBundle`] to the options of `pluginReactLynx` in the `lynx.config.js`:

```js
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginReactLynx({
      experimental_isLazyBundle: true,
    }),
  ],
});
```

Finally, change the `index.tsx` to export the `App`.

<!-- eslint-disable-next-line import/no-unresolved -->

```js title="src/index.tsx"
import { App } from './App.jsx';

export default App;
```

### Modify the Consumer project

To load the Producer project, add an import to `@lynx-js/react/experimental/lazy/import` at the beginning of the entry.

<!-- eslint-disable import/no-unresolved -->

```jsx title="src/index.tsx"
import '@lynx-js/react/experimental/lazy/import';
import { root } from '@lynx-js/react';

import { App } from './App.jsx';

root.render(<App />);
```

This would provide essential APIs that the Producer needs.

Then, the Producer could be loaded using [dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import).

<!-- eslint-disable import/no-unresolved -->

```jsx title="src/App.tsx"
import { Suspense, lazy } from '@lynx-js/react';

const LazyComponent = lazy(
  () =>
    import('https://<host>:<port>/path/to/lynx.bundle', {
      with: { type: 'component' },
    }),
);

export function App() {
  return (
    <view>
      <Suspense fallback={<text>Loading...</text>}>
        <LazyComponent />
      </Suspense>
    </view>
  );
}
```

### Developing Producer project

It is recommended to create a separated Consumer in the Producer project.

<!-- eslint-disable import/no-unresolved -->

```jsx title="src/Consumer.tsx"
import { Suspense, lazy, root } from '@lynx-js/react';

// You may use static import if you want
const App = lazy(() => import('./App.jsx'));

root.render(
  <Suspense>
    <App />
  </Suspense>,
);
```

Then, create a separated `lynx.config.consumer.js`:

```js title="lynx.config.consumer.js"
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/Consumer.tsx',
  },
  plugins: [pluginReactLynx()],
});
```

Use `npx rspeedy dev --config lynx.config.consumer.js` to start developing the producer project.

[`experimental_isLazyBundle`]: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.experimental_islazybundle.md



---
url: /react/data-fetching.md
---

# Data Fetching

Whether fetching static content from a remote server or interacting with a REST API, ReactLynx applications often need to retrieve data from external sources. For example, you might want to load user posts in a social media app or fetch the latest product listings in an e-commerce application.

Lynx provides the [Fetch API](/api/lynx-api/global/fetch.md), enabling you to make network requests. You can refer to the [Networking](/guide/interaction/networking.md) chapter for more details. The Fetch API provided by Lynx can be used together with server state management libraries from the React ecosystem, such as [TanStack Query (React Query)](https://tanstack.com/query), to simplify data fetching and state management.

It is important to note that Lynx's Fetch API has subtle differences compared to the [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). You can check the [Fetch API Reference - Compatibility](/api/lynx-api/global/fetch.md#compatibility) section to learn more about these differences. As a result, you may need to adapt libraries from the React ecosystem to ensure compatibility. If you encounter any issues on Lynx Fetch API, you are welcome to submit feature requests or [contribute](https://github.com/lynx-family/lynx/blob/develop/CONTRIBUTING.md) to help Lynx better support the React ecosystem.

## Using TanStack Query

TanStack Query is a popular server state management library in the React ecosystem, helping developers easily manage data fetching and caching.

### Installing Dependencies


```sh [npm]
npm install @tanstack/react-query
```

```sh [yarn]
yarn add @tanstack/react-query
```

```sh [pnpm]
pnpm add @tanstack/react-query
```

```sh [bun]
bun add @tanstack/react-query
```

```sh [deno]
deno add npm:@tanstack/react-query
```

### Example

The following example application shows how to use TanStack Query with the Fetch API in ReactLynx to fetch, display, and delete user posts provided by the [JSONPlaceholder API](https://jsonplaceholder.typicode.com/).

The application first uses the [`useQuery`](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) hook from TanStack Query to call `fetchPosts`, fetching and displaying the first 10 posts. When the user clicks the "Delete Post 1" button, it triggers an [Optimistic Update](https://tanstack.com/query/v4/docs/framework/react/guides/optimistic-updates) using the [`useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) hook: the post with `id` 1 is immediately removed from the list, and the `deletePost` function calls the Fetch API to send a delete request. If the request fails, the state will roll back to its original state.

**This is an example below: networking**

**Entry:** `src/react-query`
**Bundle:** `dist/react-query.lynx.bundle`

```tsx
import { root } from "@lynx-js/react";
import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import "./index.scss";

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

const queryClient = new QueryClient();

const fetchPosts = async (): Promise<Post[]> => {
  const response = await fetch("https://jsonplaceholder.typicode.com/posts");
  if (!response.ok) {
    throw new Error("Failed to fetch posts");
  }
  const data = await response.json();
  return data.slice(0, 10); // Only show the first 10 posts
};

const deletePost = async (postId: number) => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/posts/${postId}`,
    {
      method: "DELETE",
    },
  );
  if (!response.ok) {
    throw new Error("Failed to delete post");
  }
  return postId;
};

const App = () => {
  const queryClient = useQueryClient();

  // Fetch posts
  const {
    data: posts,
    isLoading,
    isError,
    error,
  } = useQuery({
    queryKey: ["posts"],
    queryFn: fetchPosts,
  });

  // Mutation to delete post optimistically
  const mutation = useMutation({
    mutationFn: () => deletePost(1),
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey: ["posts"] });

      // Snapshot current state
      const previousPosts = queryClient.getQueryData<Post[]>(["posts"]);

      // Optimistically remove post with ID 1
      queryClient.setQueryData(["posts"], (oldPosts: Post[] | undefined) => {
        return oldPosts ? oldPosts.filter((post) => post.id !== 1) : [];
      });

      // Return previous state to OnError for rolling back optimistic update
      return { previousPosts };
    },
    onError: (err, variables, context) => {
      // Rollback to previous state
      if (context?.previousPosts) {
        queryClient.setQueryData(["posts"], context.previousPosts);
      }
    },
  });

  const deleteFirstPost = () => {
    "background only";
    mutation.mutate();
  };

  return (
    <view className="container">
      {isLoading ? <text className="container__loading">Loading...</text> : isError
        ? (
          <text className="container__error">
            {error?.message || "Error fetching posts"}
          </text>
        )
        : (
          posts?.map((post) => (
            <view key={post.id} className="container__post">
              <text className="container__post-text">{`${post.id} : ${post.title}`}</text>
            </view>
          ))
        )}

      {/* Button to trigger mutation */}
      <view bindtap={deleteFirstPost} className="container__button">
        <text className="container__button-text">Delete Post 1</text>
      </view>
    </view>
  );
};

root.render(
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>,
);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

```





---
url: /react/genui/a2ui.md
---

# A2UI

[A2UI](https://a2ui.org/introduction/what-is-a2ui/) (Agent-to-UI), initiated by Google, is a protocol for Agent-generated user interfaces.
The protocol requires the Agent to emit declarative UI description messages constrained by a Schema,
which the [Renderer](https://a2ui.org/glossary/#a2ui-agent-and-a2ui-renderer) validates and renders against a pre-authorized [Catalog](https://a2ui.org/concepts/catalogs/), mapping the protocol messages into a native UI tree.

A2UI is purely a protocol; it does not introduce a new rendering framework. The actual rendering pipeline, component implementations, and platform capabilities remain the responsibility of each runtime implementation, so they can stay aligned with your existing technology stack.
The [A2UI community](https://a2ui.org/ecosystem/renderers/) has already produced renderer implementations across Web, mobile, and desktop platforms.

[@lynx-js/genui/a2ui](https://www.npmjs.com/package/@lynx-js/genui) is the A2UI rendering implementation for [ReactLynx](/react/introduction.md).
Protocol messages produced by the Agent are mapped to native components through Lynx's rendering pipeline and can directly reuse the component library, design system, and theming infrastructure of an existing Lynx app. As a result, generated UI remains consistent with existing UI in both visuals and interaction experience.

You can start with the [Mock Example](#mock-example), then explore the [Playground](#try-the-playground), and finally read the [Integration Guide](#integration-guide); if you want to better understand the principles behind the Agent + Catalog collaboration model, continue with [Core Concepts and Use Cases](#core-concepts-and-use-cases).

## Mock Example

The example below simulates the full workflow of a weather-query Agent:

- The Renderer first exposes Catalog entries such as weather cards and city buttons to the Agent, and establishes a connection with the Agent.
- The Agent uses that information to choose the corresponding components and progressively generate A2UI protocol messages.
- After the Renderer receives those messages, it writes them into the A2UI runtime. A2UI validates the components and data, then hands them to ReactLynx to render the weather cards.
- When you click a different city, the page sends that operation back to the Agent as an [Action](https://a2ui.org/concepts/actions/).
- The Agent continues generating protocol messages for the new city, and A2UI parses those messages into updated component data to refresh the page.

**This is an example below: a2ui**

**Entry:** `src`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { A2UI, Button, Card, Column, createMessageStore, defineCatalog, Image, Row, Text } from "@lynx-js/genui/a2ui";
import type { CatalogComponent, MessageStore } from "@lynx-js/genui/a2ui";
import { catalogManifests } from "@lynx-js/genui/a2ui/catalog";
import { useCallback, useEffect, useMemo, useRef, useState } from "@lynx-js/react";

import { actionMessages, initialMessages } from "./demoMessages.js";
import { Loading, loadingManifest } from "./Loading.js";
import { createMockAgent } from "./mockAgent.js";
import type { MockAgent, MockAgentProgress } from "./mockAgent.js";

import "./App.css";

const STREAM_DELAY_MS = 760;

const ALL_BUILTINS = defineCatalog([
  [Text as CatalogComponent, catalogManifests.Text],
  [Image as CatalogComponent, catalogManifests.Image],
  [Row as CatalogComponent, catalogManifests.Row],
  [Column as CatalogComponent, catalogManifests.Column],
  [Card as CatalogComponent, catalogManifests.Card],
  [Button as CatalogComponent, catalogManifests.Button],
  [Loading as CatalogComponent, loadingManifest],
]).components;
function createSession(
  onProgress: (progress: MockAgentProgress) => void,
): {
  store: MessageStore;
  agent: MockAgent;
} {
  const store = createMessageStore();
  const agent = createMockAgent(store, {
    initialMessages,
    actionMocks: actionMessages,
    delayMs: STREAM_DELAY_MS,
    onProgress,
  });

  return { store, agent };
}

export function App() {
  const agentRef = useRef<MockAgent | null>(null);
  const [sessionId, setSessionId] = useState(0);
  const [progress, setProgress] = useState<MockAgentProgress>({
    deliveredCount: 0,
    totalCount: initialMessages.length,
    status: "idle",
  });

  const session = useMemo(() => {
    "background only";
    return createSession(setProgress);
  }, [sessionId]);

  useEffect(() => {
    agentRef.current?.stop();
    agentRef.current = session.agent;
    void session.agent.start();

    return () => {
      session.agent.stop();
      if (agentRef.current === session.agent) {
        agentRef.current = null;
      }
    };
  }, [session]);

  const replay = useCallback(() => {
    "background only";
    setSessionId((value) => value + 1);
  }, []);

  const statusText = progress.status === "done"
    ? "stream complete"
    : `streaming ${Math.min(progress.deliveredCount, progress.totalCount)}/${progress.totalCount}`;

  return (
    <page>
      <view className="page">
        <view className="topbar">
          <view className="status">
            <view className={`status-dot status-dot--${progress.status}`} />
            <text className="status-text">{statusText}</text>
          </view>
          <view className="replay-button" bindtap={replay}>
            <text className="replay-icon">↻</text>
            <text className="replay-label">Replay</text>
          </view>
        </view>

        {session?.store && (
          <scroll-view scroll-orientation="vertical" className="scroll">
            <A2UI
              key={sessionId}
              messageStore={session.store}
              catalogs={ALL_BUILTINS}
              onAction={(action) => {
                void agentRef.current?.onAction(action);
              }}
              wrapSurface={(children) => <view className="a2ui-surface">{children}</view>}
              renderEmpty={() => (
                <view className="empty-state">
                  <view className="loading-mark" />
                  <text className="empty-title">Rendering UI</text>
                </view>
              )}
              className="a2ui-container"
            />
          </scroll-view>
        )}
      </view>
    </page>
  );
}

```



## Try the Playground

The Lynx A2UI Playground offers a complete interactive experience that covers the full path from model conversation to UI rendering:

- [Create](https://lynx-stack.dev/a2ui/#/a2ui/create): Chat with the model directly and observe in real time how Agent messages drive UI generation and updates, showcasing the full end-to-end pipeline.
- [Examples](https://lynx-stack.dev/a2ui/#/a2ui/examples): A rich set of built-in generated cases that you can edit and replay, making it easy to study the relationship between protocol messages and rendered output.
- [Catalog](https://lynx-stack.dev/a2ui/#/a2ui/catalog): Browse all built-in Catalog components, freely compose them, and preview the rendered result.

## Integration Guide

If you plan to integrate A2UI into a ReactLynx application, we recommend reading the [Lynx A2UI integration guide](https://lynx-stack.dev/guide/genui/a2ui) end to end. The guide is organized as an overview page plus several subpages covering runtime mechanics, Catalog configuration, and extensibility:

- [Quick Start](https://lynx-stack.dev/guide/genui/a2ui): The shortest path to bring up A2UI integration from scratch, clarifying the boundaries among the Renderer, CLI, Agent service, and transport layer.
- [Architecture](https://lynx-stack.dev/guide/genui/a2ui/architecture): A walkthrough of the Renderer architecture, key modules, and exposed capabilities, helping you understand the full data flow of protocol messages from enqueue to render.
- [Catalog Usage and Extension](https://lynx-stack.dev/guide/genui/a2ui/catalogs): The end-to-end engineering workflow around the A2UI Catalog, covering Manifest organization, syncing JSON Schemas to the Agent, registering custom Catalogs, and composing the built-in Catalog on demand.

## Core Concepts and Use Cases

If this is your first time encountering A2UI, think of it as a **controlled way to generate UI**:

- **Developers prepare the menu**: Define reusable components, styles, interactions, and [Function](https://a2ui.org/glossary/#client-function) capabilities, then organize them into a Catalog the Agent can understand.
- **The Agent orders from the menu**: Choose components based on user intent, fill in data, and call Functions when results are needed.
- **ReactLynx cooks and serves**: Render the Agent's choices into a native interface while reusing the existing component system, themes, and interaction capabilities.

The key point is that A2UI does not let the model generate UI code freely. Instead, it lets the model compose UI dynamically within an authorized scope. Components, visual style, callable capabilities, and safety boundaries remain under business control.

After the interface is generated, user actions can follow two paths:

- **Agent-handled Actions**: Best for operations that should affect the next round of generation. The action is sent back to the Agent in a structured form, and the Agent continues reasoning and returns new protocol messages.
- **Client Actions**: Best for operations that can be completed directly within the page, such as navigation, analytics, or calling local capabilities, without waiting for the Agent to join the next turn.

A2UI is a good fit when you want to bring Agent-generated UI capabilities into a ReactLynx application in the following scenarios:

- **Dynamic UI composition**: Compose cards, buttons, lists, and other UI structures in real time based on user intent, instead of predefining every possible page state.
- **Progressive generation experience**: The server returns protocol messages incrementally, and the Renderer renders them as they arrive, so the interface keeps updating like a conversation.
- **Controlled generation boundaries**: The Catalog scopes the components and parameters the Agent can use, preventing the model from emitting unconstrained code or accessing capabilities outside its sandbox.
- **Flexible interaction loop**: Important actions can be sent back to the Agent to trigger the next round of generation, while local actions can still be handled directly by the page, balancing intelligent generation with business control.



---
url: /react/index.md
---

# <span class="hero-title"><span class="normal">Idiomatic </span><span class="brand-ani">React </span><span class="normal">on </span><span class="brand">Lynx</span></span>

> Develop Lynx with the familiar React

[Introduction](/react/introduction.html) | [Quick Start](/react/start/quick-start.html)



---
url: /react/introduction.md
---

# What is ReactLynx?

ReactLynx is the official React framework for Lynx. It allows you to develop Lynx native apps with a React mental model.

With ReactLynx, you can build your UI [using JSX and React components](https://react.dev/learn/describing-the-ui), just like you would on the web. ReactLynx turns your React code into calls to the [Lynx Engine](/guide/spec.md#engine) imperative API to render the native UI.

## Main Features

ReactLynx itself is an "idiomatic" React, but it also pioneered optimizations such as "dual-threaded React" and "JSX constant folding".

- **"Idiomatic" React**: ReactLynx is an implementation of React, under the hood it is based on [Preact](https://github.com/preactjs/preact), so it has basically the same API and behavior as React, and this consistency allows many ecosystem constructions to be reused.
- **[Dual-threaded in Mind](/react/thinking-in-reactlynx.md)**: ReactLynx follows the programming model of React, but by utilizing the **dual-threaded runtime** provided by Lynx, combined with its own programming paradigm (or rules) to achieve better performance and user experience.
  - **[Off-main-thread](/guide/spec.md#background-thread-aka-off-main-thread) Reconciliation**: ReactLynx puts some Reconciliation logic into the background thread to reduce the amount of calculation in the main thread and improve performance.
  - **[Lifecycle under dual-thread architecture](/react/lifecycle.md)**: Due to the dual-thread architecture of Lynx, the lifecycle of ReactLynx is slightly different from that of traditional React in terms of calling timing.
- **JSX constant folding**: ReactLynx folds JSX constants at compile time to reduce runtime calculations.

## For React Web Developers

### Change your `import`

Since it has the same API as [`react`](https://www.npmjs.com/package/react), you can directly replace `react` with `@lynx-js/react`, and continue to use the React API you are familiar with.

```diff
- import { useState } from 'react';
+ import { useState } from '@lynx-js/react';
```

For a full list of APIs ReactLynx implemented, please refer to the [`@lynx-js/react` API documentation](/api/react/index.md).

### Different component sets

Unlike elements such as `div` and `span` on the Web, Lynx provides a set of native component sets, such as `view`, `text`, `image`, etc ([full list](/api/elements/built-in/view.md)).
In ReactLynx, you can [combine](/guide/ui/elements-components.md) these elements to build your native UI.

```diff
- <div className="..." />
+ <view className="..." />
```

While the naming of native components is similar to React Native, ReactLynx do have some differences:

```diff
- import {View, Text, Image} from 'react-native';
- <View style={{...}} />
+ <view style={{...}} />
```

### Different event naming

Based on Lynx, ReactLynx uses a different set of event naming than the Web (go to [Events](/guide/interaction/event-handling.md) to learn more).

Event propagation is also differentFor commonly used Web methods such as `e.stopPropagation()` and `e.preventDefault()`, Lynx only supports [`e.stopPropagation()`](/api/lynx-api/event/event.md#stoppropagation) in [Main Thread Scripts](/react/main-thread-script.md). But Lynx's [Event Propagation Mechanism](/guide/interaction/event-handling/event-propagation.md) allows you to implement similar functions or effects as on the Web.

```diff
- <button onTouchStart={...} />
+ <view bindtouchstart={...} catchtouchstart={...}/>
```

### No `document` and `window`

Lynx does not yet provide `document` and `window` objects, so ReactLynx does not support these two objects either.

No "DOM"?Lynx Engine provides a set of Low Level Element APIs that allow [Framework Developers](/guide/spec.md#scripting-framework-developer) to create UI through JavaScript running in the [Main Thread](/guide/spec.md#main-thread-or-lynx-main-thread).
But this set of APIs is not open to all developers.
Lynx encourages developers to use declarative methods to build UI as much as possible,
rather than directly manipulating the DOM.
But Lynx also provides the ability to [Directly Manipulate Elements](/guide/interaction/event-handling/manipulating-element.react.md) and [Main Thread Scripts](/react/main-thread-script.md),
which are generally used to help developers maintain a near-native user experience when implementing some complex interactions.

This means that you cannot use any libraries that depend on `document` or `window`.

There are basically two ways for this difference:

- Most of the time, Lynx provides the feature with a different API. For example, you can use the APIs under the `lynx` object like [`lynx.reload`](/api/lynx-api/lynx/lynx-reload.md) to replace `window.location.reload()`.
- Occasionally, Lynx does not provide the feature. You can use Lynx's [NativeModules](/guide/use-native-modules.md) and [Custom Elements](/guide/custom-native-component.md) to extend Lynx's capabilities.

## Next Steps

### Further Learning ReactLynx

[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)[Rendering Process and Lifecycle

Understand the rendering process and lifecycle of ReactLynx

](/react/lifecycle)
### Learn Lynx Basics

If you haven't already, you should learn the basics of Lynx.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)


---
url: /react/lifecycle.md
---

# Rendering Process and Lifecycle

Due to Lynx's dual-thread architecture, ReactLynx's rendering process and component lifecycle differ from traditional React. This design aims to address mobile performance bottlenecks by properly distributing tasks between threads to ensure rendering performance and interaction fluidity.

## Rendering Process

![Lifecycle Flowchart](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/lifecycle-init-render-v3.png)

### First-Screen Rendering Optimization

To solve the slow first-screen loading problem of traditional web applications, Lynx adopts an innovative rendering strategy: when the application starts, the main thread completes the first-screen rendering to ensure the fastest possible initial display. Meanwhile, the background thread performs a parallel rendering and builds a node tree structure, then compares the tree structures from both threads to ensure consistency for handling subsequent updates and synchronizing to the main thread's node tree.

### Dual-Thread Architecture Design

After the first-screen rendering is complete, ReactLynx's dual-thread architecture enhances overall performance through clear responsibility division.
Component lifecycle management and user code execution will only occur in the background thread. After the node tree is updated in the background thread, the background thread will send a message to notify the main thread.
The main thread is responsible for updating the main thread's node tree structure according to instructions from the background thread, calculating layouts, rendering the UI, and executing user-written main thread scripts.

This precise division of labor allows each thread to focus on its core responsibilities, preventing complex user logic from blocking UI responses, ensuring the normal operation of component lifecycles and state management.

### Lifecycle Specifics

In ReactLynx, all lifecycle hooks execute asynchronously in the background thread, so they do not have synchronous blocking render characteristics. This means ReactLynx does not support `useLayoutEffect`. As a current alternative, you can use the element's [`main-thread:bindlayoutchange`](/api/elements/built-in/view.md#bindlayoutchange) event to obtain layout results and set corresponding properties.

Here's a simple example modified from [Measuring layout before the browser repaints the screen](https://react.dev/reference/react/useLayoutEffect#measuring-layout-before-the-browser-repaints-the-screen) to help you use this more easily:

**This is an example below: react-lifecycle**

**Entry:** `src/measuring-layout`
**Bundle:** `dist/measuring-layout.lynx.bundle` | Web: `dist/measuring-layout.web.bundle`

```tsx {4-18}
import type { PropsWithChildren } from "@lynx-js/react";
import type { Rect } from "./ButtonWithTooltip.jsx";
import TooltipContainer from "./TooltipContainer.jsx";

interface TooltipProps {
  targetRect: Rect | null;
}

export function Tooltip({ children, targetRect }: PropsWithChildren<TooltipProps>) {
  const handleLayoutChange = (e: any) => {
    "main thread";
    let tooltipX = 0;
    let tooltipY = 0;
    if (targetRect !== null) {
      tooltipX = targetRect.left;
      tooltipY = targetRect.top - e.detail.height;
      if (tooltipY < 0) {
        // It doesn't fit above, so place below.
        tooltipY = targetRect.bottom;
      }
    }

    e.currentTarget.setStyleProperty("transform", `translate3d(${tooltipX}px, ${tooltipY}px, 0)`);
  };

  return (
    <TooltipContainer handleLayoutChange={handleLayoutChange}>
      {children}
    </TooltipContainer>
  );
}

```



## Special Characteristics of `<list />` Child Components

The [`<list />`] element has on-demand loading and node reuse characteristics. When a [`<list />`] element is created, all its child component JS object instances are created together, but the corresponding actual elements ([UI]) are not immediately generated. Instead, they are created or reused only when the [`<list />`] is about to scroll to the corresponding position. Therefore, special attention is needed regarding the timing of child component lifecycle triggers.

### Timing of `useEffect` and `ref` Callbacks

The `useEffect` callback function will strictly execute after component creation and data updates; the `ref` attribute will also be assigned when the element is created or destroyed. Even if the component is not displayed on the screen (resulting in the actual [UI] node not being created or having entered the reuse pool), both the `useEffect` callback function and `ref` will still be triggered.

Specifically for [UI] elements inside a [`<list />`], the [`main-thread:ref`] attribute accurately reflects their state. When an element is about to scroll into view, the [`main-thread:ref`] callback function is triggered, and when the element scrolls out of view, the [`main-thread:ref`] cleanup function is triggered.

[`<list />`]: /api/elements/built-in/list.md

[UI]: /guide/spec.md#ui

[`main-thread:ref`]: /react/main-thread-script.md#usingmain-threadref-to-obtain-node-objects



---
url: /react/main-thread-script.md
---

# Main Thread Script

The Main Thread Script is a JS script that can be executed on the main thread. The most common use cases for the main thread script are smooth animations and gesture handling. It is primarily used to address the response delay issue in Lynx's multi-threaded architecture, aiming to achieve a near-native interactive experience.

## Event Response Delay in Lynx

Here is a simple animation: a small square that moves in sync with a `scroll-view`. In the small square component, we listen to the scroll event of the `scroll-view`, retrieve the current scroll position from the event parameters, and update its position immediately:

**This is an example below: main-thread**

**Entry:** `src/background-draggable`
**Bundle:** `dist/background-draggable.lynx.bundle` | Web: `dist/background-draggable.web.bundle`

```tsx
export function BackgroundDraggable({ size, posStyle }: { size: number; posStyle: { x: number; y: number } }) {
  return (
    <view
      style={{
        height: size + "px",
        width: size + "px",
        background: "lightskyblue",
        transform: `translate(${posStyle.x}px, ${posStyle.y}px)`,
      }}
    >
      <text>BGDraggable</text>
    </view>
  );
}

```



You can try scrolling the scroll-view on the left side of the example. The blue square on the right side of the page will follow the scroll-view's movement. However, you might notice that its movement has an unpredictable delay, especially on devices with lower performance. This delay will also increase as the complexity of the page increases.

This is because in Lynx's architecture, events are triggered on the main thread, while regular JS event handlers can only be executed on background threads. Therefore, if you use regular touch events to trigger animations, the event trigger -> event handling -> rendering process will involve multiple thread switches, resulting in untimely responses and animations lagging behind gestures.

![mts-threads-1.png](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/mts-threads-1.png)

The main thread script provides the capability to handle events synchronously on the main thread, ensuring synchronous event responses.

![mts-threads-2.png](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/mts-threads-2.png)

## Use Main Thread Functions to Eliminate Event Response Delay

### Implementing Animations with Main Thread Script

Synchronizing events using main thread script is very simple. Here we try to modify the previous example.

First, we inform the framework that we want to handle this event on the main thread by adding a main-thread namespace to the event attribute name:

```tsx
<view main-thread:bindscroll={onScroll} />
```

Since the onScroll function is now a main thread event handler, we also need to declare the event handler as a main thread function.
This is done by adding a `main thread` directive as the first line inside the function body:

```ts
let onScroll = (event) => {
  'main thread';
  // ...
};
```

After declaring it as a main thread function, we can no longer call it from the background thread.

Finally, we can now directly manipulate the element's properties on the main thread, so there's no need to use a state to change the position.
When using a main thread function as an event handler, the main thread function accepts an `event` parameter that contains basic information about the event.
The `event.target` and `event.currentTarget` parameters differ from those in regular event handlers;
they are [`MainThread.Element`] objects.
This object allows you to conveniently synchronize the retrieval and setting of node properties, such as using `setStyleProperty()` in the example.

```tsx
let onScroll = (event) => {
  'main thread';
  const detail = event.detail.scrollTop;
  const newPos = {
    x: 0,
    y: 500 - detail,
  };
  event.currentTarget.setStyleProperty(
    'transform',
    `translate(${newPos.x}px, ${newPos.y}px)`,
  );
};
```

That's all the changes needed. We will place the components before and after the modification in the same example for you to compare the effects. You may notice that the animation delay has disappeared!

**This is an example below: main-thread**

**Entry:** `src/main-thread-draggable`
**Bundle:** `dist/main-thread-draggable.lynx.bundle` | Web: `dist/main-thread-draggable.web.bundle`

```tsx
import type { RefObject } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

export function MainThreadDraggable(
  props: { size: number; "main-thread:ref"?: RefObject<MainThread.Element> },
) {
  return (
    <view
      main-thread:ref={props["main-thread:ref"]}
      style={{
        height: props.size + "px",
        width: props.size + "px",
        background: "lightskyblue",
        transform: `translate(0px, 500px)`,
      }}
    >
      <text>MTDraggable</text>
    </view>
  );
}

```



## Retrieving Data from the Background Thread

You may have noticed that designating a function as a main thread function isolates it from its surrounding context, making it feel like an "island."
Its runtime environment is different from other functions, meaning it cannot freely communicate with the background thread or other main-thread scripts.
However, we sometimes still need data from the background thread.

Fortunately, obtaining data from the background thread inside a main thread function is straightforward: just use it directly, as if it were a normal function.

```tsx
export default function App() {
  const red = 'red';

  function addBackgroundColor(event: MainThread.ITouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={addBackgroundColor}>
      <text>Hello World!</text>
      <text>Hello World!</text>
    </view>
  );
}
```

When the main thread function is defined, it automatically captures external variables from the background thread,
such as the red variable in the example above.
However, you cannot directly modify the values in the background thread.

The values captured by the main thread function are not updated in real time.
Instead, they are synchronized from the background thread to the main thread only after the component containing the main thread function re-renders.
Additionally, the synchronization requires that the captured values be serializable using `JSON.stringify()`.

To summarize the precautions:

- Main thread functions can and must only run on the main thread. Main thread functions can call each other.
- Captured variables need to be passed between threads using `JSON.stringify()`, so they must be serializable to JSON.
- Main thread functions do not support nested definitions.
- The constructor, getter, and setter of class components do not support being specified as main thread functions.
- You cannot modify variables captured from the external scope within a main thread function.

## Using `main-thread:ref` to Obtain Node Objects

In the example above, clicking on the text would change the color of both lines of text. If we want to change the color of only the first line of text when clicking on the text, it is not easy to achieve this with just `event.target` and `event.currentTarget`. In this case, you can use `main-thread:ref` to obtain a node object usable on the main thread ([`MainThread.Element`]).

Create a [`MainThreadRef`] using the [`useMainThreadRef()`] Hook, and then assign it to the target node's `main-thread:ref` attribute:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

export default function App() {
  const red = 'red';
  const textRef = useMainThreadRef<MainThread.Element>();

  function addBackgroundColor(event: MainThread.ITouchEvent) {
    'main thread';
    textRef.current?.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={addBackgroundColor}>
      <text main-thread:ref={textRef}>Hello World!</text>
      <text>Hello World!</text>
    </view>
  );
}
```

Note that the `current` property of [`MainThreadRef`] can only be accessed within a main thread function.

### Passing a Main Thread Function to `main-thread:ref`

Similar to a regular `ref`, you can also pass a main thread function to `main-thread:ref`:

```tsx
import { useMainThreadRef } from '@lynx-js/react';

export function App() {
  let eleRef = useMainThreadRef<MainThread.Element>();

  function handleTapMainThread() {
    'main thread';
    eleRef.current?.setStyleProperty('height', '30px');
  }

  return (
    <view main-thread:bindtap={handleTapMainThread}>
      <view
        main-thread:ref={(ele: MainThread.Element) => {
          'main thread';
          eleRef.current = ele;
        }}
      />
    </view>
  );
}
```

You can also return a cleanup function in the main thread function passed to `main-thread:ref`, just like when using a regular `ref`.

### Using `main-thread:ref` in Class Components

If you are using traditional class components, you cannot use the [`useMainThreadRef()`] Hook. Instead, you can directly create a [`MainThreadRef`] object:

```tsx
import { MainThreadRef } from '@lynx-js/react';

class App extends Component {
  eleRef = new MainThreadRef<MainThread.Element>();

  handleTapMainThread(event: MainThread.ITouchEvent) {
    'main thread';
    this.eleRef.current?.setStyleProperty('height', '30px');
  }

  render() {
    // ...
  }
}
```

## Maintaining State in Main Thread Functions

Main thread functions cannot modify captured variables. Therefore, if you need to maintain state between main thread functions, you should use [`MainThreadRef`].

For example, changing the background color of a node based on the number of clicks:

```jsx
import { useMainThreadRef } from '@lynx-js/react';

function App() {
  const countRef = useMainThreadRef(0);

  function handleTapMainThread(event: MainThread.ITouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', ++countRef.current % 2 ? 'blue' : 'green');
  }

  return (
    // ...
  );
}
```

## Cross-Thread Function Calls

The examples so far use `'main thread'` functions as event handlers. But what if you need to call a main thread function from the background thread, or vice versa? ReactLynx provides [`runOnMainThread()`] and [`runOnBackground()`] for bidirectional async communication.

**This is an example below: main-thread**

**Entry:** `src/cross-thread-calls`
**Bundle:** `dist/cross-thread-calls.lynx.bundle` | Web: `dist/cross-thread-calls.web.bundle`

```tsx
import { runOnBackground, runOnMainThread, useEffect, useMainThreadRef, useState } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";

const COLORS = ["#4FC3F7", "#81C784", "#FFB74D", "#E57373", "#BA68C8"];

export function App() {
  // --- Background Thread state ---
  const [count, setCount] = useState(0);

  function incrementCount() {
    setCount((prev) => prev + 1);
  }

  // --- Main Thread function ---
  const boxRef = useMainThreadRef<MainThread.Element>(null);

  const applyColor = (color: string) => {
    "main thread";
    boxRef.current?.setStyleProperty("background-color", color);
  };

  // --- Cross-thread wiring ---
  // When count changes on BG thread, pick the next color and
  // call the MT function to apply it.
  useEffect(() => {
    const nextColor = COLORS[count % COLORS.length]!;
    runOnMainThread(applyColor)(nextColor);
  }, [count]);

  // Main Thread tap handler → calls BG function
  const onTap = () => {
    "main thread";
    runOnBackground(incrementCount)();
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        backgroundColor: "white",
      }}
    >
      <view
        main-thread:ref={boxRef}
        main-thread:bindtap={onTap}
        style={{
          width: "200px",
          height: "200px",
          backgroundColor: COLORS[0],
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          borderRadius: "16px",
        }}
      >
        <text style={{ fontSize: "16px", color: "white", fontWeight: "bold" }}>
          Tap count: {count}
        </text>
      </view>
    </view>
  );
}

```



In this example, tapping the box triggers a round trip:

1. **Main Thread** `onTap` fires, calls `runOnBackground(incrementCount)()` to update state
2. **Background Thread** `useEffect` on `count` fires, calls `runOnMainThread(applyColor)(nextColor)` to change the box color

### Asynchronously Invoking Main Thread Functions from the Background Thread

Use [`runOnMainThread()`] in the background thread to asynchronously execute a main thread function on the main thread:

```jsx
import { runOnMainThread, useMainThreadRef } from '@lynx-js/react';

function App() {
  const countRef = useMainThreadRef(0);

  const addCount = (value) => {
    'main thread';
    countRef.current += value;
    return countRef.current;
  };

  const increaseMainThreadCount = async () => {
    const result = await runOnMainThread(addCount)(1);
    console.log(result);
  };
}
```

### Asynchronously Invoking Non-Main Thread Functions from the Main Thread

Use [`runOnBackground()`] on the main thread to asynchronously execute a regular function on the background thread.

```jsx
import { runOnBackground, useState } from '@lynx-js/react';

function App() {
  const [current, setCurrent] = useState(0);

  const syncIndexToBackground = runOnBackground((nextIndex) => {
    setCurrent(nextIndex);
    return `Current index updated to ${nextIndex}`;
  });

  const onScrollMainThread = async (event) => {
    'main thread';
    const index = Math.round(event.detail.scrollTop / 300);
    const result = await syncIndexToBackground(index);
    console.log(result);
  };

  return (
    <view>
      <scroll-view main-thread:bindscroll={onScrollMainThread} />
      <text>Current index: {current}</text>
    </view>
  );
}
```

## Cross-thread Shared Modules

By default, main thread functions cannot directly call plain functions that do not have the `'main thread'` directive. This makes code reuse difficult.
To address this limitation, ReactLynx introduces the `shared-module` mechanism, allowing you to explicitly declare certain modules as shareable between the main thread and the background thread.

Add `with { runtime: 'shared' }` after the `import` statement, and the exported variables (including functions, classes, objects, etc.) in that module can be directly called in main thread functions.

```javascript
import { func } from './utils.js' with { runtime: 'shared' }; // `func` is a plain function

function mainThreadFunction() {
  'main thread';
  func(); // Allows calling plain functions in a main thread function
}
```

> \[!NOTE]
> Functions in modules imported with `with { runtime: 'shared' }` can be called by main thread functions, but they are not automatically treated as main thread functions. If they use main-thread-specific capabilities like `MainThreadRef`, they must still be manually marked with `'main thread'`.

**This is an example below: main-thread**

**Entry:** `src/shared-module`
**Bundle:** `dist/shared-module.lynx.bundle` | Web: `dist/shared-module.web.bundle`

```tsx
import { runOnBackground, useMainThreadRef, useMemo, useState } from "@lynx-js/react";
import type { MainThread } from "@lynx-js/types";
import { getColorCount, getNextColor } from "./color-utils.js" with { runtime: "shared" };

export function App() {
  // --- Background Thread state ---
  const [count, setCount] = useState(0);
  const currentColor = useMemo(() => getNextColor(count), [count]);

  function incrementCount() {
    setCount((prev) => prev + 1);
  }

  // --- Main Thread function ---
  const boxRef = useMainThreadRef<MainThread.Element & { __colorIdx?: number }>(null);

  const onTap = () => {
    "main thread";
    // Use shared function directly on the Main Thread to get color
    const idx = boxRef.current?.__colorIdx ?? 0;
    const nextIdx = idx + 1;
    const color = getNextColor(nextIdx);

    boxRef.current?.setStyleProperty("background-color", color);
    if (boxRef.current) boxRef.current.__colorIdx = nextIdx;

    // Also update BG state so the text reflects the change
    runOnBackground(incrementCount)();
  };

  return (
    <view
      style={{
        width: "100%",
        height: "100%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        backgroundColor: "white",
      }}
    >
      <view
        main-thread:ref={boxRef}
        main-thread:bindtap={onTap}
        style={{
          width: "200px",
          height: "200px",
          backgroundColor: currentColor,
          display: "flex",
          flexDirection: "column",
          alignItems: "center",
          justifyContent: "center",
          borderRadius: "16px",
        }}
      >
        <text style={{ fontSize: "16px", color: "white", fontWeight: "bold" }}>
          Tap to cycle
        </text>
        <text style={{ fontSize: "14px", color: "white", marginTop: "8px" }}>
          Color {(count % getColorCount()) + 1}/{getColorCount()}
        </text>
      </view>
    </view>
  );
}

```



### Referencing Third-Party Libraries

Usually, third-party libraries (e.g., `motion-dom`) contain plain JavaScript functions. If called directly in a main thread function, they will report an error due to the missing `'main thread'` directive.

We can use the Shared Runtime mechanism to import them as shared modules.

```javascript
// Import and use directly
import { animate } from 'motion-dom' with { runtime: 'shared' };

function onScroll() {
  'main thread';
  // Can be called directly in a main thread function
  animate(element, { opacity: 0 });
}
```

To facilitate reuse or avoid the [limitations](#limitations) of Shared Runtime (e.g., losing the shared characteristic after assignment), we recommend **wrapping** it in a main thread function:

```ts
// src/utils/motion.ts
// 1. Import the original function as shared
import { animate as _animate } from 'motion-dom' with { runtime: 'shared' };

// 2. Export a new main thread function for encapsulation
export function animate(...args) {
  'main thread';
  return _animate(...args);
}
```

In this way, `animate` becomes a standard main thread function that can be freely used in any main thread function, no longer restricted by static analysis.

```ts
// src/App.tsx
import { animate } from './utils/motion';

function onTap() {
  'main thread';
  // This is a standard main thread function, which can be assigned or passed freely
  const myAnimate = animate;
  myAnimate(element, { x: 100 });
}
```

### Limitations

Only identifiers identifiers directly imported via `import` are recognized as "shared". Assigning to a new variable will cause it to lose the shared characteristic.

```javascript
import { func } from './utils.js' with { runtime: 'shared' };
const anotherFunc = func;

function mainThreadFunction() {
  'main thread';
  anotherFunc(); // ❌ Cannot be analyzed at compile time, call fails
}
```

### State Isolation

**Variables and states in a Shared Module are completely isolated between the two threads, each possessing independent instances.**

This means that if you modify a variable in a shared module on the main thread, the background thread cannot perceive it, and vice versa. Shared Module only solves the "code sharing" problem, not the "state sharing" problem.

[`MainThread.Element`]: /api/lynx-api/main-thread/main-thread-element.md

[`MainThreadRef`]: /api/react/Class.MainThreadRef.md

[`useMainThreadRef()`]: /api/react/Function.useMainThreadRef.md

[`runOnMainThread()`]: /api/react/Function.runOnMainThread.md

[`runOnBackground()`]: /api/react/Function.runOnBackground.md



---
url: /react/payment-details.md
---

# Tutorial: Payment Details

After completing the [Gallery](/learn/gallery.md) tutorial, you should have mastered the basics of Lynx. Now, let's learn some more advanced features through a payment details page, including:

- Building an interactive scrolling list
- How to create 3D interactive animations
- How to pass data between different components

## What are we building?

Let's first take a look at the final effect of this application. To experience it, please download and install [Lynx Explorer App](/guide/start/quick-start.md#ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator) first, then scan the QR code below.

**This is an example below: bankcards**

**Entry:** `src/final`
**Bundle:** `dist/final.lynx.bundle` | Web: `dist/final.web.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import Amount from "./Components/Amount.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view className="page">
      <Amount amount="1314" />
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



## Let's Get Started

Let's look at the composition of this page. If you want to build such a page, you can break it down into these three components and implement them step by step:

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_cards.gif)1. Card Details
   - The card can perform flip animation
   - Here we'll learn how to use CSS animations to create smooth flip effects

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_bankcards.gif)2. Card List, wrapped in a [scroll-view](/api/elements/built-in/scroll-view.md) element
   - Can scroll up and down to browse all cards
   - When clicking a card, the top card details will update with corresponding card information
   - Here we'll learn how to build an interactive scrolling list and how to pass data between components

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg)![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_pay.jpg)3. The top amount display and bottom buttons, these components are relatively simple, we'll implement them using the [view](/api/elements/built-in/view.md) element.

Let's focus on three technical points: building an interactive scrolling list, implementing 3D flip animation effects, and passing data between components.

### Building an Interactive Card List

First, let's create a bank card list. This list needs to display basic information for each card, including:

- Bank type (like Bac, Boc, etc.)
- Card number (showing first and last four digits)
- Cardholder name
- Whether it's a primary card

Let's organize this information into a data structure:

```tsx title="BankCardScrollView.tsx"
export interface BankCard {
  type: string; // Bank type (like Bac, Boc, etc.)
  number: string; // Card number
  name: string; // Cardholder name
}
```

Then, prepare some card data for display:

```tsx title="BankCardScrollView.tsx"
const cards = [
  { type: "bac", number: "4558 **** **** 6767", name: "Alex Quentin" },
  { type: "boc", number: "6222 **** **** 8058", name: "Alex Quentin" },
  ...
];
```

Next, let's use the `<scroll-view>` element to create a vertically scrollable list to display all card information:

```tsx title="BankCardScrollView.tsx" {6}
export default function BankCardScrollView() {
  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

To let users know which card they've selected, we need to add an icon to indicate selection:

```scss title="BankCardScrollView.tsx"
<image className="check-icon" src={checkIcon} />
```

Then, we need to define a `selectedCard` state to track the currently selected card:

```tsx title="BankCardScrollView.tsx"
const [selectedCard, setSelectedCard] = useState(cards[0]);
```

After that, we need to add a `handleCardSelect` function in the `<BankCardScrollView>` component to handle card selection events:

```tsx title="BankCardScrollView.tsx"
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
};
```

When a user clicks a card, it will trigger the `handleCardSelect` function, which will update the `selectedCard` state:

```tsx title="BankCardScrollView.tsx" {3}
<view
  className={`card ${selectedCard === card ? 'selected' : ''}`}
  bindtap={() => handleCardSelect(card)}
>
  ...
</view>
```

Let's combine the above logic. When a user selects a card, it will show a small check mark on the right to indicate the current selection:

```tsx title="BankCardScrollView.tsx {5,17}"
export default function BankCardScrollView() {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              <view className="card-info">
                <image className="card-icon" src={getUrlByType(card.type)} />
                <view className="card-details">
                  <text className="card-name">
                    {card.type.charAt(0).toUpperCase() + card.type.slice(1)}
                  </text>
                </view>
              </view>
              {selectedCard === card && (
                <image className="check-icon" src={checkIcon} />
              )}
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

Now, we've completed building this interactive card list. Let's see how it works!

**This is an example below: bankcards**

**Entry:** `src/step_1`
**Bundle:** `dist/step_1.lynx.bundle` | Web: `dist/step_1.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from "@lynx-js/react";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";

import "./index.scss";

function BankCards() {
  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <BankCardScrollView />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



### 3D Flip effects

Now let's recreate this interesting 3D flip effect. First, we need to understand the key steps to implement this effect — CSS animation.

:::info CSS Animation Collections in Lynx
Lynx supports various CSS animation collections. To explore more animation techniques, check out [CSS Animation](/api/css/properties/animation.md).
:::

To achieve this flip effect, we need two key steps:

First, let's create a `<Card/>` component

1. Define the flip animation:
   - Use [keyframes](/api/css/at-rule/keyframes.md) to describe the process of flipping the card from front to back (and vice versa), which includes rotation keyframes.
   - The [transform](/api/css/properties/transform.md) property defines the rotation angle of the element.

```scss title="Cards.scss" {11,15,21,25}
.front {
  animation: backToFront 0.5s both;
}

.back {
  animation: frontToBack 0.5s both;
}

@keyframes frontToBack {
  0% {
    transform: rotateY(0deg) translateZ(1);
  }

  100% {
    transform: rotateY(180deg) translateZ(0);
  }
}

@keyframes backToFront {
  0% {
    transform: rotateY(-180deg) translateZ(0);
  }

  100% {
    transform: rotateY(0deg) translateZ(1);
  }
}
```

2. Make the card responsive to clicks:
   - Trigger the flip animation when the bottom button is clicked
   - Control whether the card shows front or back by switching className

```tsx title="Cards.tsx" {5,10}
export default function Card({ isFront, isFirstRender }: CardProps) {
  return (
    <view className="card-content">
      <view className={`card-back ${isFront ? 'back' : 'front'}`}>...</view>
      <view
        className={`card-front ${!isFirstRender ? (isFront ? 'front' : 'back') : ''}`}
      >
        ...
      </view>
    </view>
  );
}
```

This way, we've created a practical and fun card flip effect! Every time users click the bottom button, they'll see a smooth flip animation, making the entire interaction experience more lively and engaging.

**This is an example below: bankcards**

**Entry:** `src/step_2`
**Bundle:** `dist/step_2.lynx.bundle` | Web: `dist/step_2.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import BottomNode from "../final/Components/BottomNode.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import Card from "./Components/Card.jsx";

import "./index.scss";

function BankCards() {
  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <Card
        isFirstRender={isFirstRender}
        isFront={isFront}
      />
      <BankCardScrollView />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



### Component Data Interaction

You might have noticed an issue: when clicking a card in the list, the card details don't update with the new card number. We need to solve this synchronization problem.

In this application, we have two main components:

- Card List: the `<BankCardScrollView/>` component that displays all available bank cards
- Card Details: the `<Card/>` component that shows detailed information of the currently selected card

When a user clicks a card in the list, the card details at the top need to synchronously update to display that card's information. To achieve this functionality, we need to enable data transmission between these two components.

First, let's define a callback function to notify other components which card the user has selected:

```tsx title="BankCardScrollView.tsx" {9}
export interface BankCardScrollViewProps {
  onCardSelect?: (card: BankCard) => void;
}
```

Then, we call this callback function in our previously defined `handleCardSelect` function:

```tsx title="BankCardScrollView.tsx" {3}
const handleCardSelect = (card: BankCard) => {
  setSelectedCard(card);
  onCardSelect?.(card);
};
```

Next, we add `onCardSelect` as a property in the `<BankCardScrollView>` component:

```tsx title="BankCardScrollView.tsx" {2}
export default function BankCardScrollView({
  onCardSelect,
}: BankCardScrollViewProps) {
  const [selectedCard, setSelectedCard] = useState(cards[0]);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    onCardSelect?.(card);
  };

  return (
    <view className="payment-wrapper">
      <text className="title">Payment method</text>
      <view className="payment-container">
        <scroll-view scroll-y className="payment-sv">
          {cards.map((card, idx) => (
            <view
              key={idx}
              className="card"
              bindtap={() => handleCardSelect(card)}
            >
              ...
            </view>
          ))}
        </scroll-view>
      </view>
    </view>
  );
}
```

After handling the `<BankCardScrollView>` component, we need to handle the `<Card>` component to update the card number when switching cards in the list.

It receives a `selectedCard` property to display the details of the currently selected card, showing the last four digits of the card number.

```tsx title="Card.tsx" {4}
interface CardProps {
  isFront: boolean;
  isFirstRender: boolean;
  selectedCard: BankCard;
}
```

Let's define a utility function to extract the first and last four digits of the card number.

```tsx title="Card.tsx"
const getCardNumberParts = (number: string) => {
  const parts = number?.split(' ') || [];
  return {
    firstFour: parts[0] || '4558',
    lastFour: parts[3] || '6767',
  };
};
```

Then, we'll use this utility function to display the first and last four digits from the selectedCard number.

```tsx title="Card.tsx" {17,19}
export default function Card({
  selectedCard,
  isFront,
  isFirstRender,
}: CardProps) {
  const { firstFour, lastFour } = getCardNumberParts(selectedCard.number);

  return (
    <view className="card-content">
      <view
        className={`card-back ${!isFirstRender ? (isFront ? 'back' : 'front') : ''}`}
      >
        ...
      </view>

      <view
        className={`card-front ${!isFirstRender ? (isFront ? 'front' : 'back') : ''}`}
      >
        <view className="card-number">
          <text className="first-digits">{firstFour}</text>
          <text className="middle-digits">**** ****</text>
          <text className="last-digits">{lastFour}</text>
        </view>
        <view className="card-info">
          <text>{selectedCard?.name || 'Card holder'}</text>
        </view>
      </view>
    </view>
  );
}
```

Finally, let's combine these two components in the parent component:

1. Use `selectedCard` state to store the currently selected card
2. Update this state when the `onCardSelect` of `<BankCardScrollView>` notifies that a new card has been selected
3. Pass this state to `<Card>` to display the selected card's information

```tsx title="index.tsx" {12,26}
function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: 'visa',
    number: '4558 **** **** 6767',
    name: 'Alex Quentin',
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view class="page">
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}
```

This way, we've established an efficient collaboration mechanism:

1. User selects a card from the card list
2. Card list immediately notifies the parent component
3. Parent component updates the state and notifies the card details component
4. Card details component immediately updates its display

Let's see this seamless coordination in action:

**This is an example below: bankcards**

**Entry:** `src/step_3`
**Bundle:** `dist/step_3.lynx.bundle` | Web: `dist/step_3.web.bundle`

```tsx
// Copyright 2025 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  const handleBack = () => {
    // handle back logic
  };

  return (
    <view className="page">
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



We'll add the top amount display, and we're done!

![card](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg)
**This is an example below: bankcards**

**Entry:** `src/final`
**Bundle:** `dist/final.lynx.bundle` | Web: `dist/final.web.bundle`

```tsx
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from "@lynx-js/react";
import Amount from "./Components/Amount.jsx";
import BankCardScrollView from "./Components/BankCardScrollView.jsx";
import type { BankCard } from "./Components/BankCardScrollView.jsx";
import BottomNode from "./Components/BottomNode.jsx";
import Card from "./Components/Card.jsx";
import "./index.scss";

function BankCards() {
  const [selectedCard, setSelectedCard] = useState<BankCard>({
    type: "visa",
    number: "4558 **** **** 6767",
    name: "Alex Quentin",
  });

  const [isFront, setIsFront] = useState(true);
  const [isFirstRender, setIsFirstRender] = useState(true);

  const handleCardSelect = (card: BankCard) => {
    setSelectedCard(card);
    setIsFront(true);
  };

  const handlePayNow = () => {
    if (isFirstRender) {
      setIsFirstRender(false);
    }
    setIsFront(!isFront);
  };

  return (
    <view className="page">
      <Amount amount="1314" />
      <Card
        selectedCard={selectedCard}
        isFront={isFront}
        isFirstRender={isFirstRender}
      />
      <BankCardScrollView onCardSelect={handleCardSelect} />
      <BottomNode onPayNow={handlePayNow} />
    </view>
  );
}

export default BankCards;
root.render(<BankCards />);

```



## Summary

Through implementing this payment details page, you've mastered these core technical points:

- Building interactive lists
- Developing complex CSS animation effects
- Implementing data transmission between components

Now you're ready to develop more complex applications with Lynx.



---
url: /react/performance/profiling.md
---

# Performance Profiling

ReactLynx provides built-in profiling support to help you analyze and optimize the performance of your applications. This feature allows you to trace component rendering, diffing, and state updates in production builds.

## Overview

When profiling is enabled, ReactLynx automatically instruments the following operations:

| Trace Name                         | Description                                                     |
| ---------------------------------- | --------------------------------------------------------------- |
| `ReactLynx::render::ComponentName` | Time spent in your component's render function                  |
| `ReactLynx::diff::ComponentName`   | Time spent in ReactLynx's diffing algorithm for the component   |
| `ReactLynx::diffFinishNoPatch`     | Instant event marking when a component's diff produced no patch |
| `ReactLynx::commit`                | Time spent committing changes to the native layer               |
| `ReactLynx::patch`                 | Time spent applying patches on the main thread                  |
| `ReactLynx::setState`              | Instant event marking when `setState` was called                |

## Enabling Profiling

Profiling is automatically enabled when the Lynx engine's profile recording is active. ReactLynx checks `lynx.performance.isProfileRecording()` at runtime to determine whether to enable profiling instrumentation.

To start profiling, you need to enable profile recording in the Lynx engine. For detailed instructions on how to record and view traces, see [Recording Traces](/guide/devtool/trace/record-trace.md).

:::info Requirements

This feature requires Lynx 3.0 or later, which provides the necessary profiling APIs:

- `lynx.performance.profileStart()`
- `lynx.performance.profileEnd()`
- `lynx.performance.profileMark()`
- `lynx.performance.profileFlowId()`
- `lynx.performance.isProfileRecording()`

:::

## Understanding Trace Events

### Render Traces

The `ReactLynx::render::ComponentName` trace measures the time spent executing your component's render function. This helps identify components with expensive render logic.

```tsx
function ExpensiveComponent({ data }) {
  // This render function's execution time will be traced
  const processed = data.map((item) => complexCalculation(item));
  return (
    <view>
      {processed.map((item) => (
        <text>{item}</text>
      ))}
    </view>
  );
}
```

### Diff Traces

The `ReactLynx::diff::ComponentName` trace measures the time ReactLynx spends comparing the previous and new virtual DOM for a component. High diff times may indicate:

- Large component trees
- Frequent unnecessary re-renders
- Complex nested structures

### diffFinishNoPatch Traces

The `ReactLynx::diffFinishNoPatch` is an instant event that fires when a component finishes diffing but produces no patch. This event includes a `componentName` argument indicating which component's diff produced no changes.

This trace is useful for identifying unnecessary re-renders. If you see many `diffFinishNoPatch` events, it means components are frequently re-rendering but not actually producing any UI changes. This is an optimization signal that you may need to:

- Use `React.memo` or `useMemo` to prevent unnecessary re-renders
- Check if parent components are passing unstable props (e.g., creating new objects or functions on every render)
- Optimize state management to avoid unnecessary state updates

### setState Traces

The `ReactLynx::setState` trace is an instant event that marks when `setState` is called. It includes additional metadata:

- `current state keys`: Keys present in the current state
- `next state keys`: Keys present in the next state
- `changed (shallow diff) state keys`: Keys whose values changed

This helps you understand what triggered updates and which state properties changed.

### Flow ID Tracking

ReactLynx uses flow IDs to connect related trace events. When you call `setState`, a flow ID is generated and attached to all subsequent operations (diff, commit, patch) triggered by that state update. This allows you to trace the complete flow of an update through the system.

![React Lynx Profile Flow ID](/static/image/react_lynx_profile_flow_id.3c5489dfb6.png)


## Improving Component Name Readability

In production builds, component names may be minified and become unreadable (e.g., `ReactLynx::render::t` instead of `ReactLynx::render::MyComponent`).

To preserve readable component names, set the `displayName` property on your components:

If you encounter side effect issues during build
Build tools may treat setting `displayName` as a side effect, which can affect Tree-Shaking optimization. In this case, you can use the following pattern to avoid side effects:
```ts
function withDisplayName<T extends React.ComponentType<any>>(
  Component: T,
  name: string,
): T {
  Component.displayName = name;
  return Component;
}
```
Using this helper function:
```tsx
// Function component
function MyComponent() {
  return <view />;
}
export default /* @__PURE__ */ withDisplayName(MyComponent, 'MyComponent');

// Class component
class MyClassComponent extends Component {
  render() {
    return <view />;
  }
}
export default /* @__PURE__ */ withDisplayName(
  MyClassComponent,
  'MyClassComponent',
);
```

```tsx
// Function component
function MyComponent() {
  return <view />;
}
MyComponent.displayName = 'MyComponent';

// Class component
class MyClassComponent extends Component {
  static displayName = 'MyClassComponent';

  render() {
    return <view />;
  }
}
```

## Best Practices

1. **Profile in realistic conditions**: Test with production builds and realistic data to get accurate measurements.

2. **Focus on hot paths**: Pay attention to components that render frequently or handle large amounts of data.

3. **Use displayName**: Always set `displayName` for components you want to profile, especially in production builds.

4. **Analyze flow IDs**: Use flow IDs to understand the complete lifecycle of state updates, from `setState` to final patch.

5. **Look for patterns**: Identify components with consistently high render or diff times as optimization candidates.

## Related

- [Rendering Process and Lifecycle](/react/lifecycle.md)
- [Main Thread Script](/react/main-thread-script.md)



---
url: /react/react-compiler.md
---

# React Compiler Experimental
[React Compiler](https://react.dev/learn/react-compiler) can optimize components at compile time, eliminating the need to manually use `useMemo`, `useCallback`, and `memo`. You can use React Compiler in ReactLynx to enhance your application's performance.

## How to Use

Follow these steps to enable React Compiler for ReactLynx in Rspeedy:

1. Install the runtime dependency for React Compiler:


```sh [npm]
npm install react-compiler-runtime@rc
```

```sh [yarn]
yarn add react-compiler-runtime@rc
```

```sh [pnpm]
pnpm add react-compiler-runtime@rc
```

```sh [bun]
bun add react-compiler-runtime@rc
```

```sh [deno]
deno add npm:react-compiler-runtime@rc
```

2. Install the build-time dependencies for React Compiler:


```sh [npm]
npm install -D @rsbuild/plugin-babel babel-plugin-react-compiler@rc
```

```sh [yarn]
yarn add -D @rsbuild/plugin-babel babel-plugin-react-compiler@rc
```

```sh [pnpm]
pnpm add -D @rsbuild/plugin-babel babel-plugin-react-compiler@rc
```

```sh [bun]
bun add -D @rsbuild/plugin-babel babel-plugin-react-compiler@rc
```

```sh [deno]
deno add -D npm:@rsbuild/plugin-babel npm:babel-plugin-react-compiler@rc
```

3. Enable React Compiler in the lynx.config.js configuration:

:::warning

Currently ReactLynx only supports target to version 17.

:::

```js title="lynx.config.js"
import { defineConfig } from '@lynx-js/rspeedy';
import { pluginBabel } from '@rsbuild/plugin-babel';

export default defineConfig({
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
      babelLoaderOptions(opts) {
        opts.plugins?.unshift([
          'babel-plugin-react-compiler',
          // See https://react.dev/reference/react-compiler/configuration for config
          {
            // ReactLynx only supports target to version 17
            target: '17',
          },
        ]);
      },
    }),
  ],
});
```

4. To maximize the benefits of React Compiler, it is recommended to configure the ESLint rule `react-hooks/react-compiler` to detect code that cannot be optimized. Please refer to [React Compiler - ESLint Integration](https://react.dev/learn/react-compiler/installation#eslint-integration) for configuration details.

## Performance Considerations

The React Compiler automatically analyzes your components and injects memoization logic, reducing the need for manual optimizations like `useMemo`, `useCallback`, or `React.memo`. This simplifies your codebase and can deliver significant performance gains during subsequent re-renders, particularly in update-heavy interfaces.

Because the compiler introduces additional runtime logic, it may slightly affect [IFR](/guide/interaction/ifr.md) performance or initial background-thread rendering. We recommend enabling React Compiler in cases where initial IFR performance is less critical, or where re-render efficiency and developer experience are the higher priorities.

We’re actively evaluating its impact in ReactLynx and welcome your experiments and feedback to help guide future improvements.



---
url: /react/reactlynx-testing-library.md
---

# ReactLynx Testing Library

The [`@lynx-js/react/testing-library`](/api/reactlynx-testing-library/index.md) package provides the same set of APIs (e.g. [`render`](/api/reactlynx-testing-library/Function.render.md), [`fireEvent`](/api/reactlynx-testing-library/Function.fireEvent.md), [`screen`](/api/reactlynx-testing-library/Variable.screen.md), etc.) for testing the rendering result of ReactLynx, just like the popular [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/), with the underlying dual-threaded architecture abstracted away by the [@lynx-js/testing-environment](/api/lynx-testing-environment/index.md).

## Setup

### From create-rspeedy

If you create a new project using [`create-rspeedy`](https://www.npmjs.com/package/create-rspeedy), you can choose whether to use ReactLynx Testing Library (default checked) when creating the project. The created project is already configured with ReactLynx Testing Library.

### Adding to an existing project

ReactLynx Testing Library is integrated in the `testing-library` subdirectory of the `@lynx-js/react` package and can be used directly. Currently we support the testing frameworks Rstest and Vitest.

#### Rstest

Setup [Rstest](https://rstest.rs/) with `@lynx-js/react/testing-library/rstest-config`.

Recommended for library projects:

```ts
import { defineConfig } from '@rstest/core';
import { withDefaultConfig } from '@lynx-js/react/testing-library/rstest-config';

export default defineConfig({
  extends: withDefaultConfig(),
});
```

Use `withLynxConfig` when you want to reuse your app's `lynx.config.ts`:

```ts title=rstest.config.ts
import { defineConfig } from '@rstest/core';
import { withLynxConfig } from '@lynx-js/react/testing-library/rstest-config';

export default defineConfig({
  extends: withLynxConfig(),
});
```

Difference between `withLynxConfig` and `withDefaultConfig`:

- `withLynxConfig`: app-oriented. Loads your `lynx.config.ts` and converts it to rstest config, so rspeedy/lynx settings are reused in tests.
- `withDefaultConfig`: library-oriented. Only applies testing-library defaults (`jsdom`, setup files, globals) and lets you provide the rest via `modifyRstestConfig`.

Then you can start writing tests and run them with rstest!

#### Vitest

Setup [vitest](https://vitest.dev/):

```ts title=vitest.config.ts
import { defineConfig } from 'vitest/config';
import { vitestTestingLibraryPlugin } from '@lynx-js/react/testing-library/plugins';

export default defineConfig({
  plugins: [vitestTestingLibraryPlugin()],
  test: {
    // ...
  },
});
```

Then you can start writing tests and run them with vitest!

## Examples

:::info
The following code examples are all implemented in Vitest, but you can also use them in Rstest. Replace `vitest` with `@rstest/core` and `vi` with `rstest` in the code examples to use them under Rstest.
:::

### Quick Start

Same as in React Testing Library, it is recommended to divide test cases into three parts: [Arrange](https://testing-library.com/docs/react-testing-library/example-intro#arrange), [Act](https://testing-library.com/docs/react-testing-library/example-intro#act), and [Assert](https://testing-library.com/docs/react-testing-library/example-intro#assert). The Arrange part is used to prepare test data, the Act part is used to perform test operations, and the Assert part is used to assert test results. Here is a simple example:

```tsx
import '@testing-library/jest-dom';
import { expect, it, vi } from 'vitest';
import { render, fireEvent, screen } from '@lynx-js/react/testing-library';

it('basic', async function () {
  const Button = ({ children, onClick }) => {
    return <view bindtap={onClick}>{children}</view>;
  };
  const onClick = vi.fn(() => {});

  // ARRANGE
  const { container } = render(
    <Button onClick={onClick}>
      <text data-testid="text">Click me</text>
    </Button>,
  );

  expect(onClick).not.toHaveBeenCalled();

  // ACT
  fireEvent.tap(container.firstChild);

  // ASSERT
  expect(onClick).toBeCalledTimes(1);
  expect(screen.getByTestId('text')).toHaveTextContent('Click me');
});
```

In this example, you may have noticed that we used the `toHaveTextContent` method from third-party library [`@testing-library/jest-dom`](https://www.npmjs.com/package/@testing-library/jest-dom) to assert the text content of an element. In React Testing Library, you can use `@testing-library/jest-dom` because the test framework uses [JSDOM](https://github.com/jsdom/jsdom) to create DOM elements; in ReactLynx Testing Library, we also use JSDOM to implement the behavior of [Element PAPI](/api/engine/element-api.md), so it is compatible with DOM API.

### Basic rendering

The [`render`](/api/reactlynx-testing-library/Function.render.md) method is used to render a ReactLynx component and returns a [`RenderResult`](/api/reactlynx-testing-library/TypeAlias.RenderResult.md) object. The `container` field is a [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) containing the rendering result.

```jsx
import '@testing-library/jest-dom';
import { expect, it } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

it('basic render', () => {
  const WrapperComponent = ({ children }) => (
    <view data-testid="wrapper">{children}</view>
  );
  const Comp = () => {
    return <view data-testid="inner" style="background-color: yellow;" />;
  };
  const { container, getByTestId } = render(<Comp />, {
    wrapper: WrapperComponent,
  });
  expect(getByTestId('wrapper')).toBeInTheDocument();
  expect(container.firstChild).toMatchInlineSnapshot(`
    <view
      data-testid="wrapper"
    >
      <view
        data-testid="inner"
        style="background-color: yellow;"
      />
    </view>
  `);
});
```

### Firing events

When firing an event with [`fireEvent`](/api/reactlynx-testing-library/Function.fireEvent.md), you need to explicitly specify the type of event. For example, `new Event('catchEvent:tap')` (`eventType:eventName`) means triggering a `tap` event of type `catch`. Please refer to [Event Handler Properties](/guide/interaction/event-handling/event-propagation.md#event-handler-property). The possible values of `eventType` and usage scenarios are as follows:

| Event Type      | `eventType`     | Event Binding Example | Event Triggering Example         |
| --------------- | --------------- | --------------------- | -------------------------------- |
| `bind`          | `bindEvent`     | `bindtap`             | `new Event('bindEvent:tap')`     |
| `catch`         | `catchEvent`    | `catchtap`            | `new Event('catchEvent:tap')`    |
| `capture-bind`  | `capture-bind`  | `capture-bindtap`     | `new Event('capture-bind:tap')`  |
| `capture-catch` | `capture-catch` | `capture-catchtap`    | `new Event('capture-catch:tap')` |

You can directly construct an `Event` object yourself, or you can directly pass in the event type and initialization parameters to let the Testing Library automatically construct an `Event` object.

In the `render` process, the event handler will be mounted to the [`eventMap`](/api/lynx-testing-environment/Interface.LynxElement.md#eventmap) property of the [`LynxElement`](/api/lynx-testing-environment/Interface.LynxElement.md) object, so you can use the `eventMap` property to get the event handler of the element for assertion.

```jsx
import { render, fireEvent } from '@lynx-js/react/testing-library';
import { vi, expect } from 'vitest';

it('fireEvent', async () => {
  const handler = vi.fn();

  const Comp = () => {
    return <text catchtap={handler} />;
  };

  const {
    container: { firstChild: button },
  } = render(<Comp />);

  expect(button).toMatchInlineSnapshot(`<text />`);

  expect(button.eventMap).toMatchInlineSnapshot(`
    {
      "catchEvent:tap": [Function],
    }
  `);

  expect(handler).toHaveBeenCalledTimes(0);

  // Method 1: Construct the Event object yourself
  const event = new Event('catchEvent:tap');
  Object.assign(event, {
    eventType: 'catchEvent',
    eventName: 'tap',
    key: 'value',
  });
  expect(fireEvent(button, event)).toBe(true);

  expect(handler).toHaveBeenCalledTimes(1);
  expect(handler).toHaveBeenCalledWith(event);
  expect(handler.mock.calls[0][0].type).toMatchInlineSnapshot(
    `"catchEvent:tap"`,
  );
  expect(handler.mock.calls[0][0]).toMatchInlineSnapshot(`
  Event {
    "eventName": "tap",
    "eventType": "catchEvent",
    "isTrusted": false,
    "key": "value",
  }
  `);

  // Method 2: Pass in event type and initialization parameters
  fireEvent.tap(button, {
    eventType: 'catchEvent',
    key: 'value',
  });
  expect(handler).toHaveBeenCalledTimes(2);
  expect(handler.mock.calls[1][0]).toMatchInlineSnapshot(`
  Event {
    "eventName": "tap",
    "eventType": "catchEvent",
    "isTrusted": false,
    "key": "value",
  }
  `);
});
```

### Testing Refs

In ReactLynx Testing Library, you can use snapshot testing on the rendering result and the corresponding `ref` object of the element to determine whether it is set correctly.

```jsx
import { test, expect } from 'vitest';
import { render } from '@lynx-js/react/testing-library';
import { Component, createRef } from '@lynx-js/react';

it('element ref', async () => {
  const ref = createRef();
  const Comp = () => {
    return <view ref={ref} />;
  };
  const { container } = render(<Comp />);
  // ReactLynx sets the `has-react-ref` attribute for elements with ref
  // So you can use snapshot testing to determine whether ref is set correctly
  expect(container).toMatchInlineSnapshot(`
    <page>
      <view
        has-react-ref="true"
      />
    </page>
  `);
  // ref.current is a NodesRef object
  expect(ref.current).toMatchInlineSnapshot(`
    NodesRef {
      "_nodeSelectToken": {
        "identifier": "1",
        "type": 2,
      },
      "_selectorQuery": {},
    }
  `);
});

it('component ref', async () => {
  const ref1 = vi.fn();
  const ref2 = createRef();

  class Child extends Component {
    x = 'x';
    render() {
      return <view />;
    }
  }

  class Comp extends Component {
    render() {
      return (
        this.props.show && (
          <view>
            <Child ref={ref1} />
            <Child ref={ref2} />
          </view>
        )
      );
    }
  }

  const { container } = render(<Comp show />);
  expect(container).toMatchInlineSnapshot(`
      <page>
        <view>
          <view />
          <view />
        </view>
      </page>
    `);
  expect(ref1).toBeCalledWith(
    expect.objectContaining({
      x: 'x',
    }),
  );
  // ref2 refers to the Child component instance
  expect(ref2.current).toHaveProperty('x', 'x');
});
```

### Querying page elements

You can use [`screen`](/api/reactlynx-testing-library/Variable.screen.md) to query page elements, it provides some common methods, such as [`getByText`](/api/reactlynx-testing-library/Function.getByText.md), [`getByTestId`](/api/reactlynx-testing-library/Function.getByTestId.md), etc. There are also methods like [`waitForElementToBeRemoved`](/api/reactlynx-testing-library/Function.waitForElementToBeRemoved.md) to wait for the state of page elements.

```jsx
import '@testing-library/jest-dom';
import { Component } from '@lynx-js/react';
import { expect } from 'vitest';
// waitForElementToBeRemoved is a method in @testing-library/dom that waits for an element to be removed, which is re-exported here
import {
  render,
  screen,
  waitForElementToBeRemoved,
} from '@lynx-js/react/testing-library';

const fetchAMessage = () =>
  new Promise((resolve) => {
    // we are using random timeout here to simulate a real-time example
    // of an async operation calling a callback at a non-deterministic time
    const randomTimeout = Math.floor(Math.random() * 100);

    setTimeout(() => {
      resolve({ returnedMessage: 'Hello World' });
    }, randomTimeout);
  });

class ComponentWithLoader extends Component {
  state = { loading: true };

  componentDidMount() {
    fetchAMessage().then((data) => {
      this.setState({ data, loading: false });
    });
  }

  render() {
    if (this.state.loading) {
      return <text>Loading...</text>;
    }

    return (
      <text data-testid="message">
        Loaded this message: {this.state.data.returnedMessage}!
      </text>
    );
  }
}

test('it waits for the data to be loaded', async () => {
  render(<ComponentWithLoader />);
  // elementTree.root in Lynx Test Environment is used to maintain the page element tree
  expect(elementTree.root).toMatchInlineSnapshot(`
    <page>
      <text>
        Loading...
      </text>
    </page>
  `);
  const loading = () => {
    return screen.getByText('Loading...');
  };
  await waitForElementToBeRemoved(loading);
  // Since Lynx Test Environment uses jsdom to implement Element PAPI at the bottom layer
  // you can directly access document.body to get page elements
  expect(document.body).toMatchInlineSnapshot(`
    <body>
      <page>
        <text
          data-testid="message"
        >
          Loaded this message:
          <wrapper>
            Hello World
          </wrapper>
          !
        </text>
      </page>
    </body>
  `);
  expect(screen.getByTestId('message')).toHaveTextContent(/Hello World/);
  expect(elementTree.root).toMatchInlineSnapshot(`
    <page>
      <text
        data-testid="message"
      >
        Loaded this message:
        <wrapper>
          Hello World
        </wrapper>
        !
      </text>
    </page>
  `);
});
```

In this example, we use the `waitForElementToBeRemoved` method to wait for the `Loading...` element to be removed. At this point, the page will render the `Loaded this message: Hello World!` element. We can then use the `screen.getByTestId` method to get the element on the page and assert its text content.

### Rerendering

The `render` method returns an object that contains the `rerender` method, which can be used to re-render the page. The `rerender` method will render the new component on the page and return a new object. You can use the `rerender` method to test different states of the component.

:::warning

Unlike React Testing Library, a new `container` needs to be retrieved after `rerender`. Because ReactLynx creates a new `page` element each time it loads.

:::

```jsx
import '@testing-library/jest-dom';
import { render } from '@lynx-js/react/testing-library';
import { expect } from 'vitest';

it('rerender will re-render your component', async () => {
  const Greeting = (props) => <text>{props.message}</text>;
  const { container, rerender } = render(<Greeting message="hi" />);
  expect(container).toMatchInlineSnapshot(`
    <page>
      <text>
        hi
      </text>
    </page>
  `);
  expect(container.firstChild).toHaveTextContent('hi');

  {
    const { container } = rerender(<Greeting message="hey" />);
    expect(container.firstChild).toHaveTextContent('hey');

    expect(container).toMatchInlineSnapshot(`
      <page>
        <text>
          hey
        </text>
      </page>
    `);
  }
});
```

### Testing [list](/api/elements/built-in/list.md)

Since the `list` element's `list-item` elements are lazily loaded, they are only loaded when they enter the viewport and marked as recyclable when they leave the viewport. In the testing framework, you can use the [`elementTree.enterListItemAtIndex`](/api/lynx-testing-environment/Function.initElementTree.md#enterlistitematindex) and [`elementTree.leaveListItem`](/api/lynx-testing-environment/Function.initElementTree.md#leaveListItem) methods to simulate loading and recycling of list item elements.

```jsx
import { useState } from '@lynx-js/react';
import { render } from '@lynx-js/react/testing-library';
import { expect } from 'vitest';

it('list', () => {
  const Comp = () => {
    const [list, setList] = useState([0, 1, 2]);
    return (
      <list>
        {list.map((item) => (
          <list-item key={item} item-key={item}>
            <text>{item}</text>
          </list-item>
        ))}
      </list>
    );
  };
  const { container } = render(<Comp />);
  expect(container).toMatchInlineSnapshot(`
    <page>
      <list
        update-list-info="[{"insertAction":[{"position":0,"type":"__Card__:__snapshot_f75b7_test_2","item-key":0},{"position":1,"type":"__Card__:__snapshot_f75b7_test_2","item-key":1},{"position":2,"type":"__Card__:__snapshot_f75b7_test_2","item-key":2}],"removeAction":[],"updateAction":[]}]"
      />
    </page>
  `);
  const list = container.firstChild;

  // Enter the list-item element at the given index 0, it will load the list-item element
  const uid0 = elementTree.enterListItemAtIndex(list, 0);
  expect(list).toMatchInlineSnapshot(`
    <list
      update-list-info="[{"insertAction":[{"position":0,"type":"__Card__:__snapshot_f75b7_test_2","item-key":0},{"position":1,"type":"__Card__:__snapshot_f75b7_test_2","item-key":1},{"position":2,"type":"__Card__:__snapshot_f75b7_test_2","item-key":2}],"removeAction":[],"updateAction":[]}]"
    >
      <list-item
        item-key="0"
      >
        <text>
          0
        </text>
      </list-item>
    </list>
  `);

  // Leave the list-item element at the given index 0, it will mark the list-item element as unused and can be recycled
  elementTree.leaveListItem(list, uid0);
  expect(list).toMatchInlineSnapshot(`
    <list
      update-list-info="[{"insertAction":[{"position":0,"type":"__Card__:__snapshot_f75b7_test_2","item-key":0},{"position":1,"type":"__Card__:__snapshot_f75b7_test_2","item-key":1},{"position":2,"type":"__Card__:__snapshot_f75b7_test_2","item-key":2}],"removeAction":[],"updateAction":[]}]"
    >
      <list-item
        item-key="0"
      >
        <text>
          0
        </text>
      </list-item>
    </list>
  `);

  // Trigger componentAtIndex method of list, load the 1th item (it will reuse the recycled item)
  const uid1 = elementTree.enterListItemAtIndex(list, 1);
  expect(list).toMatchInlineSnapshot(`
    <list
      update-list-info="[{"insertAction":[{"position":0,"type":"__Card__:__snapshot_f75b7_test_2","item-key":0},{"position":1,"type":"__Card__:__snapshot_f75b7_test_2","item-key":1},{"position":2,"type":"__Card__:__snapshot_f75b7_test_2","item-key":2}],"removeAction":[],"updateAction":[]}]"
    >
      <list-item
        item-key="1"
      >
        <text>
          1
        </text>
      </list-item>
    </list>
  `);
});
```

In this example, we entered the list item element at index 0, loaded the list item element, then left the list item element at index 0, marked the list item element as recyclable, and finally entered the list item element at index 1, which reused the recycled `list-item`.

### Testing [Main thread script](/react/main-thread-script.md)

The test for the main thread script does not require additional configuration. It is important to note that you cannot directly call background thread methods in the main thread script, so it is recommended to place the function on `globalThis` for assertion, as shown below:

```jsx
import { fireEvent, render } from '@lynx-js/react/testing-library';
import { expect } from 'vitest';

it('main thread script', async () => {
  globalThis.cb = vi.fn();
  const Comp = () => {
    return (
      <view
        main-thread:bindtap={(e) => {
          'main thread';
          globalThis.cb(e);
        }}
      >
        <text>Hello Main Thread Script</text>
      </view>
    );
  };
  const { container } = render(<Comp />, {
    // You can try to enable both the main thread and the background thread at the same time
    // and the results will be the same
    // enableMainThread: true,
    // enableBackgroundThread: true,
  });
  expect(container).toMatchInlineSnapshot(`
    <page>
      <view>
        <text>
          Hello Main Thread Script
        </text>
      </view>
    </page>
  `);
  fireEvent.tap(container.firstChild, {
    key: 'value',
  });
  expect(cb).toBeCalledTimes(1);
  expect(cb.mock.calls).toMatchInlineSnapshot(`
    [
      [
        {
          "eventName": "tap",
          "eventType": "bindEvent",
          "isTrusted": false,
          "key": "value",
        },
      ],
    ]
  `);
});
```

In this example, we triggered a `tap` event and called the `globalThis.cb` function in the event handler. We then asserted that the `globalThis.cb` function was called once and that the `key` property in the event object was `value`.

### More usage

For more usage, please refer to the [test cases](https://github.com/lynx-family/lynx-stack/tree/main/packages/react/testing-library/src/__tests__) maintained in the ReactLynx Testing Library source code.

## Advanced

### Change the rendering behavior of [dual-threading](/react/thinking-in-reactlynx.md#your-code-runs-on-two-threads)

In the second parameter [`RenderOptions`](/api/reactlynx-testing-library/Interface.RenderOptions.md) of the [`render`](/api/reactlynx-testing-library/Function.render.md) method, there are two options [`enableMainThread`](/api/reactlynx-testing-library/Interface.RenderOptions.md#enablemainthread) and [`enableBackgroundThread`](/api/reactlynx-testing-library/Interface.RenderOptions.md#enablebackgroundthread). `enableMainThread` is used to enable [IFR](/guide/interaction/ifr.md) and `enableBackgroundThread` is used to enable background thread rendering.

Take this example:

```jsx
const Comp = () => {
  return <text>{__BACKGROUND__ ? 'background' : 'main thread'}</text>;
};
```

The table below lists the rendering results under different configurations:

| `enableMainThread` | `enableBackgroundThread` | IFR result    | Background result | Applicable scenarios                                                     |
| ------------------ | ------------------------ | ------------- | ----------------- | ------------------------------------------------------------------------ |
| `false`            | `true`                   | None          | `background`      | Default value, suitable for most scenarios                               |
| `true`             | `false`                  | `main thread` | None              | Scenarios that require ensuring correct IFR rendering result             |
| `true`             | `true`                   | `main thread` | `background`      | Scenarios that require ensuring the dual-thread rendering works normally |

#### Pitfalls

If you want to write a test case to test the IFR rendering (i.e. `enableMainThread: true`) result, make sure that the rendering does not depend on side effects from the top level.

In ReactLynx Testing Library, we do not generate two bundles for dual-threading like using Rspeedy, which will cause the top-level code to be executed only once in the background thread. In the following case, the value of the `isBackground` variable will be set to `true`.

```jsx
import '@testing-library/jest-dom';
import { describe, expect, it } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

const isBackground = __BACKGROUND__;

describe('IFR Testing', () => {
  it('will render a wrong result if it has top-level side effects', () => {
    const CompWithTopLevelSideEffects = () => {
      return <text>{isBackground ? 'background' : 'main thread'}</text>;
    };

    const { container } = render(<CompWithTopLevelSideEffects />, {
      enableMainThread: true,
      enableBackgroundThread: false,
    });
    // Test fails
    // Error: expect(element).toHaveTextContent()
    // Expected element to have text content:
    //   main thread
    // Received:
    //   background
    expect(container).toHaveTextContent('main thread');
  });
});
```

The correct way is to use `__BACKGROUND__` inside the component. Here is an example:

```jsx
import '@testing-library/jest-dom';
import { describe, expect, it } from 'vitest';
import { render } from '@lynx-js/react/testing-library';

describe('IFR Testing', () => {
  it('will render the correct result if it does not have top-level side effects', () => {
    const Comp = () => {
      return <text>{__BACKGROUND__ ? 'background' : 'main thread'}</text>;
    };

    const { container } = render(<Comp />, {
      enableMainThread: true,
      enableBackgroundThread: false,
    });
    // Test passes
    expect(container).toHaveTextContent('main thread');
  });
});
```

## API Reference

See details in [API Reference](/api/reactlynx-testing-library/index.md).



---
url: /react/routing/react-router.md
---

# React Router

React Router enables "single page routing".

### Installation

Since ReactLynx only have React v17 API now, you should install `react-router` v6.


```sh [npm]
npm install react-router@6
```

```sh [yarn]
yarn add react-router@6
```

```sh [pnpm]
pnpm add react-router@6
```

```sh [bun]
bun add react-router@6
```

```sh [deno]
deno add npm:react-router@6
```

### Routing

Routes are configured by rendering `<Routes>` and `<Route>` that couple URL segments to UI elements.

```jsx
import { root } from '@lynx-js/react';
import { MemoryRouter, Routes, Route } from 'react-router';

import { App } from './App.jsx';
import { Home } from './Home.jsx';

root.render(
  <MemoryRouter>
    <Routes>
      <Route path="/" element={<App />} />
      <Route path="/home" element={<Home />} />
    </Routes>
  </MemoryRouter>,
);

if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}
```

See [React Router - Routing](https://reactrouter.com/start/library/routing) for details.

### Navigating

There are no `<Link>` or `<NavLink>` components now in ReactLynx.
You may use `useNavigate` to navigate between routes.

```jsx
import { useNavigate } from 'react-router';

export function App() {
  const nav = useNavigate();

  return (
    <view>
      <text bindtap={() => nav('/home')}>Navigate to Home</text>
    </view>
  );
}
```

### URL Values

#### Route Params

Route params are the parsed values from a dynamic segment.

```jsx
<Route path="/concerts/:city" element={<City />} />
```

In this case, `:city` is the dynamic segment. The parsed value for that city will be available from `useParams`

```jsx
import { useParams } from 'react-router';

function City() {
  let { city } = useParams();
  let data = useFakeDataLibrary(`/api/v2/cities/${city}`);
}
```

See [React Router - useParams](https://reactrouter.com/6.28.1/hooks/use-params) for more details.

#### Location Object

React Router creates a custom location object with some useful information on it accessible with `useLocation`.

```js
import { useEffect } from '@lynx-js/react';
import { useLocation } from 'react-router';

function useAnalytics() {
  let location = useLocation();
  useEffect(() => {
    sendFakeAnalytics(location.pathname);
  }, [location]);
}
```

See [React Router - useLocation](https://reactrouter.com/6.28.1/hooks/use-location) for more details.



---
url: /react/routing/tanstack-router.md
---

# TanStack Router

Modern and scalable routing for React applications.

ReactLynx supports both [Memory Routing](https://tanstack.com/router/latest/docs/framework/react/guide/history-types#memory-routing)
and [File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing),
where Memory Routing is required due to browser [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) limitations in Lynx,
and File-Based Routing is enabled through seamless `@tanstack/router-plugin/rspack` integration in Rspeedy.

### Installation

Install dependencies:


```sh [npm]
npm install @tanstack/react-router url-search-params-polyfill
```

```sh [yarn]
yarn add @tanstack/react-router url-search-params-polyfill
```

```sh [pnpm]
pnpm add @tanstack/react-router url-search-params-polyfill
```

```sh [bun]
bun add @tanstack/react-router url-search-params-polyfill
```

```sh [deno]
deno add npm:@tanstack/react-router npm:url-search-params-polyfill
```

Install devDependencies:


```sh [npm]
npm install @tanstack/router-plugin -D
```

```sh [yarn]
yarn add @tanstack/router-plugin -D
```

```sh [pnpm]
pnpm add @tanstack/router-plugin -D
```

```sh [bun]
bun add @tanstack/router-plugin -D
```

```sh [deno]
deno add npm:@tanstack/router-plugin -D
```

### Project Configuration

- **File-based Routing**: Enabled via `@tanstack/router-plugin/rspack` for seamless routing integration.
- **React 18 API Compatibility**: Use `@lynx-js/react/compat` to ensure third-party libraries work correctly.

❓ Why use @lynx-js/react/compatReactLynx offers React 18 API compatibility via `@lynx-js/react/compat`,
providing crucial APIs such as `React.startTransition` required by TanStack
Router.

```js title=lynx.config.js
import { defineConfig } from '@lynx-js/rspeedy';
import { tanstackRouter } from '@tanstack/router-plugin/rspack';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default defineConfig({
  // ...other configs
  source: {
    alias: {
      react$: require.resolve('@lynx-js/react/compat'),
    },
  },
  tools: {
    rspack: {
      plugins: [
        tanstackRouter({
          target: 'react',
        }),
      ],
    },
  },
});
```

### Router Configuration

In the Lynx environment, the [document](https://developer.mozilla.org/en-US/docs/Web/API/Document) is `undefined`, causing the router to incorrectly identify it as `isServer: true`. You need to explicitly set `isServer: false` to ensure proper rendering.

Additionally, [Memory Routing](https://tanstack.com/router/latest/docs/framework/react/guide/history-types#memory-routing) is required due to browser [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) limitations in Lynx.

```tsx title=App.tsx
import {
  createMemoryHistory,
  createRouter,
  RouterProvider,
} from '@tanstack/react-router';

import { routeTree } from './routeTree.gen.js';

const memoryHistory = createMemoryHistory({
  initialEntries: ['/'],
});

const router = createRouter({
  routeTree,
  history: memoryHistory,
  isServer: false, // [!code highlight]
});

export function App() {
  return <RouterProvider router={router} />;
}
```

### Polyfill

To ensure [URLSearchParams API](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) works correctly in the Lynx environment,
add `url-search-params-polyfill` at the top of your entry file:

```tsx title=index.tsx
import 'url-search-params-polyfill';

import { root } from '@lynx-js/react';
import { App } from './App.jsx';

root.render(<App />);
```

### File-Based

TanStack Router supports file-based routing where your file structure defines your routes.
Place your route components in the `src/routes` directory, with `__root.tsx` serving as the root component.

```jsx title="src/routes/__root.tsx"
import { createRootRoute, Outlet } from '@tanstack/react-router';

export const Route = createRootRoute({
  component: () => (
    <view>
      <Outlet />
    </view>
  ),
});
```

```jsx title="src/routes/Index.tsx"
import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/')({
  component: () => <view>Index Page</view>,
});
```

The `@tanstack/router-plugin/rspack` automatically scans the `src/routes` directory and generates a `routeTree.gen.ts` file
that contains all the route definitions and type information. This generated file includes:

- Route imports and configurations
- TypeScript interfaces for type-safe routing
- The complete route tree structure

See [TanStack File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing) for more details.

### Example

**This is an example below: tanstack-router**

**Entry:** `src/tanstack-router`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { createMemoryHistory, createRouter, RouterProvider } from "@tanstack/react-router";

import { routeTree } from "./routeTree.gen.js";

const memoryHistory = createMemoryHistory({
  initialEntries: ["/"],
});

const router = createRouter({ routeTree, history: memoryHistory, isServer: false });

export function App() {
  return <RouterProvider router={router} />;
}

```





---
url: /react/state-management/jotai.md
---

# Jotai

## Using `jotai`

[Jotai](https://jotai.org) takes an atomic approach to global React state management.

### Installation


```sh [npm]
npm install jotai
```

```sh [yarn]
yarn add jotai
```

```sh [pnpm]
pnpm add jotai
```

```sh [bun]
bun add jotai
```

```sh [deno]
deno add npm:jotai
```

### Example

```jsx
import { useEffect } from '@lynx-js/react';
import { atom, useAtom } from 'jotai';

const counter = atom(0);

export function App() {
  const [count, setCounter] = useAtom(counter);

  useEffect(() => {
    console.log('count changed:', count);
  }, [count]);

  return (
    <view>
      <text>{count}</text>
      <text bindtap={() => setCounter((prev) => prev + 1)}>Tap</text>
    </view>
  );
}
```

See [Jotai - atom](https://jotai.org/docs/core/atom) for details.



---
url: /react/state-management/valtio.md
---

# Valtio

## Using `valtio`

[Valtio](https://valtio.dev/) is a simple and powerful proxy-based state management solution, offering fine-grained subscriptions and reactivity.

### Installation


```sh [npm]
npm install valtio
```

```sh [yarn]
yarn add valtio
```

```sh [pnpm]
pnpm add valtio
```

```sh [bun]
bun add valtio
```

```sh [deno]
deno add npm:valtio
```

### Example

```tsx
import { useEffect } from '@lynx-js/react';
import { proxy, useSnapshot, subscribe } from 'valtio';

const state = proxy<{ count: number }>({ count: 0 });

export function App() {
  const snap = useSnapshot(state);

  const handleTap = () => {
    state.count++;
  };

  useEffect(() => {
    const unsubscribe = subscribe(state, () => {
      console.log('state changed: ', state.count);
    });

    return () => {
      unsubscribe();
    };
  }, []);

  return (
    <view>
      <text>{snap.count}</text>
      <text bindtap={handleTap}>Tap</text>
    </view>
  );
}
```

See [valtio - basic](https://valtio.dev/docs/api/basic/proxy) for details.



---
url: /react/state-management/zustand.md
---

# Zustand

## Using `zustand`

[Zustand](https://zustand-demo.pmnd.rs/) is a small, fast, and scalable state management solution with a comfy API based on React Hooks, offering flexibility while maintaining some level of convention.

### Installation


```sh [npm]
npm install zustand
```

```sh [yarn]
yarn add zustand
```

```sh [pnpm]
pnpm add zustand
```

```sh [bun]
bun add zustand
```

```sh [deno]
deno add npm:zustand
```

### Example

```tsx
import { useEffect } from '@lynx-js/react';
import { create } from 'zustand';

type State = {
  count: number;
};

type Action = {
  increment: () => void;
};

const useStore = create<State & Action>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}));

export function App() {
  const { count, increment } = useStore();

  useEffect(() => {
    console.log('count changed:', count);
  }, [count]);

  return (
    <view>
      <text>{count}</text>
      <text bindtap={increment}>Tap</text>
    </view>
  );
}
```

See [zustand - guides](https://zustand.docs.pmnd.rs/guides/updating-state) for details.



---
url: /react/thinking-in-reactlynx.md
---

# Thinking in ReactLynx

ReactLynx follows React's programming model, but leverages the _**dual-threaded runtimes**_ provided by Lynx to achieve better performance and user experience through its own idioms (or rules).

## Your code runs on two threads

When the component `<HelloComponent />` is rendered, you will see "Hello" printed twice in the Console.

```jsx
const HelloComponent = () => {
  console.log('Hello'); // This will be printed twice
  return <text>Hello</text>;
};
```

This happens because the code runs on two threads: **main thread** and **background thread**, which are part of Lynx's dual-threaded runtime.

1. The **main thread** is responsible for rendering the initial screen and applying subsequent UI updates.
   This allows users to see the first screen as quickly as possible while reducing the main thread's workload.
2. The **background thread** runs with a complete React runtime, handling component lifecycles and other side effects. Since complete consistency with single-threaded React is not possible, we have a modified component lifecycle as shown in [Component Lifecycle](/react/lifecycle.md).

### Not all code can run on both threads

However, not all code can be executed on both threads.
Consider the following example that adds a listener to `GlobalEventEmitter`:

```jsx
const EventListenerComponent = () => {
  lynx.getJSModule('GlobalEventEmitter').addListener('myHappyEvent', () => {
    console.log('myHappyEvent triggered!');
  });
  return <text>Hello</text>;
};
```

When the component `<EventListenerComponent />` is rendered, you will see a "not a function" error. This occurs because while Lynx renders this component on both threads, `lynx.getJSModule('GlobalEventEmitter')` cannot be executed on the main thread.

❓ Why does this error occur?The reason relates to Lynx's dual-threaded runtime architecture, where the code for `<EventListenerComponent />` executes on both threads:
- On the background thread:

  The `lynx.getJSModule` function is available as part of the Lynx `GlobalEventEmitter` API. Therefore, executing `lynx.getJSModule('GlobalEventEmitter')` works without issues.

- On the main thread:

  The `getJSModule` function does not exist on the main thread. Thus, when this code executes on the main thread, `lynx.getJSModule` is evaluated as `undefined`, leading to the "not a function" error.

## Some code can only run on the background thread

Typically, side effects unrelated to rendering cannot be executed on the main thread, such as data updates, event listeners, timers, and network requests.
Executing these side effects on the main thread will result in runtime errors.
We call code that only executes on the background thread **background only** code.
By marking background only code, we help the compiler optimize code and prevent these side effects from executing on the main thread.

There are three key rules for background only code:

1. [Rule 1: Code that meets any of these conditions is considered background only](#rule-1).
2. [Rule 2: Background only code can only be used within other background only code](#rule-2).
3. [Rule 3: Code that is only used by background only code is considered background only](#rule-3).

### Rule 1: Code that meets any of these conditions is considered background only \{#rule-1}

Lynx considers code that meets any of these conditions as background only:

1. Event handlers (e.g. `bindtap` / `catchtap`)
2. Effects (e.g. `useEffect` / `useLayoutEffect`)
3. `ref` prop and `useImperativeHandle`
4. Functions with [`'background only'`] directive
5. Modules with `import 'background-only'` directive

For example, all these functions with `console.log` in the following example are considered background only. These functions will neither be bundled into main thread code nor executed on the main thread.

```jsx
import { useEffect } from '@lynx-js/react';

function App() {
  useEffect(() => console.log('Effect is background only'));
  return (
    <view bindtap={(e) => console.log('Event is background only')}>
      <text ref={(ref) => console.log('Ref is background only')}>
        Hello, ReactLynx!
      </text>
    </view>
  );
}

function backgroundOnly() {
  'background only';
  console.log('Directive marked function is background only');
}
```

```js
import 'background-only';

export const env = NativeModules.env;
console.log('Directive marked module is background only');
```

Following this rule, we can see that the earlier `<EventListenerComponent />` should move its `GlobalEventEmitter` usage into `useEffect`.
This ensures this code only runs on the background thread where the `GlobalEventEmitter` API is available:

```js
import { useEffect } from '@lynx-js/react';

const EventListenerComponent = () => {
  useEffect(() => {
    lynx.getJSModule('GlobalEventEmitter').addListener('myHappyEvent', () => {
      console.log('myHappyEvent triggered!');
    });
  }, []);
  return <text>Hello</text>;
};
```

### Rule 2: Background only code can only be used within other background only code \{#rule-2}

When **dependencies** are involved, things become more complicated.
Simply put, background only code can only be called by other background only code.

```jsx
import { backgroundOnlyFunction } from 'external-module';

backgroundOnlyFunction(); // ❌ Error: calling background only at top level

export function App() {
  function backgroundOnly() {
    'background only';
    fetch();
    NativeModules.call();
    backgroundOnlyFunction(); // ✅ Correct: calling background only API inside background only function
  }

  backgroundOnly(); // ❌ Error: calling background only code in render function

  useEffect(() => {
    backgroundOnly(); // ✅ Correct: calling background only code from background only code
  }, []);

  return <view />;
}
```

### Rule 3: Code that is only used by background only code is considered background only \{#rule-3}

Usually, event callbacks of elements are considered background only. `handleTap` doesn't need the `'background only'` directive but will be considered background only code because it's only used as a handler in the `bindtap` event.

```jsx
function App() {
  function handleTap() {
    // No need to mark this function since `bindtap` is considered background only
  }
  return <view bindtap={handleTap} />;
}
```

The `backgroundOnly` function will also be considered background only because it's only called in the `useEffect` callback.

```jsx
function App() {
  function backgroundOnly() {
    // No need to mark this function
    // since `useEffect` is considered background only
    // `backgroundOnly` will be identified as unused and removed by the optimizer
  }
  useEffect(() => {
    backgroundOnly();
  });
  return <view />;
}
```

#### Exceptions

Due to limitations in compiler analysis capabilities and compile-time performance, there are some exceptions to this rule. We will work to address these issues in future versions.

When event handlers are passed as props, you must add the [`'background only'`] directive. Otherwise, the compiler cannot identify `handleTap` as background only code and will include it in the main thread bundle:

```jsx
function App() {
  function handleTap() {
    'background only';
    // Unfortunately, you must mark event callbacks here
  }
  return <Button onClick={handleTap} />;
}

function Button({ onClick }) {
  return <view bindtap={onClick} />;
}
```

When using custom Hooks, you must add the [`'background only'`] directive. Otherwise, `backgroundOnly` will be treated as non-background only code and included in the main thread bundle.
This occurs because the compiler cannot determine if the callback of `useMount` is only used in background only code.

```jsx
function useMount(effect) {
  useEffect(() => {
    effect();
  }, []);
}

function App() {
  function backgroundOnly() {
    // No need to mark this function
    // since `backgroundOnly` is only used in `useMount` callback
  }
  useMount(() => {
    'background only';
    // You need to mark this function
    backgroundOnly();
  });
  return <view />;
}
```

[`'background only'`]: /api/react/Document.directives.md#background-only

## Some code can only run on the main thread

Just as some code (like `GlobalEventEmitter`) only works on the background thread, there is also code that can only be executed on the main thread.

### Main Thread Script

Main Thread Script (MTS) is script executed on the main thread.

```js
function toRed(event) {
  'main thread';
  event.currentTarget.setStyleProperty('background-color', 'red');
}
```

For more details about MTS, including usage examples and best practices for handling animations and gestures on the main thread, please refer to [Main Thread Script](/react/main-thread-script.md).

### Element PAPIs

Lynx Engine also provides low-level APIs called [Element PAPI].

Usually, Element PAPI calls are compiled by ReactLynx and you should not need to write any Element PAPI code.

[Element PAPI]: /api/engine/element-api.md



---
url: /rspeedy/assets.md
---

# Static Assets

Powered by Rsbuild, Rspeedy supports using static assets, including images, fonts, audios and videos.

:::tip What is Static Assets
Static assets are files that are part of a Lynx application and do not change, even when the application is being used.

Examples of static assets include images, fonts, medias, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN, and delivered to the users when the Lynx application is accessed.

Because they do not change, static assets can be cached by the App, which helps to improve the performance of the Lynx application.
:::

## Import Assets

You can directly import static assets in JavaScript:

<!-- eslint-disable import/no-unresolved, import/export -->

```jsx
// Import the logo.png image in the static directory
import logo from './static/logo.png';

function App() {
  return <image src={logo} />; // Can be directly used in ReactLynx
}
```

The result of the import will be a URL string that represent the static asset. And the asset will be emitted to the output folder.

You can also use static assets in CSS:

```css
.logo {
  background-image: url('../static/logo.png');
}
```

### URL Prefix

The URL returned after importing a asset will automatically include the path prefix:

- In development, using [`dev.assetPrefix`] to set the path prefix.
- In production, using [`output.assetPrefix`] to set the path prefix.

For example, you can set `output.assetPrefix` to `https://example.com`:

<!-- eslint-disable import/no-unresolved, import/export -->

```js
import logo from './static/logo.png';

console.log(logo); // "https://example.com/assets/logo.6c12aba3.png"
```

### Public Folder

The `public` folder at the project root can be used to place some static assets. These assets will not be bundled by Rspeedy.

- When you start the dev server, these assets will be served under the root path, `/`.
- When you perform a production build, these assets will be copied to the output directory.

In JavaScript code, you can splice the URL via `process.env.ASSET_PREFIX`:

```js
const logoURL = `${process.env.ASSET_PREFIX}/logo.png`;
```

:::warning

- Avoid importing files from the public folder into your source code, instead reference them by URL.
- When referencing resources in the public folder via URL, please use absolute paths instead of relative paths.
- During the production build, the files in public folder will be copied to the output folder (default is `dist`). Please be careful to avoid name conflicts with the output files. When files in the `public` folder have the same name as outputs, the outputs have higher priority and will overwrite the files with the same name in the `public` folder.

:::

### Type Declaration

When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './static/logo.png' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the static assets, please create a `src/rspeedy-env.d.ts` file, and add the corresponding type declaration.

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

## Inline Assets

Inline static assets refer to the practice of including the content of a static asset directly in the JS output, instead of linking to an external file. This can improve the performance of a Lynx application by reducing the number of HTTP requests that Lynx has to make to load the application.

However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation.

### Automatic Inlining

Rspeedy will inline assets when the file size of is less than a threshold (the default is 2KiB). When inlined, the asset will be converted to a base64-encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.

The threshold can be modified with the [`output.dataUriLimit`] config.

For example, set the threshold of images to 5000 bytes, and set media assets not to be inlined:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
});
```

### Force Inlining

You can force an asset to be inlined by adding the `inline` query when importing the asset, regardless of whether the asset's size is smaller than the size threshold.

<!-- eslint-disable import/no-unresolved -->

```js
import img from './foo.png?inline';

console.log(img); // "data:image/png;base64,iVBORw0KGgo..."
```

In the above example, the `foo.png` image will always be inlined, regardless of whether the size of the image is larger than the threshold.

### Force No Inlining

When you want to always treat some assets as separate files, no matter how small the asset is, you can add the `url` query to force the asset not to be inlined.

<!-- eslint-disable import/no-unresolved -->

```js
import img from '. /foo.png?url';

console.log(img); // "/static/foo.fe0bb4d0.png"
```

In the above example, the `foo.png` image will always be loaded as a separate file, even if the size of the image is smaller than the threshold.

## Extend Asset Types

If the built-in asset types in Rsbuild cannot meet your requirements, you can:

- Use the [`source.assetsInclude`] configuration option to specify additional file types to be treated as static assets.
- Modify the built-in Rspack configuration and extend the asset types you need using [`tools.rspack`].

For example, if you want to treat `*.pdf` files as assets and directly output them to the dist directory, you can add the following configuration:

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

// planA: source.assetsInclude
export default defineConfig({
  source: {
    assetsInclude: /\.pdf$/,
  },
});

// planB: tools.rspack
export default defineConfig({
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // converts asset to a separate file and exports the URL address.
          type: 'asset/resource',
        },
      ]);
      return config;
    },
  },
});
```

After adding the above configuration, you can import `*.pdf` files in your code, for example:

<!-- eslint-disable import/no-unresolved -->

```js
import myFile from './static/myFile.pdf';

console.log(myFile); // "/static/myFile.6c12aba3.pdf"
```

For more information about asset modules, please refer to [Rspack - Asset modules](https://rspack.rs/guide/features/asset-module).

[`dev.assetPrefix`]: /api/rspeedy/rspeedy.dev.assetprefix.md

[`output.assetPrefix`]: /api/rspeedy/rspeedy.output.assetprefix.md

[`output.dataUriLimit`]: /api/rspeedy/rspeedy.output.dataurilimit.md

[`tools.rspack`]: /api/rspeedy/rspeedy.tools.rspack.md

[`source.assetsInclude`]: /api/rspeedy/rspeedy.source.assetsinclude.md



---
url: /rspeedy/build-profiling.md
---

# Build Profiling

Performing a performance analysis can help you identify performance bottlenecks in your project, allowing for targeted optimization.

## Using Rsdoctor

Rsdoctor is a build analyser that can visually display the compilation time of each loaders and plugins.

Please refer to [Use Rsdoctor](/rspeedy/use-rsdoctor.md) for more information.

## Node.js Profiling

When Rspeedy executes a build, you can use Node.js profiling to analyze the JavaScript execution, which helps to identify performance bottlenecks.

For example, to perform the [CPU profiling](https://nodejs.org/docs/v20.17.0/api/cli.html#--cpu-prof) analysis, run the following command in the root directory of your project:

```bash
#dev
node --cpu-prof ./node_modules/@lynx-js/rspeedy/bin/rspeedy.js dev

# build
node --cpu-prof ./node_modules/@lynx-js/rspeedy/bin/rspeedy.js build
```

The above commands will generate a `*.cpuprofile` file. We can use [speedscope](https://github.com/jlfwong/speedscope) to visualize this file:

```bash
# Install speedscope
npm install -g speedscope

# View cpuprofile content
# Replace the name with the local file name
speedscope CPU.date.000000.00000.0.001.cpuprofile
```

## Rspack profiling

Rspeedy supports the use of the `RSPACK_PROFILE` environment variable for Rspack build performance profiling.

```bash
# dev
RSPACK_PROFILE=ALL rspeedy dev

# build
RSPACK_PROFILE=ALL rspeedy build
```

This command will generate a `rspack-profile-${timestamp}` folder in the dist folder, and it will contain `logging.json`, `trace.json` and `jscpuprofile.json` files:

- `trace.json`: The time spent on each phase of the Rust side is recorded at a granular level using tracing and can be viewed using [ui.perfetto.dev](https://ui.perfetto.dev/).
- `jscpuprofile.json`: The time spent at each stage on the JavaScript side is recorded at a granular level using [Node.js inspector](https://nodejs.org/dist/latest-v18.x/docs/api/inspector.html) and can be viewed using [speedscope.app](https://www.speedscope.app/).
- `logging.json`: Includes some logging information that keeps a coarse-grained record of how long each phase of the build took. (Not supported in development environment yet)

> For more information about Rspack build performance analysis usage, please refer to [Rspack - Profiling](https://web-infra-dev.github.io/rspack-dev-guide/profiling/intro.html#profiling).



---
url: /rspeedy/cli.md
---

# CLI

Rspeedy comes with a lightweight CLI that includes commands such as `dev` and `build`.

## Using the global Rspeedy version

You can invoke Rspeedy using `npx rspeedy`, but it's more convenient to also install it globally so that it's always available in your shell `PATH`:

```bash
# Install the Rspeedy globally
npm install --global @lynx-js/rspeedy
```

:::info What if the globally installed Rspeedy binary is the wrong version?

Just like [Rush](https://rushstack.io/), Rspeedy implements a "version selector" feature that will automatically discover your local `node_modules` folder and invoke `./node_modules/.bin/rspeedy`, ensuring that the correct version is used.
:::

## Using Node.js TypeScript support

If the version of Node.js you are using supports TypeScript:

1. Node.js >= v23.6
2. Node.js >= v22.6 with [--experimental-strip-types](https://nodejs.org/api/cli.html#--experimental-strip-types)
3. Node.js >= v22.7 with [--experimental-transform-types](https://nodejs.org/api/cli.html#--experimental-transform-types)

you can use the built-in TS transformation of Node.js.

```json title="package.json"
{
  "build": "NODE_OPTIONS=--experimental-transform-types rspeedy build"
}
```

See [Node.js - TypeScript](https://nodejs.org/api/typescript.html) for more details.

## rspeedy -h

To view all available CLI commands, run the following command in the project directory:

```bash
rspeedy -h
```

The output is shown below:

```text
➜ rspeedy --help

Usage: rspeedy <command> [options]

Options:
  -V, --version      output the version number
  --unmanaged        Force to use the unmanaged version of Rspeedy, instead of the locally installed.
  -h, --help         display help for command

Commands:
  build [options]    Build the project in production mode
  dev [options]      Run the dev server and watch for source file changes while serving.
  inspect [options]  View the Rsbuild config and Rspack config of the project.
  preview [options]  Preview the production build outputs locally.
  help [command]     display help for command
```

## rspeedy dev

The `rspeedy dev` command is used to start a local dev server and compile the source code for development.

```text
➜ rspeedy dev --help

Usage: rspeedy dev [options]

Run the dev server and watch for source file changes while serving.

Options:
  --base <base>            specify the base path of the server
  --environment <name...>  specify the name of environment to build
  -c --config <config>     specify the configuration file, can be a relative or absolute path
  --env-mode <mode>        specify the env mode to load the .env.[mode] file
  --no-env                 disable loading `.env` files"
  -m --mode <mode>         specify the build mode, can be `development`, `production` or `none`
  -h, --help               display help for command
```

The dev server will restart automatically when the content of the configuration file is modified.

## rspeedy build

The `rspeedy build` command will build the outputs for production in the `dist/` directory by default.

```text
➜ rspeedy build --help

Usage: rspeedy build [options]

Build the project in production mode

Options:
  --environment <name...>  specify the name of environment to build
  --watch                  Enable watch mode to automatically rebuild on file changes
  -c --config <config>     specify the configuration file, can be a relative or absolute path
  --env-mode <mode>        specify the env mode to load the .env.[mode] file
  --no-env                 disable loading `.env` files"
  -m --mode <mode>         specify the build mode, can be `development`, `production` or `none`
  -h, --help               display help for command
```

## rspeedy preview

The `rspeedy preview` command is used to preview the production build outputs locally. Note that you need to execute the `rspeedy build` command beforehand to generate the build outputs.

```text
➜ rspeedy preview --help

Usage: rspeedy preview [options]

Preview the production build outputs locally.

Options:
  --base <base>         specify the base path of the server
  -c --config <config>  specify the configuration file, can be a relative or absolute path
  --env-mode <mode>     specify the env mode to load the .env.[mode] file
  --no-env              disable loading `.env` files"
  -m --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  -h, --help            display help for command
```

:::tip
The preview command is only used for local preview. Do not use it for production servers, as it is not designed for that.
:::

## rspeedy inspect

The `rspeedy inspect` command is used to view the Rspeedy config and Rspack config of the project.

```text
➜ rspeedy inspect --help

Usage: rspeedy inspect [options]

View the Rsbuild config and Rspack config of the project.

Options:
  --output <output>     specify inspect content output path
  --verbose             show full function definitions in output
  -c --config <config>  specify the configuration file, can be a relative or absolute path
  --env-mode <mode>     specify the env mode to load the .env.[mode] file
  --no-env              disable loading `.env` files"
  -m --mode <mode>      specify the build mode, can be `development`, `production` or `none`
  -h, --help            display help for command
```

When you run the command `rspeedy inspect` in the project root directory, the following files will be generated in the `dist/.rspeedy` directory of the project:

- `rspeedy.config.js`: Represents the Rspeedy configuration used during the build.
- `rsbuild.config.mjs`: Represents the Rsbuild configuration used during the build.
- `rspack.config.lynx.mjs`: Represents the Rspack configuration used during the build.

```text
➜ rspeedy inspect

Inspect config succeed, open following files to view the content:

  - Rspeedy Config: /project/dist/.rsbuild/rspeedy.config.mjs
  - Rspack Config (lynx): /project/dist/.rsbuild/rspack.config.lynx.mjs

Inspect Rspeedy config succeed, open following files to view the content:

  - Rspeedy: /Users/colin/rspeedy/examples/react/dist/rspeedy-rspack/.rsbuild/rspeedy.config.js
```

### Specifying Mode

By default, the inspect command outputs the configuration for the development mode. You can add the `--mode production` option to output the configuration for the production mode:

```bash
rspeedy inspect --mode production
```

### Verbose content

By default, the inspect command omits the content of functions in the configuration object. You can add the `--verbose` option to output the complete content of functions:

```bash
rspeedy inspect --verbose
```



---
url: /rspeedy/external-bundle.md
---

# External Bundle

3.5
External Bundle lets you build a Lynx bundle once and load it from multiple Lynx apps at runtime. Use it when you want to share ReactLynx components or common business bundles across apps.

Compared with [Chunk Splitting](/api/rspeedy/rspeedy.performance.chunksplit.md), External Bundle is for cross-application reuse, while Chunk Splitting is for splitting code inside one app.

This workflow has two parts:

1. Use [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config.md) to build the external bundle.
2. Use [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin.md) to load it in the host app.

The responsibilities are equally simple:

- the library build emits the `.lynx.bundle`
- the host app declares where the bundle is loaded from and which section the runtime should request

## Install


```sh [npm]
npm install @lynx-js/lynx-bundle-rslib-config @lynx-js/external-bundle-rsbuild-plugin @lynx-js/react-umd @rslib/core -D
```

```sh [yarn]
yarn add @lynx-js/lynx-bundle-rslib-config @lynx-js/external-bundle-rsbuild-plugin @lynx-js/react-umd @rslib/core -D
```

```sh [pnpm]
pnpm add @lynx-js/lynx-bundle-rslib-config @lynx-js/external-bundle-rsbuild-plugin @lynx-js/react-umd @rslib/core -D
```

```sh [bun]
bun add @lynx-js/lynx-bundle-rslib-config @lynx-js/external-bundle-rsbuild-plugin @lynx-js/react-umd @rslib/core -D
```

```sh [deno]
deno add npm:@lynx-js/lynx-bundle-rslib-config npm:@lynx-js/external-bundle-rsbuild-plugin npm:@lynx-js/react-umd npm:@rslib/core -D
```

:::note Why `@lynx-js/react-umd` is needed
`@lynx-js/react-umd` provides the ReactLynx runtime bundles required by the built-in `reactlynx` preset.

When you enable `externalsPresets.reactlynx`, the plugin resolves `@lynx-js/react-umd/dev` or `@lynx-js/react-umd/prod` based on `NODE_ENV`, emits `react.lynx.bundle`, and loads it through the current runtime public path.

For most projects, installing `@lynx-js/react-umd` and enabling the `reactlynx` preset is enough.
:::

## Build An External Bundle

For a ReactLynx component bundle, the recommended setup is:

```ts title="rslib-comp-lib.config.ts"
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineExternalBundleRslibConfig({
  id: 'comp-lib',
  source: {
    entry: {
      './App.js': './external-bundle/CompLib.tsx',
    },
  },
  plugins: [pluginReactLynx()],
  output: {
    externalsPresets: {
      reactlynx: true,
    },
  },
});
```

`externalsPresets.reactlynx` maps the standard ReactLynx requests for you, so a ReactLynx component bundle can depend on the shared runtime directly.

Run the build with:


```sh [npm]
npm exec rslib build --config rslib-comp-lib.config.ts
```

```sh [yarn]
yarn exec rslib build --config rslib-comp-lib.config.ts
```

```sh [pnpm]
pnpm exec rslib build --config rslib-comp-lib.config.ts
```

```sh [bun]
bun exec rslib build --config rslib-comp-lib.config.ts
```

```sh [deno]
deno exec npm:rslib npm:build --config npm:rslib-comp-lib.config.ts
```

After a successful build, you will get an output directory like this:

```text
├── dist-external-bundle
│   └── comp-lib.template.js
```

### Bundle CSS

3.7
If you need to run CSS from the External Bundle, set `engineVersion: '3.7'` when building that bundle:

```ts title="rslib-comp-lib.config.ts"
export default defineExternalBundleRslibConfig({
  plugins: [
    pluginReactLynx({
      engineVersion: '3.7',
    }),
  ],
});
```

Pure JS / TS External Bundles do not need this.

## Load It In The Host App

Use the same request key in the app:

```ts title="lynx.config.ts"
import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin';
import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  plugins: [
    pluginReactLynx(),
    pluginQRCode(),
    pluginExternalBundle({
      externalsPresets: {
        reactlynx: true,
      },
      externals: {
        './App.js': 'comp-lib.lynx.bundle',
      },
    }),
  ],
});
```

This shorthand is equivalent to the following expanded config:

```ts
externals: {
  './App.js': {
    bundlePath: 'comp-lib.lynx.bundle',
    libraryName: './App.js',
    background: { sectionPath: './App.js' },
    mainThread: { sectionPath: './App.js__main-thread' },
    async: true,
  },
}
```

If your section names already match the request key, this is the smallest recommended setup.

## Verify It Works

After the configuration above, use these signals to confirm that the External Bundle is wired up correctly:

- the host app successfully requests `comp-lib.lynx.bundle` at runtime
- when `externalsPresets.reactlynx` is enabled, the runtime also loads `react.lynx.bundle` automatically
- components from the External Bundle render normally, without section mismatch or bundle loading failures

If it still does not run, check whether the request key, bundle path, and section names in `externals` are aligned.

## Advanced: When To Set `globalObject`

In most projects, you can omit `globalObject`.

Set `globalObject: 'globalThis'` only when your app enables a shared `globalThis` across background-thread runtimes and you want later bundles to reuse externals that have already been loaded there.

Use it on both sides when needed:

```ts title="rslib-comp-lib.config.ts"
output: {
  externalsPresets: {
    reactlynx: true,
  },
  globalObject: 'globalThis',
}
```

```ts title="lynx.config.ts"
pluginExternalBundle({
  externalsPresets: {
    reactlynx: true,
  },
  externals: {
    './App.js': 'comp-lib.lynx.bundle',
  },
  globalObject: 'globalThis',
});
```

## Extend Presets

Use the same preset name on both sides so the bundle build and the host app stay aligned.

### From The Library Side

On the external bundle build side, presets live in `output.externalsPresets` and `output.externalsPresetDefinitions`:

```ts title="rslib-comp-lib.config.ts"
import { defineExternalBundleRslibConfig } from '@lynx-js/lynx-bundle-rslib-config';

export default defineExternalBundleRslibConfig({
  output: {
    externalsPresets: {
      reactlynxPlus: true,
    },
    externalsPresetDefinitions: {
      reactlynxPlus: {
        extends: 'reactlynx',
        externals: {
          '@lynx-js/lynx-ui': ['LynxUI', 'UI'],
        },
      },
    },
  },
});
```

This side decides how imports are mapped to external globals when the bundle is built.

### From The Lynx Page Side

On the host app side, presets live in `pluginExternalBundle({ externalsPresets, externalsPresetDefinitions })`:

```ts title="lynx.config.ts"
import { pluginExternalBundle } from '@lynx-js/external-bundle-rsbuild-plugin';

pluginExternalBundle({
  externalsPresets: {
    reactlynxPlus: true,
  },
  externalsPresetDefinitions: {
    reactlynxPlus: {
      extends: 'reactlynx',
      resolveExternals() {
        return {
          '@lynx-js/lynx-ui': {
            libraryName: ['LynxUI', 'UI'],
            bundlePath: 'lynx-ui.lynx.bundle',
            background: { sectionPath: 'LynxUI' },
            mainThread: { sectionPath: 'LynxUI__main-thread' },
            async: false,
          },
        };
      },
    },
  },
});
```

This side decides where the bundle is loaded from and which section names the runtime should request.

Explicit `externals` still override mappings provided by presets. Use that when a single app needs a different bundle path or section name.

## Advanced: When To Use The Object Form

Use the full object form when you need custom section names, custom exported library names, timeouts, or a dedicated local bundle directory.

The `external-bundle` example in `lynx-examples` uses that style:

```ts title="lynx.config.mjs"
pluginExternalBundle({
  externalBundleRoot: 'dist-external-bundle',
  externalsPresets: {
    reactlynx: true,
  },
  externals: {
    'lodash-es': {
      bundlePath: 'lodash-es.lynx.bundle',
      background: { sectionPath: 'lodash-es' },
      mainThread: { sectionPath: 'lodash-es__main-thread' },
      async: false,
      timeout: 10000,
    },
    './components': {
      bundlePath: 'comp.lynx.bundle',
      background: { sectionPath: 'component' },
      mainThread: { sectionPath: 'component__main-thread' },
      async: true,
      timeout: 5000,
    },
  },
  timeout: 10000,
});
```

Use this form when:

- one bundle contains multiple business modules
- section names do not match the request key
- bundles are built into `dist-external-bundle`
- you want per-bundle timeout or loading behavior

## Example

The `lynx-examples` external-bundle example is available directly in the docs:

**This is an example below: external-bundle**

**Bundle:** `dist/index.lynx.bundle`

```js
// Copyright 2024 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { pluginExternalBundle } from "@lynx-js/external-bundle-rsbuild-plugin";
import { pluginQRCode } from "@lynx-js/qrcode-rsbuild-plugin";
import { pluginReactLynx } from "@lynx-js/react-rsbuild-plugin";
import { defineConfig } from "@lynx-js/rspeedy";

export default defineConfig({
  source: {
    entry: {
      index: "./src/index",
    },
  },
  output: {
    filename: "[name].[platform].bundle",
    assetPrefix: "https://unpkg.com/@lynx-example/external-bundle@latest/dist",
  },
  plugins: [
    pluginReactLynx(),
    pluginQRCode(),
    pluginExternalBundle({
      externalBundleRoot: "dist-external-bundle",
      externalsPresets: {
        reactlynx: true,
      },
      externals: {
        "lodash-es": {
          bundlePath: "lodash-es.lynx.bundle",
          background: { sectionPath: "lodash-es" },
          mainThread: { sectionPath: "lodash-es__main-thread" },
          async: false,
          timeout: 10000,
        },
        "./components": {
          bundlePath: "comp.lynx.bundle",
          background: { sectionPath: "component" },
          mainThread: { sectionPath: "component__main-thread" },
          async: true,
          timeout: 5000,
        },
      },
      timeout: 10000,
    }),
  ],
});

```



## API Reference

- [`defineExternalBundleRslibConfig()`](/api/rspeedy/lynx-bundle-rslib-config.defineexternalbundlerslibconfig.md)
- [`pluginExternalBundle()`](/api/rspeedy/external-bundle-rsbuild-plugin.pluginexternalbundle.md)
- [`@lynx-js/lynx-bundle-rslib-config`](/api/rspeedy/lynx-bundle-rslib-config.md)
- [`@lynx-js/external-bundle-rsbuild-plugin`](/api/rspeedy/external-bundle-rsbuild-plugin.md)



---
url: /rspeedy/index.md
---

# <span class="hero-title"><span class="normal">The </span><span class="brand-ani">Build Tool </span><span class="normal">for </span><span class="brand">Lynx</span></span>

> Build your Lynx application instantly with Rspack

[Get Started](/rspeedy/start/quick-start.html) | [API](/api/rspeedy.html)



---
url: /rspeedy/output.md
---

# Output Files

This chapter will introduces the directory structure of output files and how to control the output directory of different types of files.

## Default Directory Structure

The following is a basic directory for output files. By default, the compiled files will be output in the `dist` directory of current project.

### Production

In production, the `dist/` directory contains all the files that need to be deployed.

```txt
dist/
├── [name].lynx.bundle
├── async
│   └── [name].lynx.bundle
└── static
    ├── image
    │   └── [name].[hash].png
    ├── svg
    │   └── [name].[hash].svg
    └── js
        ├── [id].[hash].js
        │   └── async
        │       └── [id].[hash].js
        └── lib-preact.[hash].js
```

The most common output files are Bundle files, JS files and static assets:

- Bundle files(`[name].lynx.bundle`), which can be configured with [`output.filename.bundle`].
- Async(lazy) bundle files(`async/[name].lynx.bundle`).
- JS files(`static/js/*.js`), which can be configured with [`output.distPath.js`] and [`output.filename.js`].
- Static assets(`static/{font,image,media,svg}`) directory.

In the filename, `[name]` is the entry name corresponding to this file, such as `index`, `main`. `[hash]` is the hash value generated based on the content of the file. `[id]` is the internal chunk ID of Rspack.

### Development

In development, an `dist/.rspeedy` directory is emitted which contains the resources for debugging.

```txt
dist/
├── .rspeedy
│   ├── async
│   │   └── [name]
│   │       ├── debug-info.json
│   │       ├── tasm.json
│   │       └── [name].css
│   ├── [name]
│   │   ├── background.js
│   │   ├── background.js.map
│   │   ├── debug-info.json
│   │   ├── [name].css
│   │   ├── main-thread.js
│   │   ├── main-thread.js.map
│   │   └── tasm.json
│   └── rspeedy.config.js
├── [name].lynx.bundle
└── static
    ├── image
    │   ├── [name].[hash].png
    │   └── [name].[hash].svg
    └── js
        ├── [id].[hash].js
        │   └── async
        │       ├── [id].[hash].js
        │       └── [id].[hash].js.map
        ├── lib-preact.[hash].js
        └── lib-preact.[hash].js.map
```

In addition, Rspeedy generates some extra files in development:

- Background Thread Script(BTS): The background script file that is inlined into the bundle, default output to `.rspeedy/[name]/background.js`.
- MainThread Thread Script(MTS): The main-thread script file that is inlined into the bundle, default output to `.rspeedy/[name]/main-thread.js`.
- Source Map files: contains the source code mappings, which is output to the same level directory of JS files and adds a `.map` suffix.

## Modify the Directory

Rspeedy provides some configs to modify the directory or filename, you can:

- Modify the filename through [`output.filename`].
- Modify the output path of through [`output.distPath`].
- Modify the license file through [`output.legalComments`].
- Modify Source Map file through [`output.sourceMap`].

## Flatten the Directory

Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.

See the example below:

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    distPath: {
      js: '',
    },
    filename: {
      bundle: '[name].lynx.bundle',
    },
  },
});
```

The above config produces the following directory structure:

```bash
dist
├── [id].[hash].js
├── [id].[hash].js.map
└── [name].lynx.bundle
```

[`output.filename`]: /api/rspeedy/rspeedy.output.filename.md

[`output.filename.js`]: /api/rspeedy/rspeedy.filename.md

[`output.filename.bundle`]: /api/rspeedy/rspeedy.filename.bundle.md

[`output.distPath`]: /api/rspeedy/rspeedy.output.distpath.md

[`output.distPath.js`]: /api/rspeedy/rspeedy.distpath.md

[`output.legalComments`]: /api/rspeedy/rspeedy.output.legalcomments.md

[`output.sourceMap`]: /api/rspeedy/rspeedy.output.sourcemap.md



---
url: /rspeedy/plugin.md
---

# Plugin

Rsbuild provides a powerful plugin system that allows for user extension.
Rspeedy leverages this plugin system directly.

Plugins written by developers can modify the default behavior of Rspeedy/Rsbuild and add various additional features, including but not limited to:

- Register lifecycle hooks
- Transform module source code
- Modify Rsbuild configuration
- Modify Rspack configuration

## Find Plugins

Before finding plugin, you may want to check if the feature you want is already included in [Rspeedy Configuration](/api/rspeedy/rspeedy.md).

### Rsbuild Plugins

The following Rsbuild plugins can be used in Rspeedy.

- [Sass Plugin](https://rsbuild.dev/plugins/list/plugin-sass): Use Sass as the CSS preprocessor.
- [Less Plugin](https://rsbuild.dev/plugins/list/plugin-less): Use Less as the CSS preprocessor.
- [ESLint Plugin](https://github.com/rspack-contrib/rsbuild-plugin-eslint): Run ESLint checks during the compilation.
- [Type Check Plugin](https://github.com/rspack-contrib/rsbuild-plugin-type-check): Run TypeScript type checker on a separate process.
- [Image Compress Plugin](https://github.com/rspack-contrib/rsbuild-plugin-image-compress): Compress the image assets.
- [Typed CSS Modules Plugin](https://github.com/rspack-contrib/rsbuild-plugin-typed-css-modules): Generate TypeScript declaration file for CSS Modules.
- [Tailwind CSS Plugin](https://github.com/rspack-contrib/rsbuild-plugin-tailwindcss): Integrate with Tailwind CSS V3

### Rspack/Webpack Plugins

The following Rspack/Webpack plugins can be used in Rspeedy.

:::info
Rspack/Webpack plugins should be placed in [`tools.rspack.plugins`].
:::

- [BannerPlugin]: Add a banner to the top or bottom of the output.
- [EnvironmentPlugin]: Use `process.env` with [DefinePlugin].
- [ProvidePlugin]: Automatically load modules instead of having to `import` them everywhere.

## Write Plugins

If none of the existing ecosystem plugins meet your requirements, you might consider writing your own plugin.

### Rsbuild Plugin API

See [Rsbuild - Plugin Hooks](https://rsbuild.dev/plugins/dev/hooks) for more details.

### Rspack Plugin API

See [Rspack - Compiler Hooks](https://rspack.rs/api/plugin-api/compiler-hooks) and [Rspack - Compilation Hooks](https://rspack.rs/api/plugin-api/compilation-hooks) for more details.

[`tools.rspack.plugins`]: /api/rspeedy/rspeedy.tools.rspack.md#example-4

[BannerPlugin]: https://rspack.rs/plugins/webpack/banner-plugin

[DefinePlugin]: https://rspack.rs/plugins/webpack/define-plugin

[EnvironmentPlugin]: https://rspack.rs/plugins/webpack/environment-plugin

[ProvidePlugin]: https://rspack.rs/plugins/webpack/provide-plugin



---
url: /rspeedy/resolve.md
---

# Module Resolution

In modern front-end development, modularity has become a key approach to managing code effectively:

1. **Simplified Module Imports**:
   - Module resolution allows you to use concise and more readable paths for importing modules, instead of cumbersome relative paths. For example, with an alias configuration, you can use `@components/Button` instead of `../../../src/components/Button`, which significantly improves code maintainability.

2. **Environment-Aware Module Substitution**:
   - Module resolution enables you to load different versions of modules based on the environment (e.g., development and production or Lynx and browser). You can easily achieve environment-aware module substitution, ensuring that the most appropriate dependencies are used in different scenarios.

## Path Aliases

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use `import request from '@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

### Using `tsconfig.json`'s `paths` Configuration

You can configure aliases through the `paths` configuration in `tsconfig.json`, which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.

For example:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}
```

After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.

:::tip
You can refer to the [TypeScript - paths](https://typescriptlang.org/tsconfig#paths) documentation for more details.
:::

### Use `source.alias` Configuration

Rsbuild provides the [source.alias](/api/rspeedy/rspeedy.source.alias.md) configuration option, which corresponds to the webpack/Rspack native [resolve.alias](https://rspack.rs/config/resolve#resolvealias) configuration. You can configure this option using an object or a function.

#### Use Cases

The `paths` configuration in `tsconfig.json` is static and lacks dynamism. Furthermore, `paths` only takes effect when the module is included in [`source.include`](/api/rspeedy/rspeedy.source.include.md).

The `source.alias` configuration can overcome this limitation by enabling you to dynamically set `source.alias` using JavaScript code.

For example, use the workspace version of `lodash-es` for all dependencies:

```js title="lynx.config.ts"
import { createRequire } from 'node:module';

import { defineConfig } from '@lynx-js/rspeedy';

const require = createRequire(import.meta.url);

export default defineConfig({
  source: {
    alias: {
      'lodash-es': require.resolve('lodash-es'),
    },
  },
});
```

## Conditional Exports

[NodeJS's conditional exports](https://nodejs.org/api/packages.html#conditional-exports) provide a way to map to different paths depending on certain conditions.

For example, consider an arbitrary library with a `package.json` that contains the following exports:

```json "package.json"
{
  "name": "foo",
  "exports": {
    ".": {
      "lynx": "./index-lynx.js",
      "import": "./index-import.js",
      "require": "./index-require.js"
    },
    "./bar": {
      "import": "./bar-import.js",
      "lynx": "./bar-lynx.js",
      "require": "./bar-require.js"
    }
  }
}
```

Importing:

- `foo` will resolve to `foo/index-lynx.js`
- `foo/bar` will resolve to `foo/bar-import.js`

:::info The key order in the exports field is significant
During condition matching, earlier entries have higher priority and take precedence over later entries.
:::

The default value of `resolve.conditionNames` is:

```js title="rspack.config.js"
export default {
  resolve: {
    conditionNames: ['lynx', 'import', 'require', 'browser'],
  },
};
```

To change the default value, use [`tools.rspack`]:

```js title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  tools: {
    rspack: {
      resolve: {
        conditionNames: ['...', 'foo'],
      },
    },
  },
});
```

## Main Fields

When importing from an npm package, the `mainFields` option will determine which fields in its `package.json` are checked.

For example, consider an arbitrary library with a `package.json` that contains the following fields:

```json title="package.json"
{
  "name": "upstream",
  "lynx": "build/lynx.js",
  "module": "build/index.js"
}
```

When we `import * as Upstream from 'upstream'` this will actually resolve to the file in the `lynx` property. The `lynx` property takes precedence because it's the first item in `mainFields`.

The default value of `resolve.mainFields` is:

```js title="rspack.config.js"
export default {
  resolve: {
    mainFields: ['lynx', 'module', 'main'],
  },
};
```

To change the default value, use [`tools.rspack`]:

```js title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  tools: {
    rspack: {
      resolve: {
        mainFields: ['...', 'foo'],
      },
    },
  },
});
```

## Main Files

If the path to be resolved is an directory, the resolver will try to resolve the `mainFiles` of the directory.

For example, consider an directory with:

```
dir/
├─ sub/
│  ├─ index.js
├─ index.lynx.js
├─ index.js
```

Importing

- `dir/` will resolve to `dir/index.lynx.js`
- `dir/sub` will resolve to `dir/sub/index.js`

The default value of `resolve.mainFiles` is:

```js title="rspack.config.js"
export default {
  resolve: {
    mainFiles: ['index.lynx', 'index'],
  },
};
```

To change the default value, use [`tools.rspack`]:

```js title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  tools: {
    rspack: {
      resolve: {
        mainFiles: ['...', 'foo'],
      },
    },
  },
});
```

[`tools.rspack`]: /api/rspeedy/rspeedy.tools.rspack.md



---
url: /rspeedy/runtime-profiling.md
---

# Runtime Profiling

## Profiling Lynx

Following the instruction of [Record Trace](/guide/devtool/trace/record-trace.md) to profiling Lynx.

## Profiling Framework

You can analyze framework performance in two ways: via build configuration and using the [JS Profile](/guide/devtool/trace/js-profile.md).

### Enabling via Build Configuration

We provide the builtin trace points in frameworks like ReactLynx (Components' `render` and `diff`).

![react profile](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/rspeedy-react-profile.png)

- In development(`rspeedy dev`): ReactLynx-related trace points are _**added**_ by default.
- In production(`rspeedy build`): ReactLynx-related trace points are _**removed**_ by default.

These tracing points show how components are rendered and diffed.

#### Run profiling in production

The trace points can be enabled by setting the [`performance.profile`] to `true` when build.

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  performance: {
    // [!code ++]
    profile: true, // [!code ++]
  }, // [!code ++]
});
```

:::tip
You may use [`rspeedy preview`](/rspeedy/cli.md#rspeedy-preview) to preview the output locally.
:::

This is useful when trying to optimize the performance of the application.

:::warning
Do **NOT** deploy the output with `performance.profile: true`. They are not for production.
:::

#### Disable profiling in development

The trace points can be disabled by setting the [`performance.profile`] to `false` when dev.

```js
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  performance: {
    // [!code ++]
    profile: false, // [!code ++]
  }, // [!code ++]
});
```

### Dynamic Sampling with JS Profile

Use the [JS Profile](/guide/devtool/trace/js-profile.md) tool to collect call stack data at runtime without modifying the build configuration.

[`performance.profile`]: /api/rspeedy/rspeedy.performance.profile.md



---
url: /rspeedy/styling.md
---

# Styling

Rspeedy supports different ways of styling your application, including:

- [**CSS Modules**](#using-css-modules): Create locally scoped CSS classes to avoid naming conflicts and improve maintainability.

- [**Global CSS**](#using-global-css): Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.

- [**CSS pre-processors**](#using-css-pre-processors): Popular CSS pre-processors like [`sass`](https://sass-lang.com/) and [`less`](https://lesscss.org/) that extend CSS with features like variables, nested rules, and mixins.

- [**PostCSS**](#using-postcss): A tool for transforming CSS.

- [**Tailwind CSS**](#using-tailwind-css): A utility-first CSS framework that allows for rapid custom designs by composing utility classes.

## Using CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) allows us to write CSS code in a modular way, and these styles can be imported and used in JavaScript files. Using CSS Modules can automatically generate unique class names, isolate styles between different modules, and avoid class name conflicts.

:::tip
You can use [Global CSS](#using-global-css) if you want some of the CSS to be non-isolated.
:::

Rspeedy supports CSS Modules by default, you don't need to add additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.

### Example

1. Write styles as usual:

```css title=button.module.css
.red {
  background: red;
}
```

2. Use styles like a module:

```jsx title=Button.jsx
import styles from './button.module.css';

export function Button() {
  return (
    <view className={styles.red}>
      <text>Button</text>
    </view>
  );
}
```

Or, you can use **Named Imports**:

```jsx title=Button.jsx
import { red } from './button.module.css';

export function Button() {
  return (
    <view className={red}>
      <text>Button</text>
    </view>
  );
}
```

### With CSS Pre-Processor

The CSS Modules can also be used with [CSS Pre-Processor](#using-css-pre-processors). Just name your files with the pattern `*.module.*`.

E.g.: the following style files are considered CSS Modules:

- `*.module.css`
- `*.module.less`
- `*.module.sass`
- `*.module.scss`
- `*.module.styl` {/* <!-- cspell:disable-line --> */}
- `*.module.stylus`

### Recognition Rules

By default, only files ending with `*.module.{css,scss,less}` are recognized as CSS Modules.

If you want to treat other CSS files as CSS Modules as well, you can achieve this by configuring [output.cssModules.auto](/api/rspeedy/rspeedy.cssmodules.auto.md)
. 
For example:

```js title=lynx.config.ts
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  output: {
    cssModules: {
      auto(filename) {
        return filename.includes('.module.') || filename.includes('/shared/');
      },
    },
  },
});
```

Given this configuration, the following imports will be recognized as CSS Modules:

```js
import * as foo from './foo.module.css';
import * as bar from './shared/bar.css';
```

### Type Declaration

When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the CSS Modules, please create a `src/rspeedy-env.d.ts` file, and add the corresponding type declaration.

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically create this file for you.
:::

If type errors still exist after adding the type declaration, you can try to restart the current IDE. Making sure the TypeScript can correctly identify the type definition.

#### Generate exact type declaration

The `@lynx-js/rspeedy/client` will give type declarations like this:

```ts
declare module '*.module.css' {
  type CSSModuleClasses = {
    readonly [key: string]: string;
  };
  const classes: CSSModuleClasses;
  export default classes;
}
```

Using [Typed CSS Modules Plugin](https://github.com/rspack-contrib/rsbuild-plugin-typed-css-modules) with Rspeedy will generate type declaration files for all CSS Modules with exact type declarations.

1. Install the `@rsbuild/plugin-typed-css-modules` package


```sh [npm]
npm add -D @rsbuild/plugin-typed-css-modules
```

```sh [yarn]
yarn add -D @rsbuild/plugin-typed-css-modules
```

```sh [pnpm]
pnpm add -D @rsbuild/plugin-typed-css-modules
```

```sh [bun]
bun add -D @rsbuild/plugin-typed-css-modules
```

```sh [deno]
deno add -D npm:@rsbuild/plugin-typed-css-modules
```

2. Add the `pluginTypedCSSModules` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginTypedCSSModules } from '@rsbuild/plugin-typed-css-modules';

import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [pluginReactLynx(), pluginTypedCSSModules()],
});
```

After running `rspeedy build` or `rspeedy dev`, the type declarations will be generated.

```ts title=button.module.css.d.ts
// This file is automatically generated.
// Please do not change this file!
interface CssExports {
  red: string;
}
export const cssExports: CssExports;
export default cssExports;
```

You may also need to add [`"allowArbitraryExtensions": true`](https://www.typescriptlang.org/tsconfig/#allowArbitraryExtensions) and [`"moduleResolution": "Bundler"`](https://www.typescriptlang.org/tsconfig/#moduleResolution) to `tsconfig.json`.

```json title=tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowArbitraryExtensions": true
  }
}
```

## Using Global CSS

In some case, you may want the CSS styles to be used with some complex selector. It is called Global CSS in ReactLynx.

Just write CSS code and imported from a javascript file.

### Example

1. Write styles as usual:

```css title=styles.css
.red {
  background: red;
}

.red > text {
  color: blue;
}
```

2. Import the `.css` file from the JSX file and use the CSS classes:

```jsx title=index.jsx
import './styles.css';

export default function App() {
  return (
    <view className="red">
      <text>Hello, Rspeedy!</text>
    </view>
  );
}
```

## Using CSS Pre-Processors

CSS pre-processors extend CSS with features like variables, nested rules, and mixins.

### Using `sass`

1. Install the `@rsbuild/plugin-sass` package


```sh [npm]
npm install -D @rsbuild/plugin-sass
```

```sh [yarn]
yarn add -D @rsbuild/plugin-sass
```

```sh [pnpm]
pnpm add -D @rsbuild/plugin-sass
```

```sh [bun]
bun add -D @rsbuild/plugin-sass
```

```sh [deno]
deno add -D npm:@rsbuild/plugin-sass
```

2. Add the `pluginSass` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginSass } from '@rsbuild/plugin-sass';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginSass({
      /** sass options */
    }),
  ],
});
```

Then simply create `.scss` or `.sass` files and import them into JavaScript.

```jsx
import './global.sass';
import styles from './button.module.scss';

export function App() {
  return (
    <view className={styles.red}>
      <text className="title">Hello, Sass</text>
    </view>
  );
}
```

More options can be used in `pluginSass`, please refer to [Sass Plugin](https://rsbuild.dev/plugins/list/plugin-sass) for usage.

### Using `less`

1. Install the `@rsbuild/plugin-less` package


```sh [npm]
npm install -D @rsbuild/plugin-less
```

```sh [yarn]
yarn add -D @rsbuild/plugin-less
```

```sh [pnpm]
pnpm add -D @rsbuild/plugin-less
```

```sh [bun]
bun add -D @rsbuild/plugin-less
```

```sh [deno]
deno add -D npm:@rsbuild/plugin-less
```

2. Add the `pluginLess` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginLess } from '@rsbuild/plugin-less';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginLess({
      /** less options */
    }),
  ],
});
```

Then simply create `.less` files and import them into JavaScript.

```jsx
import './global.less';
import styles from './button.module.less';

export function App() {
  return (
    <view className={styles.red}>
      <text className="title">Hello, Less</text>
    </view>
  );
}
```

More options can be used in `pluginLess`, please refer to [Less Plugin](https://rsbuild.dev/plugins/list/plugin-less) for usage.

### Using `stylus`

1. Install the `@rsbuild/plugin-stylus` package


```sh [npm]
npm install -D @rsbuild/plugin-stylus
```

```sh [yarn]
yarn add -D @rsbuild/plugin-stylus
```

```sh [pnpm]
pnpm add -D @rsbuild/plugin-stylus
```

```sh [bun]
bun add -D @rsbuild/plugin-stylus
```

```sh [deno]
deno add -D npm:@rsbuild/plugin-stylus
```

2. Add the `pluginStylus` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginStylus } from '@rsbuild/plugin-stylus';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/index.tsx',
  },
  plugins: [
    pluginStylus({
      /** stylus options */
    }),
  ],
});
```

More options can be used in `pluginStylus`, please refer to [Stylus Plugin](https://rsbuild.dev/plugins/list/plugin-stylus) for usage.

## Using PostCSS

Powered by Rsbuild, Rspeedy has built-in [PostCSS](https://postcss.org/) to transform the CSS code.

Rsbuild uses [postcss-load-config](https://github.com/postcss/postcss-load-config) to load the PostCSS configuration file in the root directory of the current project, such as `postcss.config.js`:

```js
export default {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};
```

## Using Tailwind CSS

:::tip Tailwind CSS v3
Lynx currently requires **Tailwind CSS v3**. Install `tailwindcss@^3` and use it as the PostCSS plugin. Note that v4 packages such as `@tailwindcss/postcss`, `@tailwindcss/vite`, and `@tailwindcss/cli` are incompatible with `@lynx-js/tailwind-preset`.
:::

1. Installing Tailwind CSS

   Rspeedy has built-in support for PostCSS, you can install tailwindcss package to integrate Tailwind CSS:

   <PackageManagerTabs command="install -D tailwindcss@^3" />

2. Configuring PostCSS

   You can register the tailwindcss PostCSS plugin through [`postcss.config.js`](https://www.npmjs.com/package/postcss-loader#config) or [`tools.postcss`](https://rsbuild.rs/config/tools/postcss).

   ```js title=postcss.config.js
   export default {
     plugins: {
       tailwindcss: {},
     },
   };
   ```

3. Installing the `@lynx-js/tailwind-preset` package:

   <PackageManagerTabs command="install -D @lynx-js/tailwind-preset" />

4. Configuring `tailwind.config.js` and adding `@lynx-js/tailwind-preset`:

   You must use [`@lynx-js/tailwind-preset`](https://github.com/lynx-family/lynx-stack/tree/main/packages/third-party/tailwind-preset) to remove all the tailwindcss utilities not supported in Lynx or adapt to Lynx-specific alternatives.

   ```js title=tailwind.config.js
   import lynxPreset from '@lynx-js/tailwind-preset';

   export default {
     content: ['./src/**/*.{js,ts,jsx,tsx}'],
     presets: [lynxPreset],
   };
   ```

   :::warning

   `@lynx-js/tailwind-preset` is still not stable, please use it with caution. If you found any tailwindcss features that are not working and should be supported, please open an issue at [https://github.com/lynx-family/lynx-stack/issues](https://github.com/lynx-family/lynx-stack/issues).

   :::

### Example

**This is an example below: tailwindcss**

**Entry:** `src`
**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useEffect } from "@lynx-js/react";

import "./App.css";

export function App() {
  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  return (
    <page>
      <view className="flex flex-col justify-center items-center min-h-screen text-center">
        <text className="text-6xl font-bold leading-normal underline">
          ReactLynx + TailwindCSS
        </text>
        <text className="text-lg font-normal text-gray-500 leading-normal">
          Start building amazing things with ReactLynx.
        </text>
        <view
          className="flex flex-row p-20 rounded-full"
          style={{
            backgroundColor: "rgba(255, 255, 255, 0.5)",
            padding: "40px",
            margin: "10px",
          }}
        >
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 translate-x-6"
            style={{
              marginRight: "40px",
            }}
          />
          {/* static should not be supported */}
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 rotate-45 static"
            style={{
              marginRight: "40px",
            }}
          />
          {/* static should be supported */}
          <image
            src="https://images.unsplash.com/photo-1554629947-334ff61d85dc?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=320&h=320&q=80"
            className="mt-8 rounded-full w-16 h-16 scale-150 sticky"
            style={{
              marginRight: "40px",
            }}
          />
        </view>
        <view className="grid grid-cols-3 gap-4">
          <text>01</text>
          <text>02</text>
          <text>03</text>
          <text>04</text>
          <text>05</text>
          <text>06</text>
        </view>
      </view>
    </page>
  );
}

```





---
url: /rspeedy/typescript.md
---

# TypeScript

Powered by Rsbuild, Rspeedy supports TypeScript by default, allowing you to directly use `.ts` and `.tsx` files in your projects.

## Path Alias

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use import request from `'@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

The [`paths`](https://www.typescriptlang.org/tsconfig/#paths) option of TypeScript is recommended to be used to make path aliases.

```json title=tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}
```

After configuring, if you reference `@common/request.ts` in your code, it will be mapped to the `<project>/src/common/request.ts` path.

<!-- eslint-disable-next-line import/no-unresolved -->

```js
import { get } from '@common/request.js'; // The same as './common/request.js'
```

## Custom `tsconfig.json` Path

Rspeedy by default reads the `tsconfig.json` file from the root directory. You can use the [source.tsconfigPath](/api/rspeedy/rspeedy.source.tsconfigpath.md) to configure a custom tsconfig.json file path.

```ts
export default {
  source: {
    tsconfigPath: './tsconfig.custom.json',
  },
};
```

## Rspeedy type declaration

Rspeedy provide various built-in features like CSS Modules and [Static Assets](/rspeedy/assets.md). TypeScript does not know about these features and the corresponding type declarations.

To solve this, create a `src/rspeedy-env.d.ts` file, and add the following content:

```typescript title=src/rspeedy-env.d.ts
/// <reference types="@lynx-js/rspeedy/client" />
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically create this file for you.
:::

## Extending Lynx types

Lynx provides default types, but you may need to extend or customize certain type definitions for your application.

- [`GlobalProps`](#globalprops): extends the type definition for `lynx.__globalProps`
- [`InitData`](#initdata): extends the return type of [`useInitData()`](/api/react/Function.useInitData.md)
- [`IntrinsicElements`](#intrinsicelements): extends the type definition for elements (e.g: you may have your own `<input>` element)
- [`NativeModules`](#nativemodules): extends the type definition for [custom native modules](/guide/use-native-modules.md).

### GlobalProps

You can extend the `interface GlobalProps` from `@lynx-js/types` to add custom properties:

```ts title="src/global-props.d.ts"
declare module '@lynx-js/types' {
  interface GlobalProps {
    foo: string;
    bar: number;
  }
}

export {}; // This export makes the file a module
```

After this extension, TypeScript will recognize and provide type checking for `lynx.__globalProps.foo` and `lynx.__globalProps.bar`.

### InitData

You can extend the `interface InitData` from `@lynx-js/react` to add your custom data properties:

```ts title="src/init-data.d.ts"
declare module '@lynx-js/react' {
  interface InitData {
    foo: string;
    bar: number;
  }
}

export {}; // This export makes the file a module
```

With this extension, TypeScript will provide type checking for `useInitData().foo` and `useInitData().bar` in your components.

### IntrinsicElements

You can extends the `interface IntrinsicElements` from `@lynx-js/types` to add your [custom native element](/guide/custom-native-component.md)

Here is an example for a `<input>` element with required `type` and optional `bindinput` and `value`.

```ts title="src/intrinsic-element.d.ts"
import * as Lynx from '@lynx-js/types';

declare module '@lynx-js/types' {
  interface IntrinsicElements extends Lynx.IntrinsicElements {
    input: {
      bindinput?: (e: { type: 'input'; detail: { value: string } }) => void;
      type: string;
      value?: string | undefined;
    };
  }
}
```

### NativeModules

You can extend the `interface NativeModules` from `@lynx-js/types` to add custom [native modules](/guide/use-native-modules.md):

Here is an example for a `NativeLocalStorageModule` with 3 methods:

```ts title="src/native-modules.d.ts"
declare module '@lynx-js/types' {
  interface NativeModules {
    NativeLocalStorageModule: {
      clearStorage(): void;
      getStorageItem(key: string): string | null;
      setStorageItem(key: string, value: string): void;
    };
  }
}

export {}; // This export makes the file a module
```

## TypeScript Transpilation

Rsbuild uses SWC for transforming TypeScript code.

### isolatedModules

Unlike the native TypeScript compiler, tools like SWC and Babel compile each file separately and cannot determine whether an imported name is a type or a value. Therefore, when using TypeScript in Rspeedy, you need to enable the [isolatedModules](https://typescriptlang.org/tsconfig/#isolatedModules) option in your `tsconfig.json` file:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "isolatedModules": true // [!code focus]
  }
}
```

:::tip
[`create-rspeedy`](https://npmjs.com/create-rspeedy) will automatically include this for you.
:::

This option can help you avoid using certain syntax that cannot be correctly compiled by SWC and Babel, such as cross-file type references. It will guide you to correct the corresponding usage:

<!-- eslint-disable import/no-unresolved, import/export -->

```ts
// ❌ Wrong
export { SomeType } from './types.js';

// ✅ Correct
export type { SomeType } from './types.js';

// ✅ Correct
export { type SomeType } from './types.js';
```

## Type Checking

Type checking is not performed.

Rsbuild provides the [Type Check plugin](https://rsbuild.rs/guide/basic/typescript#type-checking), which runs TypeScript type checking in a separate process. The plugin internally integrates [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin).

1. Install the `@rsbuild/plugin-type-check` package

```bash
pnpm add -D @rsbuild/plugin-type-check
```

2. Add `@rsbuild/plugin-type-check` to `lynx.config.ts`

```js title=lynx.config.ts
import { pluginTypeCheck } from '@rsbuild/plugin-type-check';

import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  plugins: [
    pluginTypeCheck({
      enable: true,
    }),
  ],
});
```

Please refer to the [Type Check plugin](https://rsbuild.rs/guide/basic/typescript#type-checking) for more available options.



---
url: /rspeedy/upgrade.md
---

# Upgrade Rspeedy

This section explains how to upgrade the project's Rspeedy-related dependencies.

## Use `upgrade-rspeedy`

The Rspeedy project includes several NPM packages with `peerDependencies` constraints. Unmatched `peerDependencies` can lead to compilation and runtime errors.

We recommend using the [`upgrade-rspeedy`](https://npmjs.org/package/upgrade-rspeedy) tool to upgrade the Rspeedy version.

:::info
The `upgrade-rspeedy` command will not install dependencies for you.

Please remember to install the dependencies with your package manager.
:::

### Upgrade to the `latest` version (recommended)

To upgrade `@lynx-js/rspeedy` and its plugins to the latest version, use the following command in your project:


```sh [npx]
npx upgrade-rspeedy@latest
```

```sh [pnpm]
pnpm dlx upgrade-rspeedy@latest
```

```sh [bunx]
bunx upgrade-rspeedy@latest
```

```sh [yarn]
yarn dlx upgrade-rspeedy@latest
```

> For better performance when using **pnpm** in a monolithic repository, use **pnpm dlx** instead of **npx**.

### Upgrade to a specific version

To upgrade `@lynx-js/rspeedy` and its plugins to a specific version, use the following command in your project:


```sh [npx]
npx upgrade-rspeedy@0.8.3
```

```sh [pnpm]
pnpm dlx upgrade-rspeedy@0.8.3
```

```sh [bunx]
bunx upgrade-rspeedy@0.8.3
```

```sh [yarn]
yarn dlx upgrade-rspeedy@0.8.3
```

Replace the `0.8.3` with the one you would like to install.

### Upgrade to a canary version

:::warning
Please note that the canary version of Rspeedy is released solely for testing purposes.

**IMPORTANT:** Do not use canary versions in production environments.
:::

To upgrade `@lynx-js/rspeedy` and its plugins to a canary version before release, use the following command:

```bash
# Replace the `0.8.2-canary-20250309-870106fc` with your canary version.
pnpm dlx upgrade-rspeedy-canary@0.8.2-canary-20250309-870106fc
```



---
url: /rspeedy/use-rsdoctor.md
---

# Use Rsdoctor

[Rsdoctor](https://rsdoctor.dev/) is a build analyzer that can visually display the build process, such as compilation time, code changes before and after compilation, module reference relationships, duplicate modules, etc.

If you need to debug the build outputs or build process, you can use Rsdoctor for troubleshooting.

- Rsdoctor is a one-stop tool for diagnosing and analyzing the build process and build artifacts.
- Rsdoctor is a tool that supports Webpack and Rspack build analysis.
- Rsdoctor is an analysis tool that can display the time-consuming and behavioral details of the compilation.
- Rsdoctor is a tool that can analyze the time-consuming and compilation process of the rspack builtin:swc-loader.

## 🔥 Features

- **Compilation Visualization**: Rsdoctor visualizes the compilation behavior and time consumption, making it easy to view build issues.

- **Multiple Analysis Capabilities**: Rsdoctor supports build artifact, build-time analysis, and anti-degradation capabilities:
  - Build artifact support for resource lists and module dependencies, etc.
  - Build-time analysis supports Loader, Plugin, and Resolver building process analysis, including: **Rspack's builtin:swc-loader**.
  - Build rules support duplicate package detection and ES Version Check, etc.

- **Support Custom Rules**: In addition to built-in build scan rules, Rsdoctor also supports users adding custom component scan rules based on the build data of Rsdoctor.

## Quick Start

In an Rspeedy-based project, you can enable Rsdoctor as follows:

```bash
# dev
RSDOCTOR=true rspeedy dev

# build
RSDOCTOR=true rspeedy build
```

After running the above commands, Rspeedy will automatically register the Rsdoctor plugin, and after the build is completed, it will open the build analysis page. For complete features, please refer to [Rsdoctor document](https://rsdoctor.dev/).

## Options

If you need to configure the [options](https://rsdoctor.dev/config/options/options#options) provided by the Rsdoctor plugin, use [`tools.rsdoctor`](/api/rspeedy/rspeedy.tools.rsdoctor.md).

```ts title="lynx.config.ts"
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  tools: {
    rsdoctor: {
      disableClientServer: true,
    },
  },
});
```

## Use custom Rsdoctor version

1. Install the Rsdoctor plugin:


```sh [npm]
npm add @rsdoctor/rspack-plugin -D
```

```sh [yarn]
yarn add @rsdoctor/rspack-plugin -D
```

```sh [pnpm]
pnpm add @rsdoctor/rspack-plugin -D
```

```sh [bun]
bun add @rsdoctor/rspack-plugin -D
```

```sh [deno]
deno add npm:@rsdoctor/rspack-plugin -D
```

2. Add the `RsdoctorRspackPlugin` to `lynx.config.ts`

:::danger

- Rsdoctor should not be used in production versions.
- In Rspeedy, the `supports.banner` configuration item needs to be opened.

:::

```ts title="lynx.config.ts"
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

export default {
  tools: {
    rspack(config, { appendPlugins }) {
      if (process.env.RSDOCTOR === 'true') {
        appendPlugins(
          new RsdoctorRspackPlugin({
            // plugin options
            supports: { banner: true },
          }),
        );
      }
    },
  },
};
```

Please note that `tools.rsdoctor` has no effect when using a custom version of Rsdoctor.



---
url: /versions.md
---

# Lynx versions

In 2025, Lynx plan to publish 5 stable releases. You can find Lynx [release schedule](/blog/lynx-open-source-roadmap-2025.md) here.

## Next version (unreleased)

Developers can check out the new features currently in development in this release.

| Version Number | release | docs repo branch | docs link | release blog |
| --- | --- | --- | --- | --- |
| next | --- | [main](https://github.com/lynx-family/lynx-website/tree/main) | [https://lynxjs.org/next](https://lynxjs.org/next) | --- |


## Latest version

It is recommended that new applications using Lynx adopt the latest version.

| Version Number | release | docs repo branch | docs link | release blog |
| --- | --- | --- | --- | --- |
| 3.8 | --- | [release/3.8](https://github.com/lynx-family/lynx-website/tree/release/3.8) | [https://lynxjs.org/](https://lynxjs.org/) | --- |


## Previous versions

| Version Number | release | docs repo branch | docs link | release blog |
| --- | --- | --- | --- | --- |
| 3.7 | --- | [release/3.7](https://github.com/lynx-family/lynx-website/tree/release/3.7) | [https://lynxjs.org/3.7](https://lynxjs.org/3.7) | --- |
| 3.6 | --- | [release/3.6](https://github.com/lynx-family/lynx-website/tree/release/3.6) | [https://lynxjs.org/3.6](https://lynxjs.org/3.6) | --- |
| 3.5 | [3.5.2](https://github.com/lynx-family/lynx/releases/tag/3.5.2) | [release/3.5](https://github.com/lynx-family/lynx-website/tree/release/3.5) | [https://lynxjs.org/3.5](https://lynxjs.org/3.5) | [blog](https://lynxjs.org//3.5/blog/lynx-3-5.html) |
| 3.4 | [3.4.2](https://github.com/lynx-family/lynx/releases/tag/3.4.2) | [release/3.4](https://github.com/lynx-family/lynx-website/tree/release/3.4) | [https://lynxjs.org/3.4](https://lynxjs.org/3.4) | [blog](https://lynxjs.org//3.4/blog/lynx-3-4.html) |
| 3.3 | [3.3.2](https://github.com/lynx-family/lynx/releases/tag/3.3.2) | --- | --- | --- |
| 3.2 | [3.2.0](https://github.com/lynx-family/lynx/releases/tag/3.2.0) | --- | --- | [blog](https://lynxjs.org//3.2/blog/lynx-3-2.html) |




---
url: /ai/start/quick-start.md
---

# Try with Explorer

Try with ExplorerRun Lynx pages in the pre-built sandbox app[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use [Lynx Explorer](https://github.com/lynx-family/lynx), a pre-built sandbox app, to start developing and previewing Lynx pages instantly, no native toolchain required. Great for learning, prototyping, and development. For production deployment, [integrate with your existing app](/guide/start/integrate-with-existing-apps.md) or [build a new app on an app framework](/guide/start/build-with-app-framework.md).

### System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

### Create a new Lynx project
We use Rspeedy (a Rspack-based Lynx build tool) to build Lynx projects.
It is recommended to start a new project using [`create-rspeedy`](https://npmjs.org/package/create-rspeedy),
which sets up everything automatically for you. To create a project, run:

```sh [npm]
npm create rspeedy@latest
```

```sh [yarn]
yarn create rspeedy
```

```sh [pnpm]
pnpm create rspeedy@latest
```

```sh [bun]
bun create rspeedy@latest
```

```sh [deno]
deno init --npm rspeedy@latest
```
After completing the prompts, `create-rspeedy` will create a folder with your project name.
### Prepare Lynx Explorer
Lynx Explorer is a sandbox for trying out Lynx quickly.
iOS SimulatorAndroidHarmonyOSWe currently only provide pre-built binaries for the iOS simulator. If you need to run Lynx Explorer on a real iOS device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide.
:::info
A version of Lynx Explorer is also available on the [App Store](https://apps.apple.com/us/app/lynx-go-dev-explorer/id6743227790), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on iOS.
:::
1. **Install Xcode**
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click Install (or Update if you have it already).
2. **<div id="download-lynx-explorer,ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator">Download LynxExplorer</div>**
macOS (arm64)macOS (x86_64)Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-arm64.app.tar.gz).
Then extract the downloaded archive:
```bash
mkdir -p LynxExplorer-arm64.app/
tar -zxf LynxExplorer-arm64.app.tar.gz -C LynxExplorer-arm64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-arm64.app" into it.
Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-x86_64.app.tar.gz).
Then, extract the downloaded archive:
```bash
mkdir -p LynxExplorer-x86_64.app/
tar -zxf LynxExplorer-x86_64.app.tar.gz -C LynxExplorer-x86_64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-x86\_64.app" into it.
## 

Scan the QR code to download the pre-built app from [GitHub Release 3.7.0](https://github.com/lynx-family/lynx/releases/tag/3.7.0).
Or, you may build from source by following the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide.
:::info
A version of Lynx Explorer is also available on the [Play Store](https://play.google.com/store/apps/details?id=com.funcs.io.lynx.go), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on Android.
:::
We currently only provide pre-built binaries for the harmony simulator. If you need to run Lynx Explorer on a real harmony device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
1. **Install DevEco Studio**
Download the latest DevEco Studio from the [official website](https://developer.huawei.com/consumer/en/deveco-studio/).
2. **<div id="download-lynx-explorer">Download Lynx Explorer</div>**
Download the pre-built app [`lynx_explorer-default-unsigned.hap`](https://github.com/lynx-family/lynx/releases/download/3.7.0/lynx_explorer-default-unsigned.hap).
Or, you may build from source by following the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
3. **Install Lynx Explorer on Simulator**
```bash
hdc install lynx_explorer-default-unsigned.hap
```
### Start developing
1. Navigate to the created project:
```bash
cd <project-name>
```
2. Install the NPM dependencies with package manager:

```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```
3. To start the development server, run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You will see a QR code showing up in the terminal, scan with your Lynx Explorer App or if you are using the simulator, just copy the bundle URL and paste it on the "Enter Card URL" input in the Lynx Explorer App and hit "Go".
4. Make your first change
Open the `src/App.tsx` file in your code editor and make a change.
You should see the UI on your Lynx Explorer being updated automatically.
**This is an example below: hello-world**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useEffect, useState } from "@lynx-js/react";

import "./App.css";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

export function App() {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
}

```



### Debugging
Visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to download and open the Lynx DevTool desktop application. Use a USB cable to connect the debugging device, and start debugging.
Visit [Debugging](/guide/devtool/panels.md), learn how to debug your Lynx app.

## Next Steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

[Tutorial

Step-by-step walkthrough of building a Gallery page with Lynx

](/learn/gallery)[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)
### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)


---
url: /rspeedy/start/quick-start.md
---

# Try with Explorer

Try with ExplorerRun Lynx pages in the pre-built sandbox app[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use [Lynx Explorer](https://github.com/lynx-family/lynx), a pre-built sandbox app, to start developing and previewing Lynx pages instantly, no native toolchain required. Great for learning, prototyping, and development. For production deployment, [integrate with your existing app](/guide/start/integrate-with-existing-apps.md) or [build a new app on an app framework](/guide/start/build-with-app-framework.md).

### System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

### Create a new Lynx project
We use Rspeedy (a Rspack-based Lynx build tool) to build Lynx projects.
It is recommended to start a new project using [`create-rspeedy`](https://npmjs.org/package/create-rspeedy),
which sets up everything automatically for you. To create a project, run:

```sh [npm]
npm create rspeedy@latest
```

```sh [yarn]
yarn create rspeedy
```

```sh [pnpm]
pnpm create rspeedy@latest
```

```sh [bun]
bun create rspeedy@latest
```

```sh [deno]
deno init --npm rspeedy@latest
```
After completing the prompts, `create-rspeedy` will create a folder with your project name.
### Prepare Lynx Explorer
Lynx Explorer is a sandbox for trying out Lynx quickly.
iOS SimulatorAndroidHarmonyOSWe currently only provide pre-built binaries for the iOS simulator. If you need to run Lynx Explorer on a real iOS device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide.
:::info
A version of Lynx Explorer is also available on the [App Store](https://apps.apple.com/us/app/lynx-go-dev-explorer/id6743227790), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on iOS.
:::
1. **Install Xcode**
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click Install (or Update if you have it already).
2. **<div id="download-lynx-explorer,ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator">Download LynxExplorer</div>**
macOS (arm64)macOS (x86_64)Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-arm64.app.tar.gz).
Then extract the downloaded archive:
```bash
mkdir -p LynxExplorer-arm64.app/
tar -zxf LynxExplorer-arm64.app.tar.gz -C LynxExplorer-arm64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-arm64.app" into it.
Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-x86_64.app.tar.gz).
Then, extract the downloaded archive:
```bash
mkdir -p LynxExplorer-x86_64.app/
tar -zxf LynxExplorer-x86_64.app.tar.gz -C LynxExplorer-x86_64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-x86\_64.app" into it.
## 

Scan the QR code to download the pre-built app from [GitHub Release 3.7.0](https://github.com/lynx-family/lynx/releases/tag/3.7.0).
Or, you may build from source by following the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide.
:::info
A version of Lynx Explorer is also available on the [Play Store](https://play.google.com/store/apps/details?id=com.funcs.io.lynx.go), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on Android.
:::
We currently only provide pre-built binaries for the harmony simulator. If you need to run Lynx Explorer on a real harmony device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
1. **Install DevEco Studio**
Download the latest DevEco Studio from the [official website](https://developer.huawei.com/consumer/en/deveco-studio/).
2. **<div id="download-lynx-explorer">Download Lynx Explorer</div>**
Download the pre-built app [`lynx_explorer-default-unsigned.hap`](https://github.com/lynx-family/lynx/releases/download/3.7.0/lynx_explorer-default-unsigned.hap).
Or, you may build from source by following the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
3. **Install Lynx Explorer on Simulator**
```bash
hdc install lynx_explorer-default-unsigned.hap
```
### Start developing
1. Navigate to the created project:
```bash
cd <project-name>
```
2. Install the NPM dependencies with package manager:

```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```
3. To start the development server, run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You will see a QR code showing up in the terminal, scan with your Lynx Explorer App or if you are using the simulator, just copy the bundle URL and paste it on the "Enter Card URL" input in the Lynx Explorer App and hit "Go".
4. Make your first change
Open the `src/App.tsx` file in your code editor and make a change.
You should see the UI on your Lynx Explorer being updated automatically.
**This is an example below: hello-world**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useEffect, useState } from "@lynx-js/react";

import "./App.css";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

export function App() {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
}

```



### Debugging
Visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to download and open the Lynx DevTool desktop application. Use a USB cable to connect the debugging device, and start debugging.
Visit [Debugging](/guide/devtool/panels.md), learn how to debug your Lynx app.

## Next Steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

[Tutorial

Step-by-step walkthrough of building a Gallery page with Lynx

](/learn/gallery)[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)
### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)


---
url: /react/start/quick-start.md
---

# Try with Explorer

Try with ExplorerRun Lynx pages in the pre-built sandbox app[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use [Lynx Explorer](https://github.com/lynx-family/lynx), a pre-built sandbox app, to start developing and previewing Lynx pages instantly, no native toolchain required. Great for learning, prototyping, and development. For production deployment, [integrate with your existing app](/guide/start/integrate-with-existing-apps.md) or [build a new app on an app framework](/guide/start/build-with-app-framework.md).

### System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

### Create a new Lynx project
We use Rspeedy (a Rspack-based Lynx build tool) to build Lynx projects.
It is recommended to start a new project using [`create-rspeedy`](https://npmjs.org/package/create-rspeedy),
which sets up everything automatically for you. To create a project, run:

```sh [npm]
npm create rspeedy@latest
```

```sh [yarn]
yarn create rspeedy
```

```sh [pnpm]
pnpm create rspeedy@latest
```

```sh [bun]
bun create rspeedy@latest
```

```sh [deno]
deno init --npm rspeedy@latest
```
After completing the prompts, `create-rspeedy` will create a folder with your project name.
### Prepare Lynx Explorer
Lynx Explorer is a sandbox for trying out Lynx quickly.
iOS SimulatorAndroidHarmonyOSWe currently only provide pre-built binaries for the iOS simulator. If you need to run Lynx Explorer on a real iOS device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide.
:::info
A version of Lynx Explorer is also available on the [App Store](https://apps.apple.com/us/app/lynx-go-dev-explorer/id6743227790), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on iOS.
:::
1. **Install Xcode**
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click Install (or Update if you have it already).
2. **<div id="download-lynx-explorer,ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator">Download LynxExplorer</div>**
macOS (arm64)macOS (x86_64)Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-arm64.app.tar.gz).
Then extract the downloaded archive:
```bash
mkdir -p LynxExplorer-arm64.app/
tar -zxf LynxExplorer-arm64.app.tar.gz -C LynxExplorer-arm64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-arm64.app" into it.
Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-x86_64.app.tar.gz).
Then, extract the downloaded archive:
```bash
mkdir -p LynxExplorer-x86_64.app/
tar -zxf LynxExplorer-x86_64.app.tar.gz -C LynxExplorer-x86_64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-x86\_64.app" into it.
## 

Scan the QR code to download the pre-built app from [GitHub Release 3.7.0](https://github.com/lynx-family/lynx/releases/tag/3.7.0).
Or, you may build from source by following the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide.
:::info
A version of Lynx Explorer is also available on the [Play Store](https://play.google.com/store/apps/details?id=com.funcs.io.lynx.go), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on Android.
:::
We currently only provide pre-built binaries for the harmony simulator. If you need to run Lynx Explorer on a real harmony device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
1. **Install DevEco Studio**
Download the latest DevEco Studio from the [official website](https://developer.huawei.com/consumer/en/deveco-studio/).
2. **<div id="download-lynx-explorer">Download Lynx Explorer</div>**
Download the pre-built app [`lynx_explorer-default-unsigned.hap`](https://github.com/lynx-family/lynx/releases/download/3.7.0/lynx_explorer-default-unsigned.hap).
Or, you may build from source by following the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
3. **Install Lynx Explorer on Simulator**
```bash
hdc install lynx_explorer-default-unsigned.hap
```
### Start developing
1. Navigate to the created project:
```bash
cd <project-name>
```
2. Install the NPM dependencies with package manager:

```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```
3. To start the development server, run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You will see a QR code showing up in the terminal, scan with your Lynx Explorer App or if you are using the simulator, just copy the bundle URL and paste it on the "Enter Card URL" input in the Lynx Explorer App and hit "Go".
4. Make your first change
Open the `src/App.tsx` file in your code editor and make a change.
You should see the UI on your Lynx Explorer being updated automatically.
**This is an example below: hello-world**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useEffect, useState } from "@lynx-js/react";

import "./App.css";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

export function App() {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
}

```



### Debugging
Visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to download and open the Lynx DevTool desktop application. Use a USB cable to connect the debugging device, and start debugging.
Visit [Debugging](/guide/devtool/panels.md), learn how to debug your Lynx app.

## Next Steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

[Tutorial

Step-by-step walkthrough of building a Gallery page with Lynx

](/learn/gallery)[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)
### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)


---
url: /lynx-ui/start/quick-start.md
---

# Try with Explorer

Try with ExplorerRun Lynx pages in the pre-built sandbox app[Integrate with Existing AppsUse Lynx as a UI building block in your native or web app](/guide/start/integrate-with-existing-apps)[Build with an App FrameworkBuild a new mobile or desktop app on a Lynx-based framework|](/guide/start/build-with-app-framework)
Use [Lynx Explorer](https://github.com/lynx-family/lynx), a pre-built sandbox app, to start developing and previewing Lynx pages instantly, no native toolchain required. Great for learning, prototyping, and development. For production deployment, [integrate with your existing app](/guide/start/integrate-with-existing-apps.md) or [build a new app on an app framework](/guide/start/build-with-app-framework.md).

### System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

### Create a new Lynx project
We use Rspeedy (a Rspack-based Lynx build tool) to build Lynx projects.
It is recommended to start a new project using [`create-rspeedy`](https://npmjs.org/package/create-rspeedy),
which sets up everything automatically for you. To create a project, run:

```sh [npm]
npm create rspeedy@latest
```

```sh [yarn]
yarn create rspeedy
```

```sh [pnpm]
pnpm create rspeedy@latest
```

```sh [bun]
bun create rspeedy@latest
```

```sh [deno]
deno init --npm rspeedy@latest
```
After completing the prompts, `create-rspeedy` will create a folder with your project name.
### Prepare Lynx Explorer
Lynx Explorer is a sandbox for trying out Lynx quickly.
iOS SimulatorAndroidHarmonyOSWe currently only provide pre-built binaries for the iOS simulator. If you need to run Lynx Explorer on a real iOS device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for iOS](https://github.com/lynx-family/lynx/tree/develop/explorer/darwin/ios) guide.
:::info
A version of Lynx Explorer is also available on the [App Store](https://apps.apple.com/us/app/lynx-go-dev-explorer/id6743227790), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on iOS.
:::
1. **Install Xcode**
Open up the Mac App Store, search for [Xcode](https://apps.apple.com/us/app/xcode/id497799835), and click Install (or Update if you have it already).
2. **<div id="download-lynx-explorer,ios-simulator-platform=macos-arm64,explorer-platform=ios-simulator">Download LynxExplorer</div>**
macOS (arm64)macOS (x86_64)Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-arm64.app.tar.gz).
Then extract the downloaded archive:
```bash
mkdir -p LynxExplorer-arm64.app/
tar -zxf LynxExplorer-arm64.app.tar.gz -C LynxExplorer-arm64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-arm64.app" into it.
Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/download/3.7.0/LynxExplorer-x86_64.app.tar.gz).
Then, extract the downloaded archive:
```bash
mkdir -p LynxExplorer-x86_64.app/
tar -zxf LynxExplorer-x86_64.app.tar.gz -C LynxExplorer-x86_64.app/
```
3. **Install LynxExplorer on Simulator**
Open Xcode, choose **Open Developer Tool** from the Xcode menu. Click the **Simulator** to launch a simulator. Drag "LynxExplorer-x86\_64.app" into it.
## 

Scan the QR code to download the pre-built app from [GitHub Release 3.7.0](https://github.com/lynx-family/lynx/releases/tag/3.7.0).
Or, you may build from source by following the [Build Lynx Explorer for Android](https://github.com/lynx-family/lynx/tree/develop/explorer/android) guide.
:::info
A version of Lynx Explorer is also available on the [Play Store](https://play.google.com/store/apps/details?id=com.funcs.io.lynx.go), published by community contributors.
While this version is not reviewed and maintained by the Lynx team, we're thankful to the community for making it more convenient for developers to try out Lynx on Android.
:::
We currently only provide pre-built binaries for the harmony simulator. If you need to run Lynx Explorer on a real harmony device, you'll need to build it from source. Please refer to the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
1. **Install DevEco Studio**
Download the latest DevEco Studio from the [official website](https://developer.huawei.com/consumer/en/deveco-studio/).
2. **<div id="download-lynx-explorer">Download Lynx Explorer</div>**
Download the pre-built app [`lynx_explorer-default-unsigned.hap`](https://github.com/lynx-family/lynx/releases/download/3.7.0/lynx_explorer-default-unsigned.hap).
Or, you may build from source by following the [Build Lynx Explorer for Harmony](https://github.com/lynx-family/lynx/tree/develop/explorer/harmony) guide.
3. **Install Lynx Explorer on Simulator**
```bash
hdc install lynx_explorer-default-unsigned.hap
```
### Start developing
1. Navigate to the created project:
```bash
cd <project-name>
```
2. Install the NPM dependencies with package manager:

```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```
3. To start the development server, run:

```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```
You will see a QR code showing up in the terminal, scan with your Lynx Explorer App or if you are using the simulator, just copy the bundle URL and paste it on the "Enter Card URL" input in the Lynx Explorer App and hit "Go".
4. Make your first change
Open the `src/App.tsx` file in your code editor and make a change.
You should see the UI on your Lynx Explorer being updated automatically.
**This is an example below: hello-world**

**Bundle:** `dist/main.lynx.bundle` | Web: `dist/main.web.bundle`

```tsx
import { useCallback, useEffect, useState } from "@lynx-js/react";

import "./App.css";
import arrow from "./assets/arrow.png";
import lynxLogo from "./assets/lynx-logo.png";
import reactLynxLogo from "./assets/react-logo.png";

export function App() {
  const [alterLogo, setAlterLogo] = useState(false);

  useEffect(() => {
    console.info("Hello, ReactLynx");
  }, []);

  const onTap = useCallback(() => {
    "background-only";
    setAlterLogo(!alterLogo);
  }, [alterLogo]);

  return (
    <page>
      <view className="Background" />
      <view className="App">
        <view className="Banner">
          <view className="Logo" bindtap={onTap}>
            {alterLogo
              ? <image src={reactLynxLogo} className="Logo--react" />
              : <image src={lynxLogo} className="Logo--lynx" />}
          </view>
          <text className="Title">React</text>
          <text className="Subtitle">on Lynx</text>
        </view>
        <view className="Content">
          <image src={arrow} className="Arrow" />
          <text className="Description">Tap the logo and have fun!</text>
          <text className="Hint">
            Edit<text style={{ fontStyle: "italic", color: "rgba(255, 255, 255, 0.85)" }}>{" src/App.tsx "}</text>
            to see updates!
          </text>
        </view>
        <view style={{ flex: 1 }}></view>
      </view>
    </page>
  );
}

```



### Debugging
Visit [Lynx DevTool](https://github.com/lynx-family/lynx-devtool/releases) to download and open the Lynx DevTool desktop application. Use a USB cable to connect the debugging device, and start debugging.
Visit [Debugging](/guide/devtool/panels.md), learn how to debug your Lynx app.

## Next Steps

Here are a few things that we recommend exploring next. You can read them in any order.

### ReactLynx

ReactLynx is the official React framework designed specifically for Lynx, offering a familiar and idiomatic React development experience.

[Tutorial

Step-by-step walkthrough of building a Gallery page with Lynx

](/learn/gallery)[Thinking in ReactLynx

Learn how to think in the ReactLynx framework

](/react/thinking-in-reactlynx)
### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

[Elements

Check out the built-in elements that Lynx provides

](/guide/ui/elements-components)[Styling

Learn how to apply different styles in Lynx

](/guide/ui/styling)


[Layout

Layout your elements and Components

](/guide/ui/layout)[Scrolling

Learn how to use scrollable elements in Lynx

](/guide/ui/scrolling)