# Lynx

> 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.

---

# Source: https://lynxjs.org/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));
  },
);
```

---

# Source: https://lynxjs.org/ai/agentsmd.md

# `AGENTS.md` for Lynx

The [`AGENTS.md`](https://agents.md) file is similar to `README.md`, but it's for agents.

In this document, you'll learn how to add a suitable `AGENTS.md` for your Lynx project, ensuring your agents can perform at their best within your Lynx project.

## Creating a New Project

We've included `AGENTS.md` in the initial project template. You can refer to [Quick Start](/guide/start/quick-start.md#create-a-new-lynx-project) to create a new Lynx project. The project's root directory will contain a pre-written `AGENTS.md` file.

## Adding `AGENTS.md` to an Existing Project

For Lynx projects, you can start with this file and then modify it according to your project needs:

- [`AGENTS.md` in Lynx Template Project](https://github.com/lynx-family/lynx-stack/blob/main/packages/rspeedy/create-rspeedy/template-common/AGENTS.md)

## Modifying the existing `AGENTS.md`

Below is an example; please add the "Read in Advance" section to your project's `AGENTS.md`:

:::info No Magic Spell

This section isn't a magic spell; it works because:

1. It provides the agent with the LLM-friendly Lynx website: [llms.txt](https://lynxjs.org/llms.txt).

2. It explicitly emphasizes the importance of reading [llms.txt](https://lynxjs.org/llms.txt) in `AGENTS.md` to agents.

:::

```markdown
# My Awesome Project

<!-- Here goes your original project description -->

<!-- Insert the section below -->

## 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.

<!-- Below goes your original content -->

## Build Instructions

<!-- ... -->

## Test Instructions

<!-- ... -->
```

## Using `AGENTS.md` in a Monorepo

In a monorepo, you can add an `AGENTS.md` file to each subproject to provide specific guidance and information to agents for each subproject. This helps ensure that agents can optimize and adapt to the needs and characteristics of their respective sub-projects.

However, you can use `AGENTS.md` in the monorepo root directory as a global guideline file, providing general information and guiding principles.

For example:

```bash

$ tree
.
├── AGENTS.md # the global AGENTS.md
├── README.md
└── packages
    ├── web
    │   ├── AGENTS.md # the AGENTS.md for web project
    │   ├── package-a
    │   │   └── AGENTS.md
    │   └── package-b
    │       └── AGENTS.md
    └── lynx
        ├── AGENTS.md # the AGENTS.md for lynx project
        ├── package-c
        │   └── AGENTS.md
        └── package-d
            └── AGENTS.md # the AGENTS.md for d subproject
```

In this example, you should place Lynx-specific guidance and information in `packages/lynx/AGENTS.md`.

For example, when agents process tasks under package-d, they should first refer to `packages/lynx/package-d/AGENTS.md`, then `packages/lynx/AGENTS.md`, and finally the `AGENTS.md` in the root directory.

Organizing the `AGENTS.md` files in a tree structure avoids repetitive writing of the same information and ensures that agents can access the most relevant and up-to-date guidance. However, developers should ensure that the information in the various `AGENTS.md` files does not conflict with each other to avoid causing abnormal agent behavior.

## Using `llms.txt` as `AGENTS.md`

If agents are not reading the Lynx documentation as required, consider inlining or overwriting the contents of `llms.txt` into `AGENTS.md`.

```bash
curl https://lynxjs.org/llms.txt > packages/lynx/AGENTS.md
```

It is recommended to use this method only for public `AGENTS.md` files to avoid duplicate content across multiple files and to override customized instructions for specific subprojects.

If you want to keep `llms.txt` up-to-date, you can add the above command to the prepare script in your package.json (or root package.json for monorepo). Remember to gitignore the generated `AGENTS.md` file to avoid committing it to version control.

## Troubleshooting

### Agents Not Reading Lynx Documentation as Required

Ensure that the "Read in Advance" section is correctly added to `AGENTS.md`, explicitly stating that agents must read [llms.txt](https://lynxjs.org/llms.txt).

If the problem persists, consider inlining the contents of `llms.txt` directly into `AGENTS.md`, as shown in the example above.

---

# Source: https://lynxjs.org/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();
}

```

---

# Source: https://lynxjs.org/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 | - |
| 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.

<APITableExplorer />

## 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.

---

# Source: https://lynxjs.org/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 cursur 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.

<table rules="none" align="center" width="100%" style={{tableLayout:"fixed"}}>
  <tr style={{height: '275px'}}>
    <td style={{padding: '15px'}}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/color-gradient.png" style={{width: "80%"}} />

        <br />

        <span>
          Text with a gradient 

          <code>color</code>
        </span>
      </center>
    </td>

    <td style={{padding: '15px'}}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-radial-gradient.png" style={{width: "80%"}} />

        <br />

        <span>
          Filling background with 

          <code>radial-gradient</code>
        </span>
      </center>
    </td>

    <td style={{padding: '15px'}}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-fading-edge.gif" style={{width: "80%"}} />

        <br />

        <span>
           Create a 'fading edge' effect by adding 

          <code>linear-gradient</code>

           to 

          <code>mask-image</code>

          property
        </span>
      </center>
    </td>
  </tr>
</table>

## 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();
}

```



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

**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();
}

```



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

---

# Source: https://lynxjs.org/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.dev/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

---

# Source: https://lynxjs.org/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} />;
```

[Lynx 3.5: Main Thread Script, React Compiler, HarmonyOS ImprovementsNovember 10, 2025

![](https://github.com/loongliu.png)Leron LiuPerformance Lead @ Lynx![](https://github.com/huxpro.png)Xuan HuangArchitect @ Lynx![](https://github.com/lynx-family.png)The Lynx Teamlynxjs.org](/next/blog/lynx-3-5)
### `<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']} />;
```

<BlogAvatar list={['lynx']} />

## 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.

---

# Source: https://lynxjs.org/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).

---

# Source: https://lynxjs.org/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
```

---

# Source: https://lynxjs.org/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.dev/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

---

# Source: https://lynxjs.org/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.

<Mermaid title="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
    `}
</Mermaid>

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`

<APITableExplorer />

[Bundle]: /guide/spec.md#app-bundle-aka-template-bundle

[Lynx Engine]: /guide/spec.md#engine

[`engineVersion`]: /api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.targetsdkversion.md

---

# Source: https://lynxjs.org/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 />
```

<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
  <AndroidOnly />

  <IOSOnly />

  <WebOnly />

  <HarmonyOnly />
</div>

### Status Badges

Indicate API or feature status.

```tsx
<Deprecated />
<Experimental />
<Required />
```

<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
  <Deprecated />

  <Experimental />

  <Required />
</div>

### Runtime Badges

Indicate which thread the script runs on.

```tsx
<RuntimeBadge type="mts" />
<RuntimeBadge type="bts" />
```

<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
  <RuntimeBadge type="mts" />

  <RuntimeBadge type="bts" />
</div>

### Version Badge

Indicates the Lynx version a feature was introduced.

```tsx
<VersionBadge v={2.5} />
<VersionBadge>2.5.1</VersionBadge>
```

<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
  <VersionBadge v={2.5} />

  <VersionBadge>
    2.5.1
  </VersionBadge>
</div>

### Generic Badges

Standard Rspress badge.

```tsx
<Badge type="tip" text="Recommended" />
<Badge type="warning" text="Deprecated" />
```

<div style={{ display: 'flex', gap: '8px' }}>
  <Badge type="tip" text="Recommended" />

  <Badge type="warning" text="Deprecated" />
</div>

## 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>
```

<PlatformTabs defaultPlatform="ios" queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    iOS Content
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    Android Content
  </PlatformTabs.Tab>
</PlatformTabs>

### 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>
```

<Columns titles={['Left Column', 'Right Column']}>
  <div>
    Content for the left column.
  </div>

  <div>
    Content for the right column.
  </div>
</Columns>

### 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>
```

<ResponsiveDualColumn>
  <FlexItem minWidth={300}>
    <div style={{ background: 'var(--rp-c-bg-mute)', padding: '1rem' }}>
      Left Content (min 300px)
    </div>
  </FlexItem>

  <FlexItem minWidth={300}>
    <div style={{ background: 'var(--rp-c-bg-mute)', padding: '1rem' }}>
      Right Content (min 300px)
    </div>
  </FlexItem>
</ResponsiveDualColumn>

### Browser Container

Wraps content in a browser-like window frame.

```tsx
<BrowserContainer>
  <div style={{ padding: '20px', textAlign: 'center' }}>Browser Content</div>
</BrowserContainer>
```

<BrowserContainer>
  <div style={{ padding: '20px', textAlign: 'center' }}>
    Browser Content
  </div>
</BrowserContainer>

### CodeFold

Collapsible code block, optionally with an image.

````tsx
<CodeFold toggle>```ts console.log('Hidden code'); ```</CodeFold>
````

<CodeFold toggle>
  ```ts
  console.log('Hidden code');
  ```
</CodeFold>

## Media & Embeds

### YouTube

```tsx
<YouTubeIframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" />
```

<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}
/>
```

<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}
/>

### Mermaid Diagrams

```tsx
<Mermaid>
  graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
</Mermaid>
```

<Mermaid>
  graph TD; A-->B; A-->C; B-->D; C-->D;
</Mermaid>

## 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 />
```

<EditThis />

### Version Table

Renders a table of Lynx versions.

```tsx
<VersionTable type="latest" />
```

<VersionTable type="latest" />

---

# Source: https://lynxjs.org/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{/* enable hints */}.

```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{/* enable hints */}:

```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 | - |

---

# Source: https://lynxjs.org/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

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    <CustomComponentLynxIOS />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    <CustomComponentLynxAndroid />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    <CustomComponentLynxHarmony />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="web">
    <CustomComponentLynxWeb />
  </PlatformTabs.Tab>
</PlatformTabs>

## 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`

```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>
  );
}

```

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/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)

---

# Source: https://lynxjs.org/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

<PackageManagerTabs command="install @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();
}

```

---

# Source: https://lynxjs.org/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.

<video src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/devtool-overview.mp4" loop autoPlay muted />

## 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

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-ios.png" alt="Lynx DevTool Switch Page" width={200} />

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

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-using-devtool-toolbar-connection.png" alt="View Device Connection Status" width={400} />

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

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-using-devtool-toolbar-choose-device.png" alt="Choose Debugging Device" width={400} />

In the toolbar, you can click this button, and select other connected devices from the pop-up menu.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-device-menu.png" alt="Choose Debugging Device" width={140} />

:::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!

---

# Source: https://lynxjs.org/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):

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tags.png" width="100%" height="40%" />

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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_tree.png" width="100%" height="30%" />

## 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>
```

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx_gray.png" width="100%" height="30%" />

### 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>
```

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_hello_lynx.png" width="100%" height="30%" />

### 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" />
```

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_lynx_logo.png" width="20%" />

### More Built-in Elements

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

## Behind the Elements: Native Rendering

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/elements_2_na.png" width="100%" height="30%" />

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:

<div style={{width: '100%', overflowX: 'scroll'}}>
  <div style={{width: 'max-content'}}>
    | 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.                                                           |
  </div>
</div>

## 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.

---

# Source: https://lynxjs.org/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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/event/event_handling.png" width="100%" height="40%" />

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} />
```

<Details title="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).
</Details>

## 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.

<Details title="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.
</Details>

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`.

<Details title="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.
</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.

---

# Source: https://lynxjs.org/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 <NoWeb />

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:

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```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];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```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);
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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);
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

### 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();
}

```

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/exposure-ability.png" width="40%" height="40%" />

## 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.

---

# Source: https://lynxjs.org/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();
}

```



<Details title={<span>Lynx differs from Web in the minimum value for shrinking sub-elements.</span>}>
  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.

  <Columns titles={['Code', 'Inconsistent behavior between Web and Lynx']}>
    ```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>
    ```

    <center>
      <img width="70%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/layout_min_content.png" />
    </center>
  </Columns>
</Details>

### 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

---

# Source: https://lynxjs.org/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 <VersionBadge v={3.4} />
. To use this element, the Lynx dependency version must be upgraded to <VersionBadge v={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

### `data`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
data?: Record<string, unknown>;
```

Passes data to the nested Lynx page within the frame.

### `global-props`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.6
</VersionBadge>

```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`](/api/lynx-api/lynx/lynx-global-props.md).

### `src`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.6
</VersionBadge>

```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

---

# Source: https://lynxjs.org/guide/glossary.md

{/* import { Toc } from '@theme'; */}

# 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).

{/* <Toc/> */}

## 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

---

# Source: https://lynxjs.org/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.

<center>
  <img width="100%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/grid_define.png" />
</center>

### 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

---

# Source: https://lynxjs.org/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.

<Details title="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)

  :::
</Details>

## 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.
:::

<VideoList
  videos={[
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/ifr_fib_with_blank.mp4',
    title: 'Other cross-platform solutions (No IFR)',
  },
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/ifr_fib.mp4',
    title: 'Lynx (IFR)',
  },
]}
  playbackRate={0.3}
/>

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.

---

# Source: https://lynxjs.org/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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.6
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.11
</VersionBadge>

```tsx
// @defaultValue: true
autoplay?: boolean;
```

Specifies whether the animated image should start playing automatically once it is loaded.

### `blur-radius`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  0.2
</VersionBadge>

```tsx
'blur-radius'?: string;
```

Image blur radius

### `cap-insets`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
'cap-insets'?: string;
```

Stretchable area for 9patch images, in percentage or decimal, four values for top, right, bottom, left

### `cap-insets-scale`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: 1
'cap-insets-scale'?: number;
```

Adjust the scale of stretchable area for 9patch images

### `defer-src-invalidation`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.7
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<ClayOnly />

<VersionBadge>
  1.4
</VersionBadge>

```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

### `loop-count`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: 0
'loop-count'?: number;
```

Number of times an animated image plays, 0 stands for infinite

### `mode`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  0.2
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
placeholder?: string;
```

Placeholder image, used same as src

### `prefetch-height`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  1.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: "0px"
'prefetch-width'?: string;
```

Image won't load if its size is 0, but will load if prefetch-width is set

### `src`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  0.2
</VersionBadge>

```tsx
// @defaultValue: undefined
src?: string;
```

Supports http/https/base64

### `tint-color`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  2.12
</VersionBadge>

```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.

### `binderror`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  0.2
</VersionBadge>

```tsx
binderror = (e: ErrorEvent) => {};
```

Image load error event

### `bindload`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  0.2
</VersionBadge>

```tsx
bindload = (e: LoadEvent) => {};
```

Image load success event

## Methods

Frontend can invoke component methods via the [SelectorQuery](/api/lynx-api/nodes-ref/nodes-ref-invoke.md) API.

### `pauseAnimation`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.11
</VersionBadge>

```ts

lynx.createSelectorQuery()
.select('#id')
.invoke({
method: 'pauseAnimation',
success: function (res) {},
fail: function (res) {},
})
.exec();

```

Pauses the animation, without resetting the loop-count.

### `resumeAnimation`

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.11
</VersionBadge>

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'resumeAnimation',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Resumes the animation, without resetting the loop-count.

### `startAnimate`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<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`

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.11
</VersionBadge>

```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:

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```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
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```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
            ) ?: ""
        }
    }
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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;
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

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


```
```

---

# Source: https://lynxjs.org/rspeedy/index.md

# Source: https://lynxjs.org/react/index.md

# Source: https://lynxjs.org/help/index.md

# Source: https://lynxjs.org/ai/index.md

# Source: https://lynxjs.org/blog/index.md

# Source: https://lynxjs.org/guide/ui/layout/index.md

# Source: https://lynxjs.org/guide/scripting-runtime/index.md

# Source: https://lynxjs.org/guide/ui/layout/index.md

# Source: https://lynxjs.org/guide/scripting-runtime/index.md

# JavaScript Runtime

## 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.

## 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.


<Tabs
  defaultValue="common"
  groupId="install-script"
  values={[
  { label: 'common.js', value: 'common' },
  { label: 'ReactLynx', value: 'react' },
]}
>
  <Tab value="common">
    ```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;
    ```
  </Tab>

  <Tab value="react">
    ```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>;
      }
    }
    ```
  </Tab>
</Tabs>

:::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.

<Tabs
  defaultValue="utils"
  groupId="install-script"
  values={[
  { label: 'utils.js', value: 'utils' },
  { label: 'ReactLynx', value: 'react' },
]}
>
  <Tab value="utils">
    ```js title="utils.js"
    export function getAge() {
      return 11;
    }

    export default function (add1, add2) {
      return add1 + add2;
    }
    ```
  </Tab>

  <Tab value="react">
    ```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>;
      }
    }
    ```
  </Tab>
</Tabs>

---

# Source: https://lynxjs.org/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`

{' '}

<AndroidOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: 'send'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.5
</VersionBadge>

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `input-filter`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

{' '}

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

{' '}

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `maxlength`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `placeholder`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```ts

lynx.createSelectorQuery()
.select('#id')
.invoke({
method: 'blur',
success: function (res) {},
fail: function (res) {},
})
.exec();

```

Release focus

### `focus`

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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

---

# Source: https://lynxjs.org/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).

:::

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    <Steps>
      ### 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', '3.6.0' # [!code --]
      pod 'Lynx', '3.6.0-dev' # [!code ++]

      pod 'LynxDevtool', '3.6.0' # [!code --]
      pod 'LynxDevtool', '3.6.0-dev' # [!code ++]
      ```

      ### Install Dependencies

      Run `pod install` to install dependencies, then open your Xcode project and rebuild.
    </Steps>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    <Steps>
      ### 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:

      <Tabs groupId="impl-android">
        <Tab label="build.gradle">
          ```groovy
          - implementation ("org.lynxsdk.lynx:lynx:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx:3.6.0-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:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx-trace:3.6.0-dev")

          - implementation ("org.lynxsdk.lynx:lynx-devtool:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx-devtool:3.6.0") {
          +   // 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'
          + }

          ```
        </Tab>

        <Tab label="build.gradle.kts">
          ```kotlin

          - implementation ("org.lynxsdk.lynx:lynx:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx:3.6.0-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:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx-trace:3.6.0-dev")

          - implementation ("org.lynxsdk.lynx:lynx-devtool:3.6.0")
          + implementation ("org.lynxsdk.lynx:lynx-devtool:3.6.0") {
          +   // 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')
          + }

          ```
        </Tab>
      </Tabs>

      ### Rebuild your application

      Rebuild your application to ensure all changes take effect.
    </Steps>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    <Steps>
      ### 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.6.0", // [!code --]
        "@lynx/lynx_devtool": "3.6.0", // [!code --]
        "@lynx/lynx": "3.6.0-dev", // [!code ++]
        "@lynx/lynx_devtool": "3.6.0-dev", // [!code ++]
      }
      ```

      ### Install Dependencies

      Run `ohpm install` to install dependencies, then open your DevEco-Studio project and rebuild.
    </Steps>
  </PlatformTabs.Tab>
</PlatformTabs>

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.

---

# Source: https://lynxjs.org/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.

<div id="debugging-devtool-switch" />

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-ios.png" alt="Lynx DevTool Switch Page" width={200} />

    > 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:

    <Tabs groupId="switch-page-ios">
      <Tab label="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
        ```
      </Tab>

      <Tab label="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")
          }
        }
        ```
      </Tab>
    </Tabs>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/debugging-devtool-switch-en-android.png" alt="Lynx DevTool Switch Page" width={200} />

    > 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:

    <Tabs groupId="switch-page-android">
      <Tab label="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();
            }

        }

        ```
      </Tab>

      <Tab label="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)
            }
        }
        ```
      </Tab>
    </Tabs>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/debugging-devtool-switch-en-harmony.png" alt="Lynx DevTool Switch Page" width={200} />

    > 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:

    <Tabs groupId="switch-page-harmony">
      <Tab label="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)
          }
        }

        ```
      </Tab>
    </Tabs>
  </PlatformTabs.Tab>
</PlatformTabs>

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`

---

# Source: https://lynxjs.org/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).
:::

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    <Steps>
      ### Adding Dependencies

      You need to add two components: `LynxDevTool` and the `Devtool` subcomponent of `LynxService`.

      ```ruby title="Podfile" {8,11}
      # Ensure Lynx DevTool version matches the Lynx version when integrating
      target 'YourTarget' do
        pod 'LynxService', '3.6.0', :subspecs => [
            'Devtool',
        ]
        pod 'LynxDevtool', '3.6.0'
      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).

      <Details title="These three 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.
      </Details>

      You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

      <Tabs groupId="integrating-lynx-with-existing-app-ios">
        <Tab label="Objective-C">
          ```objective-c title=AppDelegate.m {9-16}
          #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 Lynx Debug
            lynxEnv.lynxDebugEnabled = YES;
            // Enable Lynx DevTool
            lynxEnv.devtoolEnabled = YES;
            // Enable Lynx LogBox
            [LynxService(LynxServiceDevToolProtocol) setLogBoxPresetValue:YES];
            lynxEnv.logBoxEnabled = YES;
            return YES;
          }
          ```
        </Tab>

        <Tab label="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-12}
          class AppDelegate: UIResponder, UIApplicationDelegate {

            func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
              // ...
              let lynxEnv = LynxEnv.sharedInstance()
              // 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
            }
          }
          ```
        </Tab>
      </Tabs>

      :::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).
      :::
    </Steps>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    <Steps>
      ### Adding Dependencies

      You need to integrate these two components: `lynx-service-devtool` and `lynx-devtool`

      <Tabs groupId="impl-android">
        <Tab label="build.gradle">
          ```groovy
          // Ensure Lynx DevTool version matches the Lynx version when integrating
          dependencies {
            implementation "org.lynxsdk.lynx:lynx-devtool:3.6.0"
            implementation "org.lynxsdk.lynx:lynx-service-devtool:3.6.0"
          }
          ```
        </Tab>

        <Tab label="build.gradle.kts">
          ```kotlin
          // Ensure Lynx DevTool version matches the Lynx version when integrating
          dependencies {
            implementation ("org.lynxsdk.lynx:lynx-devtool:3.6.0")
            implementation ("org.lynxsdk.lynx:lynx-service-devtool:3.6.0")
          }
          ```
        </Tab>
      </Tabs>

      :::info
      It is recommended to use the latest [Lynx version](https://github.com/lynx-family/lynx/releases) when integrating
      :::

      ### Registering DevTool Service

      <Tabs groupId="register-devtool-service-android">
        <Tab label="Java">
          ```java title=YourApplication.java {3-4}
          private void initLynxService() {
            // ...
            // register DevTool service
            LynxServiceCenter.inst().registerService(LynxDevToolService.getINSTANCE());
          }

          ```
        </Tab>

        <Tab label="Kotlin">
          ```kotlin title=YourApplication.kt {3-4}
          private fun initLynxService() {
            // ...
            // register DevTool service
            LynxServiceCenter.inst().registerService(LynxDevToolService.INSTANCE)
          }
          ```
        </Tab>
      </Tabs>

      ### 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).

      <Details title="These three 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 enable the `LoadJsBridge` switch.
        * LogBox helps you quickly identify and diagnose issues.
      </Details>

      You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

      <Tabs groupId="turn-on-switches-android">
        <Tab label="Java">
          ```java title=YourApplication.java {3-11}
          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
            LynxDevToolService.getINSTANCE().setLogBoxPresetValue(true);
            LynxEnv.inst().enableLogBox(true);
            // Enable LoadJsBridge
            LynxDevToolService.getINSTANCE().setLoadJsBridge(true);
          }

          ```
        </Tab>

        <Tab label="Kotlin">
          ```kotlin title=YourApplication.kt {3-11}
          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
            LynxDevToolService.INSTANCE.setLogBoxPresetValue(true)
            LynxEnv.inst().enableLogBox(true)
            // Enable LoadJsBridge
            LynxDevToolService.INSTANCE.setLoadJsBridge(true)
          }
          ```
        </Tab>
      </Tabs>

      :::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).
      :::
    </Steps>
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    <Steps>
      ### Adding Dependencies

      You need to integrate these two components: `@lynx/lynx_devtool` and `@lynx/lynx_devtool_service`.

      <Tabs groupId="impl-harmony">
        <Tab label="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"
          }
          ```
        </Tab>

        <Tab label="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"
                  ]
                }
              },
          }
          ```
        </Tab>
      </Tabs>

      :::info
      It is recommended to use the latest [Lynx version](https://github.com/lynx-family/lynx/releases) when integrating
      :::

      ### Registering DevTool Service

      <Tabs groupId="register-devtool-service-harmony">
        <Tab label="ETS">
          ```ts title=YourEntryAbility.ets {2 - 3}
          // Initialize LynxDevToolService first, as LynxEnv initialization
          // depends on LynxDevToolService from LynxService
          LynxServiceCenter.registerService(
            LynxServiceType.DevTool,
            LynxDevToolService.instance,
          );
          ```
        </Tab>
      </Tabs>

      ### 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).

      <Details title="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.
      </Details>

      You can configure these switches during [Lynx Environment Initialization](/guide/start/integrate-with-existing-apps.md):

      <Tabs groupId="turn-on-switches-harmony">
        <Tab label="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);
          }

          ```
        </Tab>
      </Tabs>

      :::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).
      :::
    </Steps>
  </PlatformTabs.Tab>
</PlatformTabs>

Congratulations! You have completed the DevTool integration. Now, you may launch the Lynx DevTool Desktop and
connect your app via USB to start debugging.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/devtool_connected_success.png" alt="Integrate Lynx DevTool Successfully" width={800} />

<NextSteps.Root>
  <NextSteps.Step href="/guide/start/integrate-lynx-devtool-advanced" title="More DevTool Switches" description="Need more advanced configurations for DevTool?" />
</NextSteps.Root>

## Compatibility


**Error:** No compatibility data found for `devtool.integration`
## Next Step

<NextSteps.Root>
  <NextSteps.Step href="/guide/devtool/panels.html" title="Use DevTool" description="Learn how to use Lynx DevTool Desktop for in-depth debugging capabilities" />
</NextSteps.Root>

---

# Source: https://lynxjs.org/ai/start/integrate-with-existing-apps.md

# Source: https://lynxjs.org/rspeedy/start/integrate-with-existing-apps.md

# Source: https://lynxjs.org/react/start/integrate-with-existing-apps.md

# Source: https://lynxjs.org/guide/start/integrate-with-existing-apps.md

# Integrate with Existing Apps

Currently, Lynx is not suitable for building a new application from scratch. You need to integrate Lynx (engine) with your native mobile app or web app, and load Lynx apps through Lynx views. With a few steps, you can start developing with Lynx in your application.

Choose your target platform to view the specific integration steps:

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    <IntegratingLynxIOS />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    <IntegratingLynxAndroid />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    <IntegratingLynxHarmony />
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="web">
    <IntegratingLynxWeb />
  </PlatformTabs.Tab>
</PlatformTabs>

## Next Steps

<NextSteps.Root>
  <NextSteps.Step href="/guide/start/integrate-lynx-devtool" title="Integrate Lynx DevTool" description="Integrate Lynx DevTool to debug Lynx pages" />
</NextSteps.Root>

---

# Source: https://lynxjs.org/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:

<PackageManagerTabs command="install 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.

{/* <!-- eslint-disable import/no-unresolved --> */}

```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.dev/api/runtime-api/module-variables#importmetawebpackcontext) API of Rspack to statically import all the JSON files.

<Columns titles={['import one-by-one', 'import.meta.webpackContext']}>
  ```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');
  ```
</Columns>

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:

<PackageManagerTabs command="install 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:

<Columns>
  ```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": "世界"}');
    },
  };
  ```
</Columns>

:::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>
  );
}

```

---

# Source: https://lynxjs.org/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).

---

# Source: https://lynxjs.org/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).

<Details title="Event propagation is also different">
  For 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.
</Details>

```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.

<Details title="No &#x22;DOM&#x22;?">
  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.
</Details>

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

<NextSteps.Root>
  <NextSteps.Step href="/react/thinking-in-reactlynx" title="Thinking in ReactLynx" description="Learn how to think in the ReactLynx framework" />

  <NextSteps.Step href="/react/lifecycle" title="Rendering Process and Lifecycle" description="Understand the rendering process and lifecycle of ReactLynx" />
</NextSteps.Root>

### Learn Lynx Basics

If you haven't already, you should learn the basics of Lynx.

<NextSteps.Root>
  <NextSteps.Step href="/guide/ui/elements-components" title="Elements" description="Check out the built-in elements that Lynx provides" />

  <NextSteps.Step href="/guide/ui/styling" title="Styling" description="Learn how to apply different styles in Lynx" />
</NextSteps.Root>

<br />

<NextSteps.Root>
  <NextSteps.Step href="/guide/ui/layout" title="Layout" description="Layout your elements and Components" />

  <NextSteps.Step href="/guide/ui/scrolling" title="Scrolling" description="Learn how to use scrollable elements in Lynx" />
</NextSteps.Root>

---

# Source: https://lynxjs.org/react/state-management/jotai.md

# Jotai

## Using `jotai`

[Jotai](https://jotai.org) takes an atomic approach to global React state management.

### Installation

<PackageManagerTabs command="install 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.

---

# Source: https://lynxjs.org/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`

```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

---

# Source: https://lynxjs.org/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;
```

<center>
  <img width="50%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/linear_main_axis.png" />
</center>

### 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).

---

# Source: https://lynxjs.org/api/elements/built-in/list.md

---

# Source: https://lynxjs.org/blog/lynx-3-2.md

_May 14th, 2025_

# What’s new in Lynx 3.2

<BlogAvatar list={['shiwentao', 'lynx']} />

![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`
 <Badge>Web-friendly</Badge>

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>`
 <Badge>Web-friendly</Badge>

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 <Badge>Web-friendly</Badge>

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(
          {
            // @ts-expect-error TODO(types): support `query` in `@lynx-js/types`
            query: true,
            id: true,
          },
          resolve,
        )
        .exec();
    });

    Promise.all(
      resArray.map((element) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve) => {
          // @ts-expect-error TODO(types): support `query` in `@lynx-js/types`
          element.query
            .selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: (res: {
                top: number;
                left: number;
                width: number;
                height: number;
                id: string;
              }) => {
                resolve(res);
              },
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = [...values].map(({ top, left, width, height, id }) => ({
        id: String(id),
        left: Number(left),
        top: Number(top),
        width: Number(width),
        height: Number(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 <Badge>Web-friendly</Badge>

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 <Badge>Web-friendly</Badge>

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.

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/lynx-console.gif" width="400" height="400" align="center" />
</center>

## 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.dev/) [1.3](https://rspack.dev/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.

<center>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/news-in-3.2/devtoolsopt.gif" width="800" height="800" />
</center>

## 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:

<Tabs groupId="update-lynx-3-2-with-existing-app">
  <Tab label="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"
    }
    ```
  </Tab>

  <Tab label="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")
    }
    ```
  </Tab>
</Tabs>

In your project's `build.gradle` or `build.gradle.kts` file, update the LynxService version:

<Tabs groupId="update-lynx-3-2-with-existing-app">
  <Tab label="build.gradle">
    <CodeFold height={360} toggle>
      ```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"

      }
      ```
    </CodeFold>
  </Tab>

  <Tab label="build.gradle.kts">
    <CodeFold height={360} toggle>
      ```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")
      }
      ```
    </CodeFold>
  </Tab>
</Tabs>

### iOS

In your project's `Podfile` file, update the Lynx version as follows:

<CodeFold height={360} toggle>
  ```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
  ```
</CodeFold>

In your project's `Podfile` file, update the LynxService version as follows:

<CodeFold height={360} toggle>
  ```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
  ```
</CodeFold>

## 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._

---

# Source: https://lynxjs.org/blog/lynx-3-4.md

_September 3rd, 2025_

# Lynx 3.4: HarmonyOS Support, Trace and Recorder, Text Input Elements

<BlogAvatar list={['liujilong', 'lynx']} />

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://tosv-sg.tiktok-row.org/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`

```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.

<table border="0">
   

  <tr> <td>![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/not-recycle-sticky-1.gif)</td> <td>![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/recycle-sticky-1.gif)</td> </tr>

   

  <tr> <td>sticky `<list-item>` in Lynx 3.3</td> <td>sticky `<list-item>` in Lynx 3.4</td> </tr>

   
</table>

### 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.

---

# Source: https://lynxjs.org/blog/lynx-3-5.md

_November 10th, 2025_

# Lynx 3.5: Main Thread Script, React Compiler, HarmonyOS Improvements

<BlogAvatar list={['liujilong', 'huxpro', 'lynx']} />

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 <Badge>Web Friendly</Badge>

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>
```

<table border="0">
  <tr>
    <td>
      ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_delete.gif)
    </td>

    <td>
      ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_update.gif)
    </td>

    <td>
      ![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/5_insert.gif)
    </td>
  </tr>

  <tr>
    <td>
      Delete
    </td>

    <td>
      Update
    </td>

    <td>
      Insert
    </td>
  </tr>
</table>

## CSS Property: `pointer-events`
 <Badge>Web Friendly</Badge>

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):

<YouTubeIframe src="https://www.youtube.com/embed/n0jDZSI4tXg" />

---

# Source: https://lynxjs.org/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 | - |
| Web | ❌ No | - |

**Description:** Create An Animation in MTS

---

# Source: https://lynxjs.org/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"]
    }
  }
}
```

<details>
  <summary>
    Claude Code
  </summary>

  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
  ```
</details>

<details>
  <summary>
    Codex
  </summary>

  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
  ```
</details>

<details>
  <summary>
    Copilot / VS Code
  </summary>

  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"]}'
  ```
</details>

<details>
  <summary>
    Cursor
  </summary>

  **Click the button to install:**

  <a href="https://cursor.com/en/install-mcp?name=lynx-devtool&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBseW54LWpzL2RldnRvb2wtbWNwLXNlcnZlckBsYXRlc3QiXX0=">
    <img src="https://cursor.com/deeplink/mcp-install-light.svg" alt="Install Lynx DevTool MCP in Cursor" style={{ display: 'block', cursor: 'pointer' }} />
  </a>

  **Or install manually:**

  Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
</details>

<details>
  <summary>
    Gemini CLI
  </summary>

  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.
</details>

## 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.

---

# Source: https://lynxjs.org/ai/lynx-docs-mcp.md

# Lynx Docs MCP

> A MCP Server providing docs for LLMs from [Lynx official site](https://lynxjs.org/), with carefully designed prompting.

`@lynx-js/docs-mcp-server` 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.
```

<details>
  <summary>
    Claude Code
  </summary>

  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
  ```
</details>

<details>
  <summary>
    Codex
  </summary>

  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
  ```
</details>

<details>
  <summary>
    Copilot / VS Code
  </summary>

  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"]}'
  ```
</details>

<details>
  <summary>
    Cursor
  </summary>

  **Install manually:**

  Go to `Cursor Settings` -> `MCP` -> `New MCP Server`. Use the config provided above.
</details>

<details>
  <summary>
    Gemini CLI
  </summary>

  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.
</details>

## 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.

---

# Source: https://lynxjs.org/blog/lynx-harmony.md

_September 25, 2025_

# Announcing Lynx for HarmonyOS

<BlogAvatar list={['baiqiang', 'shiwentao', 'lynx']} />

![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](/guide/start/tutorial-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.

<VideoList
  videos={[
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/ifr-harmony.mp4',
    title: 'Running Lynx on HarmonyOS',
  },
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/ifr-android1.mp4',
    title: 'Running Lynx on Android',
  },
]}
  playbackRate={1}
/>

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.

<table rules="none" align="center" width="100%" style={{ tableLayout: 'fixed' }}>
  <thead align="center">
    <th colSpan={1}>
      <span style={{ fontWeight: 'bold' }}>
        Gesture Support
      </span>
    </th>

    <th colSpan={1}>
      <span style={{ fontWeight: 'bold' }}>
        Custom Gesture Control in Hybrid Scenarios
      </span>
    </th>
  </thead>

  <tr>
    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/base-event.gif" style={{ width: '200px', height: '380px', aspectRatio: '1/1' }} />
      </center>
    </td>

    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-harmony/complex-event.gif" style={{ width: '200px', height: '380px', aspectRatio: '1/1' }} />
      </center>
    </td>
  </tr>
</table>

- **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!

---

# Source: https://lynxjs.org/blog/lynx-open-source-roadmap-2025.md

_March 19th, 2025_

# Lynx Roadmap 2025

<BlogAvatar list={['liushouqun']} />

[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.

---

# Source: https://lynxjs.org/blog/lynx-unlock-native-for-more.md

_March 5th, 2025_

# Lynx: Unlock Native for More

<BlogAvatar list={['huxpro', 'lynx']} />

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)

<center>
  <span>
    <small>
      TikTok's extensive use of Lynx
    </small>
  </span>
</center>

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();
}

```



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

### 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.

<VideoList
  videos={[
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/killers/ifr.mp4',
    title: 'IFR',
  },
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/killers/mts.mp4',
    title: 'MTS',
  },
]}
  playbackRate={1}
/>

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!

<VideoList
  videos={[
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/killers/ifr.mp4',
    title: 'IFR (0.25x)',
  },
  {
    src: 'https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/killers/mts.mp4',
    title: 'MTS (0.25x)',
  },
]}
  playbackRate={0.25}
/>

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.dev/), 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)

---

# Source: https://lynxjs.org/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 | - |
| Web | ❌ No | - |

**Description:** Represents an element in the main thread.

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/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`

```tsx
import { useState } from "@lynx-js/react";
import type { ScrollEvent } from "@lynx-js/types";

export function BackgroundDraggable({ size }: { size: number }) {
  const [posStyle, setPosStyle] = useState({ x: 0, y: 500 });

  let onScroll = (event: ScrollEvent) => {
    const detail = event.detail.scrollTop;
    const newPos = {
      x: 0,
      y: 500 - detail,
    };
    setPosStyle(newPos);
  };

  return (
    <view
      global-target="scroll"
      global-bindscroll={onScroll}
      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`

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

export function MainThreadDraggable({ size }: { size: number }) {
  let onScroll = (event: MainThread.TouchEvent & ScrollEvent) => {
    "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)`,
    );
  };

  return (
    <view
      global-target="scroll"
      main-thread:global-bindscroll={onScroll}
      style={{
        height: size + "px",
        width: 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

### 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 [count, setCount] = useState(1);

  const increaseBackgroundCount = async (event) => {
    'main thread';
    const result = await runOnBackground(() => {
      let count;
      setCount((c) => {
        return (count = c + 1);
      });
      return count;
    })();
    console.log(result);
  };
}
```

[`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

---

# Source: https://lynxjs.org/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

---

# Source: https://lynxjs.org/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 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.

---

# Source: https://lynxjs.org/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 |
| 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.

---

# Source: https://lynxjs.org/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 | - |
| Web | ✅ Yes | - |

**Description:** Directly set the attributes of the selected node.

---

# Source: https://lynxjs.org/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 | - |
| 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.

---

# Source: https://lynxjs.org/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

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/react/payment-details.md

# Tutorial: Payment Details

After completing the [Gallery](/guide/start/tutorial-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:

<Columns>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_cards.gif" alt="card" />

  1. Card Details
     - The card can perform flip animation
     - Here we'll learn how to use CSS animations to create smooth flip effects
</Columns>

<Columns>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_bankcards.gif" alt="card" />

  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

  <view style={{ height: '20px' }} />
</Columns>

<Columns>
  <div margin-top="20px">
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg" alt="card" />

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_pay.jpg" alt="card" />
  </div>

  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.
</Columns>

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!

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg" alt="card" width="40%" />

**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.

---

# Source: https://lynxjs.org/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.dev/api/plugin-api/compiler-hooks) and [Rspack - Compilation Hooks](https://rspack.dev/api/plugin-api/compilation-hooks) for more details.

[`tools.rspack.plugins`]: /api/rspeedy/rspeedy.tools.rspack.md#example-4

[BannerPlugin]: https://rspack.dev/plugins/webpack/banner-plugin

[DefinePlugin]: https://rspack.dev/plugins/webpack/define-plugin

[EnvironmentPlugin]: https://rspack.dev/plugins/webpack/environment-plugin

[ProvidePlugin]: https://rspack.dev/plugins/webpack/provide-plugin

---

# Source: https://lynxjs.org/ai/start/quick-start.md

# Source: https://lynxjs.org/rspeedy/start/quick-start.md

# Source: https://lynxjs.org/react/start/quick-start.md

# Source: https://lynxjs.org/guide/start/quick-start.md

# Source: https://lynxjs.org/rspeedy/start/quick-start.md

# Quick Start

Welcome to the Lynx documentation! We will create a Lynx project and start developing.

## System Requirements

- [Node.js 18](https://nodejs.org/en) or later.
  - Requires Node.js 18.19 when using TypeScript as configuration.

## Installation

<Steps>
  ### 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:

  <PackageManagerTabs command="create 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.

  <PlatformTabs queryKey="explorer-platform">
    <PlatformTabs.Tab platform="ios-simulator">
      We 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>**

      <PlatformTabs queryKey="ios-simulator-platform">
        <PlatformTabs.Tab platform="macos-arm64">
          Download [`LynxExplorer-arm64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/latest/download/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.
        </PlatformTabs.Tab>

        <PlatformTabs.Tab platform="macos-intel">
          Download [`LynxExplorer-x86_64.app.tar.gz`](https://github.com/lynx-family/lynx/releases/latest/download/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.
        </PlatformTabs.Tab>
      </PlatformTabs>
    </PlatformTabs.Tab>

    <PlatformTabs.Tab platform="android">
      Scan the QR code to download the pre-built app from the [GitHub Release](https://github.com/lynx-family/lynx/releases/latest).

      <QRCodeSVG style={{ border: '2px solid #fff' }} size={220} value="https://github.com/lynx-family/lynx/releases/latest/download/LynxExplorer-noasan-release.apk" />

      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.
      :::
    </PlatformTabs.Tab>

    <PlatformTabs.Tab platform="harmony">
      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/latest/download/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
      ```
    </PlatformTabs.Tab>
  </PlatformTabs>

  ### Start developing

  1. Navigate to the created project:

  ```bash
  cd <project-name>
  ```

  2. Install the NPM dependencies with package manager:

  <PackageManagerTabs command="install" />

  3. To start the development server, run:

  <PackageManagerTabs command="run 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.

  <Go example="hello-world" defaultFile="src/App.tsx" img="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/hello-world-showcase-ios.png" defaultEntryFile="dist/main.lynx.bundle" />

  <br />

  ### 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.
</Steps>

## 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.

<NextSteps.Root>
  <NextSteps.Step href="/guide/start/tutorial-gallery" title="Tutorial" description="Step-by-step walkthrough of building a Gallery page with Lynx" />

  <NextSteps.Step href="/react/thinking-in-reactlynx" title="Thinking in ReactLynx" description="Learn how to think in the ReactLynx framework" />
</NextSteps.Root>

### Describing UI

Lynx makes it easy to create rich UI using familiar Web technology.
Learn how to describe UI in the Lynx engine.

<NextSteps.Root>
  <NextSteps.Step href="/guide/ui/elements-components" title="Elements" description="Check out the built-in elements that Lynx provides" />

  <NextSteps.Step href="/guide/ui/styling" title="Styling" description="Learn how to apply different styles in Lynx" />
</NextSteps.Root>

<br />

<NextSteps.Root>
  <NextSteps.Step href="/guide/ui/layout" title="Layout" description="Layout your elements and Components" />

  <NextSteps.Step href="/guide/ui/scrolling" title="Scrolling" description="Learn how to use scrollable elements in Lynx" />
</NextSteps.Root>

### Integration

Learn how to integrate Lynx with existing iOS/Android/Web Apps.

<NextSteps.Root>
  <NextSteps.Step href="/guide/start/integrate-with-existing-apps" title="Integration" description="Integrate Lynx with existing Apps" />
</NextSteps.Root>

---

# Source: https://lynxjs.org/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:

<PackageManagerTabs command="install react-compiler-runtime@rc" />

2. Install the build-time dependencies for React Compiler:

<PackageManagerTabs command="install -D @rsbuild/plugin-babel 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.

---

# Source: https://lynxjs.org/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.

<PackageManagerTabs command="install 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.

---

# Source: https://lynxjs.org/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.

To configure [Vitest](https://vitest.dev/), you can use `@lynx-js/react/testing-library/vitest-config` to create a Vitest configuration. You can use the `mergeConfig` method to merge it with other configurations.

```js title=vitest.config.js
import { defineConfig, mergeConfig } from 'vitest/config';
import { createVitestConfig } from '@lynx-js/react/testing-library/vitest-config';

const defaultConfig = await createVitestConfig();
const config = defineConfig({
  test: {
    // ...
  },
});

export default mergeConfig(defaultConfig, config);
```

## Examples

### 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).

---

# Source: https://lynxjs.org/guide/ui/layout/relative-layout.md

# Relative Layout <NoWeb />

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.

<center>
  <img width="70%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/relative_demo_1.png" />
</center>

**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

<center>
  <img width="100%" src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/layout/lynx_layout_relative_demo.png" />
</center>

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)

---

# Source: https://lynxjs.org/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.dev/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

---

# Source: https://lynxjs.org/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

---

# Source: https://lynxjs.org/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 <AndroidOnly />
, 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`

{' '}

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: true
bounces?: boolean;
```

Enable bounce effect

### `enable-scroll`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: true
'enable-scroll'?: boolean;
```

Enable dragging

### `initial-scroll-offset`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.17
</VersionBadge>

```tsx
// @defaultValue: 0
'initial-scroll-offset'?: number;
```

Initial scroll position, only effective once, in PX

### `initial-scroll-to-index`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  2.17
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: 0
'lower-threshold'?: number;
```

Set upper threshold to bindscrolltoupper event.

### `scroll-bar-enable`

{' '}

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
// @defaultValue: true
'scroll-bar-enable'?: boolean;
```

Enable scrollbar

### `scroll-orientation`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  3.0
</VersionBadge>

```tsx
// @defaultValue: 'vertical'
'scroll-orientation'?: 'vertical' | 'horizontal';
```

Replacement of scroll-x and scroll-y

### `upper-threshold`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  1.6
</VersionBadge>

```tsx
bindcontentsizechanged = (e: ContentSizeChangedEvent) => {};
```

This event is triggered when the scrollview's content size changed.

### `bindscroll`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```tsx
bindscroll = (e: ScrollEvent) => {};
```

This event is triggered when the scrollview is scrolling.

### `bindscrollend`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

<VersionBadge>
  1.6
</VersionBadge>

```tsx
bindscrollend = (e: ScrollEndEvent) => {};
```

This event is triggered when the scrollview's scroll ended.

### `bindscrolltolower`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  1.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```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`

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```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`

<AndroidOnly />

<IOSOnly />

<ClayOnly />

<HarmonyOnly />

```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

---

# Source: https://lynxjs.org/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.

<table rules="none" align="center" width="100%" style={{ tableLayout: 'fixed' }}>
  <thead align="center">
    <th colSpan={2}>
      <span style={{ fontWeight: 'bold' }}>
        non-scrollable element
      </span>
    </th>

    <th colSpan={2}>
      <span style={{ fontWeight: 'bold' }}>
        scrollable element
      </span>
    </th>
  </thead>

  <tr>
    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/style-guide-overflow-visible.png" style={{ width: '70%', aspectRatio: '1/1' }} />
      </center>
    </td>

    <td style={{ padding: '15px 15px 15px 0' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/style-guide-overflow-hidden.png" style={{ width: '70%', aspectRatio: '1/1' }} />
      </center>
    </td>

    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-scroll-orientation-vertical.gif" style={{ width: '70%', aspectRatio: '1/1' }} />
      </center>
    </td>

    <td style={{ padding: '15px 15px 15px 0' }}>
      <center>
        <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/guide-scroll-orientation-horizontal.gif" style={{ width: '70%', aspectRatio: '1/1' }} />
      </center>
    </td>
  </tr>

  <tr>
    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <span>
          Content overflow has occurred.
        </span>
      </center>
    </td>

    <td style={{ padding: '15px 15px 15px 0' }}>
      <center>
        <span>
          crop the overflowing content through 

          <code>overflow: hidden</code>
        </span>
      </center>
    </td>

    <td style={{ padding: '15px 0 15px 15px' }}>
      <center>
        <span>
          <code>scroll-orientation: vertical</code>

           scrollable element 
        </span>
      </center>
    </td>

    <td style={{ padding: '15px 15px 15px 0' }}>
      <center>
        <span>
          <code>scroll-orientation: horizontal</code>

           scrollable element
        </span>
      </center>
    </td>
  </tr>
</table>

<Details title={<span>Doesn't support<code>overflow:scroll</code>for scrolling effect !</span>}>
  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.
</Details>

## 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)

---

# Source: https://lynxjs.org/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 | - |
| Web | ✅ Yes | - |

**Description:** Execute all submitted operations.

---

# Source: https://lynxjs.org/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 | - |
| Web | ✅ Yes | - |

**Description:** Select the first node that matches the specified selector in the descendants of the root node specified in `SelectorQuery`.

---

# Source: https://lynxjs.org/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 | - |
| Web | ✅ Yes | - |

**Description:** Gets a reference to the specified node in order to call its methods or get its properties.

---

# Source: https://lynxjs.org/guide/interaction/storage.md

---

# Source: https://lynxjs.org/rspeedy/styling.md

# Source: https://lynxjs.org/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)

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/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:

<PackageManagerTabs command="install @tanstack/react-router url-search-params-polyfill" />

Install devDependencies:

<PackageManagerTabs command="install @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.

<Details title="❓ Why use @lynx-js/react/compat">
  ReactLynx offers React 18 API compatibility via `@lynx-js/react/compat`,
  providing crucial APIs such as `React.startTransition` required by TanStack
  Router.
</Details>

```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} />;
}

```

---

# Source: https://lynxjs.org/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:

<p align="center">
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/inline-image-demo.png" width="300" />
</p>

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();
}

```

---

# Source: https://lynxjs.org/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`
 <AndroidOnly />

```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.

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```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];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```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));
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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));
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

## 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/big-font-flow.png" width="75%" height="75%" />

### 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(
          {
            // @ts-expect-error TODO(types): support `query` in `@lynx-js/types`
            query: true,
            id: true,
          },
          resolve,
        )
        .exec();
    });

    Promise.all(
      resArray.map((element) => {
        return new Promise<{
          top: number;
          left: number;
          width: number;
          height: number;
          id: string;
        }>((resolve) => {
          // @ts-expect-error TODO(types): support `query` in `@lynx-js/types`
          element.query
            .selectRoot()
            .invoke({
              method: "boundingClientRect",
              success: (res: {
                top: number;
                left: number;
                width: number;
                height: number;
                id: string;
              }) => {
                resolve(res);
              },
            })
            .exec();
        });
      }),
    ).then((values) => {
      textsInfo = [...values].map(({ top, left, width, height, id }) => ({
        id: String(id),
        left: Number(left),
        top: Number(top),
        width: Number(width),
        height: Number(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>

---

# Source: https://lynxjs.org/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`

```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`

```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`

{' '}

<AndroidOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
bounces?: boolean;
```

Bounce effect for iOS

### `confirm-type`

{' '}

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: 'done'
'confirm-type'?: 'search' | 'send' | 'go' | 'done' | 'next';
```

The type of confirm button

### `disabled`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.5
</VersionBadge>

```tsx
// @defaultValue: false
disabled?: boolean;
```

Interaction enabled

### `enable-scroll-bar`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.6
</VersionBadge>

```tsx
// @defaultValue: false
'enable-scroll-bar'?: boolean;
```

Whether to show scroll bar, on HarmonyOS, the scroll bar will always be shown

### `input-filter`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: undefined
'input-filter'?: string;
```

Filter the input content and process it in the form of regular expressions

### `ios-auto-correct`

{' '}

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'ios-auto-correct'?: boolean;
```

Auto correct input content on iOS

### `ios-spell-check`

{' '}

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'ios-spell-check'?: boolean;
```

Check spelling issue on iOS

### `line-spacing`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: undefined
'line-spacing'?: number | any | any;
```

Line spacing

### `maxlength`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: 140
maxlength?: number;
```

Max input length

### `maxlines`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: undefined
maxlines?: number;
```

Max input lines

### `placeholder`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
placeholder?: string;
```

Placeholder

### `readonly`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: false
readonly?: boolean;
```

Readonly

### `show-soft-input-on-focus`

{' '}

<AndroidOnly />

<IOSOnly />

<VersionBadge>
  3.4
</VersionBadge>

```tsx
// @defaultValue: true
'show-soft-input-on-focus'?: boolean;
```

Show soft input keyboard while focused

### `type`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```ts

lynx.createSelectorQuery()
.select('#id')
.invoke({
method: 'blur',
success: function (res) {},
fail: function (res) {},
})
.exec();

```

Release focus

### `focus`

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```ts

lynx.createSelectorQuery()
     .select('#id')
     .invoke({
      method: 'focus',
      success: function (res) {},
      fail: function (res) {},
    })
    .exec();

```

Require focus

### `getValue`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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`

{' '}

<AndroidOnly />

<IOSOnly />

<HarmonyOnly />

<VersionBadge>
  3.4
</VersionBadge>

```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

---

# Source: https://lynxjs.org/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.

<Details title="❓ 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.
</Details>

## 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

---

# Source: https://lynxjs.org/guide/devtool/trace.md

<style>
  {`
    .full_image {
      width: 750px;
      margin: 20px;
    }
    `}
</style>


# 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace_render_pipeline_latest.png" alt="Trace Render Pipeline" className="full_image" />

### 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-scheduling.png" alt="Trace Task Scheduling" className="full_image" />

### 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/element-render-analysis-latest.png" alt="Element" className="full_image" />

- **[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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/nativemodule-invoke-flow.png" alt="NativeModules" className="full_image" />

- **Smoothness Analysis**: Use flame charts of task durations to quickly locate the root causes of jank, helping you optimize animations and interactions.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/trace-frame.png" alt="Trace Frame" className="full_image" />

## Next Steps

<NextSteps.Root>
  <NextSteps.Step href="/guide/devtool/trace/record-trace" title="Record Trace" description="Learn how to record a trace" />
</NextSteps.Root>

## Compatibility


**Compatibility Table**
**Query:** `devtool.trace`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 3.4 | - |
| iOS | 3.4 | - |
| HarmonyOS | 3.4 | - |

**Description:** Trace Tool

---

# Source: https://lynxjs.org/ai/start/tutorial-gallery.md

# Source: https://lynxjs.org/rspeedy/start/tutorial-gallery.md

# Source: https://lynxjs.org/react/start/tutorial-gallery.md

# Source: https://lynxjs.org/guide/start/tutorial-gallery.md

# 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:

<CodeFold toggle>
  ```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;
    }
  }
  ```
</CodeFold>

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](/guide/start/tutorial-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.

---

# Source: https://lynxjs.org/guide/start/tutorial-payment-details.md

# Tutorial: Payment Details

After completing the [Gallery](/guide/start/tutorial-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:

<Columns>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_cards.gif" alt="card" />

  1. Card Details
     - The card can perform flip animation
     - Here we'll learn how to use CSS animations to create smooth flip effects
</Columns>

<Columns>
  <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_bankcards.gif" alt="card" />

  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

  <view style={{ height: '20px' }} />
</Columns>

<Columns>
  <div margin-top="20px">
    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg" alt="card" />

    <img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_pay.jpg" alt="card" />
  </div>

  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.
</Columns>

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!

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/payment_amount.jpeg" alt="card" width="40%" />

**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.

---

# Source: https://lynxjs.org/ai/start/tutorial-product-detail.md

# Source: https://lynxjs.org/rspeedy/start/tutorial-product-detail.md

# Source: https://lynxjs.org/react/start/tutorial-product-detail.md

# Source: https://lynxjs.org/guide/start/tutorial-product-detail.md

# 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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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`

```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

---

# Source: https://lynxjs.org/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.

---

# Source: https://lynxjs.org/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:

<PackageManagerTabs
  command={{
  npm: `npx upgrade-rspeedy@latest`,
  pnpm: `pnpm dlx upgrade-rspeedy@latest`,
  bun: `bunx upgrade-rspeedy@latest`,
  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:

<PackageManagerTabs
  command={{
  npm: `npx upgrade-rspeedy@0.8.3`,
  pnpm: `pnpm dlx upgrade-rspeedy@0.8.3`,
  bun: `bunx upgrade-rspeedy@0.8.3`,
  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
```

---

# Source: https://lynxjs.org/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:

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```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];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```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);
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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%' })
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

You can update this data later through [`LynxView.updateData()`] (or [`LynxContext.updateData()`] on HarmonyOS) when needed:

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```objc {2}
    LynxUpdateMeta* meta = [LynxUpdateMeta init];
    meta.data = __YOUR_DATA__;
    [lynxView updateData:meta];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```java {2}
    LynxUpdateMeta.Builder builder = new LynxUpdateMeta.Builder();
    builder.setUpdatedData(__YOUR_DATA__);
    LynxUpdateMeta meta = builder.build();
    lynxView.updateMetaData(meta);
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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%' })
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

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):

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    ```objc
    LynxUpdateMeta *meta = [[LynxUpdateMeta alloc] init];

    [lynxView updateData:meta];
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    ```java
    LynxUpdateMeta meta = new LynxUpdateMeta();

    lynxView.updateMetaData(meta);
    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="harmony">
    ```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%' })
      }
    }
    ```
  </PlatformTabs.Tab>
</PlatformTabs>

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

---

# Source: https://lynxjs.org/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)

<Steps>
  ### 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.

  <Go highlight="{11,19,24}" example="local-storage" defaultFile="src/App.tsx" img="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/native-modules-demo-preview.png" />

  ### Write Your Native Platform Code

  Now, you can start writing the native platform code.

  <PlatformTabs queryKey="platform">
    <PlatformTabs.Tab platform="ios">
      <NativeModuleIOS />
    </PlatformTabs.Tab>

    <PlatformTabs.Tab platform="android">
      <NativeModuleAndroid />
    </PlatformTabs.Tab>

    <PlatformTabs.Tab platform="harmony">
      <NativeModuleHarmony />
    </PlatformTabs.Tab>
  </PlatformTabs>
</Steps>

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.

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="android">
    When 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);

    ```
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="ios">
    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];

    ```
  </PlatformTabs.Tab>
</PlatformTabs>

---

# Source: https://lynxjs.org/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:

<PackageManagerTabs command="add @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.

---

# Source: https://lynxjs.org/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

<PackageManagerTabs command="install 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.

---

# Source: https://lynxjs.org/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.

<VersionTable type="developing" />

## Release candidate version

Before the official release, the Lynx version undergoes comprehensive testing in various complex application scenarios. You can find current release candidate here.

<VersionTable type="release_candidate" />

## Latest version

It is recommended that new applications using Lynx adopt the latest version.

<VersionTable type="latest" />

## Previous versions

<VersionTable type="previous" />

---

# Source: https://lynxjs.org/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`
 <Badge text="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`
 <AndroidOnly />

```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.
:::

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/enable-exposure-ui-clip-en.png" width="100%" height="100%" />

### `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`
 <IOSOnly />

```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
```

Specifies 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.
:::

### `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][]
```

Specifies 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][]
```

Specifies 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/doc/consume_slide_event.jpg" width="70%" height="70%" />

### `event-through`

```ts
// DefaultValue: false
event-through?: boolean
```

Specifies 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][]
```

Specifies 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.

<img src="https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/plugin/static/event-through-active-regions.png" width="100%" height="100%" />

### `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`
 <IOSOnly />

```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, // Specifies whether to consider animation properties when calculating position on iOS; the default is false.
      androidEnableTransformProps: true, // Specifies whether to consider the transform attribute when calculating the position on Android. The default value is false.
      relativeTo: null, // Specify the reference node, relative to LynxView by default.
    },
    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

---

# Source: https://lynxjs.org/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).

---

# Source: https://lynxjs.org/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.

<Steps>
  ### Step 1: Install

  Run the installation command...

  ### Step 2: Configure

  Update your config file...
</Steps>

```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`.

<PackageManagerTabs command="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.

<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>

```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.

<PlatformTabs queryKey="platform">
  <PlatformTabs.Tab platform="ios">
    iOS specific instructions...
  </PlatformTabs.Tab>

  <PlatformTabs.Tab platform="android">
    Android specific instructions...
  </PlatformTabs.Tab>
</PlatformTabs>

```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.

---

# Source: https://lynxjs.org/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

<PackageManagerTabs command="install 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.